الانتقال إلى المحتوى الرئيسي
الوظيفة الرئيسية لواجهة برمجة تطبيقات مهام نانو موز هي استعلام حالة تنفيذ المهمة من خلال إدخال معرف المهمة الذي تم إنشاؤه بواسطة واجهة برمجة تطبيقات صور نانو موز. ستتناول هذه الوثيقة تفاصيل تكامل واجهة برمجة تطبيقات مهام نانو موز، لمساعدتك على دمجها بسهولة والاستفادة الكاملة من القوة الكبيرة لهذه الواجهة. من خلال واجهة برمجة تطبيقات مهام نانو موز، يمكنك بسهولة استعلام حالة تنفيذ المهام من واجهة برمجة تطبيقات صور نانو موز.

​
مثال على الطلب

يمكن استخدام واجهة برمجة تطبيقات مهام نانو موز لاستعلام نتائج واجهة برمجة تطبيقات صور نانو موز. لمزيد من المعلومات حول كيفية استخدام واجهة برمجة تطبيقات صور نانو موز، يرجى الرجوع إلى الوثيقة واجهة برمجة تطبيقات صور نانو موز. سنأخذ مثالاً على معرف المهمة الذي تم إرجاعه من خدمة واجهة برمجة تطبيقات صور نانو موز، ونوضح كيفية استخدام هذه الواجهة. لنفترض أن لدينا معرف مهمة: 4d320ead-4af4-4a55-8f3e-f2afebdf4fd0، وسنوضح كيفية تمرير معرف المهمة.

​
مثال على المهمة

​
إعداد رأس الطلب وجسم الطلب

رؤوس الطلب تشمل:
  • accept: تحديد استلام نتائج الاستجابة بتنسيق JSON، هنا يتم ملؤه بـ application/json.
  • authorization: مفتاح استدعاء الواجهة، يمكن اختياره مباشرة بعد التقديم.
جسم الطلب يشمل:
  • id: معرف المهمة المرفوعة.
  • action: طريقة تنفيذ العملية على المهمة.
الإعداد كما هو موضح في الصورة أدناه:

​
مثال على الكود

يمكن ملاحظة أنه تم إنشاء أكواد بلغات مختلفة تلقائيًا على الجانب الأيمن، كما هو موضح في الصورة:

بعض أمثلة الكود كما يلي:

​
CURL

curl -X POST 'https://api.acedata.cloud/nano-banana/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0",
  "action": "retrieve"
}'

​
بايثون

import requests

url = "https://api.acedata.cloud/nano-banana/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0",
    "action": "retrieve"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

​
مثال على الاستجابة

بعد نجاح الطلب، ستقوم الواجهة بإرجاع تفاصيل هذه المهمة. على سبيل المثال: 
{
  "_id": "68bc7c3c550a4144a53d0e24",
  "id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0",
  "api_id": "9d8a117e-31ca-4322-a0fd-1771296ec610",
  "application_id": "8afd681a-2a4e-4265-aecb-43970094c019",
  "created_at": 1757183036.787,
  "credential_id": "097b2987-62f4-4ac0-b0cc-aed41e372a07",
  "request": {
    "action": "generate",
    "prompt": "a white siamese cat"
  },
  "trace_id": "7ba1f1e8-0ef8-450d-8bb2-b5c3bf1ea319",
  "type": "images",
  "user_id": "b87f67c1-b04f-4332-99a1-7a5e651331c6",
  "response": {
    "success": true,
    "task_id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0",
    "trace_id": "7ba1f1e8-0ef8-450d-8bb2-b5c3bf1ea319",
    "data": [
      {
        "prompt": "a white siamese cat",
        "image_url": "https://platform.cdn.acedata.cloud/nanobanana/7e7bd000-698a-4e14-bb2d-3db61237e4bb.png"
      }
    ]
  }
}
تتضمن النتيجة عدة حقول، حيث أن حقل request هو جسم الطلب عند بدء المهمة، بينما حقل response هو جسم الاستجابة الذي يتم إرجاعه بعد إكمال المهمة. توضيح الحقول كما يلي.
  • id: معرف هذه المهمة، يستخدم لتحديد هذه المهمة بشكل فريد.
  • request: معلومات الطلب في المهمة.
  • response: معلومات الاستجابة في المهمة.

​
عمليات الاستعلام الجماعي

هذا مخصص لاستعلام تفاصيل المهام لعدة معرفات، وما يميزها عن السابقة هو أنه يجب اختيار action كـ retrieve_batch. جسم الطلب يشمل:
  • ids: مصفوفة معرفات المهام المرفوعة.
  • action: طريقة تنفيذ العملية على المهام.
مثال كما يلي: 
curl -X POST 'https://api.acedata.cloud/nano-banana/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed","1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed"],
  "action": "retrieve_batch"
}'

​
مثال على الاستجابة

بعد نجاح الطلب، ستقوم الواجهة بإرجاع تفاصيل جميع المهام الجماعية. على سبيل المثال: 
{
  "items": [
    {
      "_id": "68bc7c3c550a4144a53d0e24",
      "id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0",
      "api_id": "9d8a117e-31ca-4322-a0fd-1771296ec610",
      "application_id": "8afd681a-2a4e-4265-aecb-43970094c019",
      "created_at": 1757183036.787,
      "credential_id": "097b2987-62f4-4ac0-b0cc-aed41e372a07",
      "request": {
        "action": "generate",
        "prompt": "a white siamese cat"
      },
      "trace_id": "7ba1f1e8-0ef8-450d-8bb2-b5c3bf1ea319",
      "type": "images",
      "user_id": "b87f67c1-b04f-4332-99a1-7a5e651331c6",
      "response": {
        "success": true,
        "task_id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0",
        "trace_id": "7ba1f1e8-0ef8-450d-8bb2-b5c3bf1ea319",
        "data": [
          {
            "prompt": "a white siamese cat",
            "image_url": "https://platform.cdn.acedata.cloud/nanobanana/7e7bd000-698a-4e14-bb2d-3db61237e4bb.png"
          }
        ]
      }
    }
  ],
  "count": 1
}
تتضمن النتيجة عدة حقول، حيث أن items تحتوي على تفاصيل المهام الجماعية، ومعلومات كل مهمة تتشابه مع الحقول المذكورة أعلاه، وتفاصيل الحقول كما يلي.
  • items: جميع تفاصيل المهام الجماعية. إنها مصفوفة، حيث أن كل عنصر في المصفوفة له نفس تنسيق نتيجة الاستعلام عن مهمة واحدة كما هو مذكور أعلاه.
  • count: عدد المهام في استعلام المجموعة.

​
معالجة الأخطاء

عند استدعاء واجهة برمجة التطبيقات (API)، إذا واجهت خطأ، ستقوم واجهة برمجة التطبيقات بإرجاع رمز الخطأ والمعلومات المناسبة. على سبيل المثال:
  • 400 token_mismatched：طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 400 api_not_implemented：طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 401 invalid_token：غير مصرح، رمز التفويض غير صالح أو مفقود.
  • 429 too_many_requests：عدد كبير جداً من الطلبات، لقد تجاوزت الحد الأقصى لمعدل الطلبات.
  • 500 api_error：خطأ في الخادم الداخلي، حدث خطأ ما على الخادم.

​
مثال على استجابة الخطأ

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
الاستنتاج

من خلال هذه الوثيقة، لقد تعرفت على كيفية استخدام واجهة برمجة تطبيقات Nano Banana Tasks للاستعلام عن تفاصيل مهمة واحدة أو مجموعة من المهام. نأمل أن تساعدك هذه الوثيقة في التوصيل واستخدام واجهة برمجة التطبيقات بشكل أفضل. إذا كان لديك أي أسئلة، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.