واجهة برمجة تطبيقات مهام Nano Banana والتكامل والاستخدام

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

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

يمكن استخدام واجهة برمجة تطبيقات مهام Nano Banana لاستعلام نتائج واجهة برمجة تطبيقات صور Nano Banana. لمزيد من المعلومات حول كيفية استخدام واجهة برمجة تطبيقات صور Nano Banana، يرجى الرجوع إلى الوثيقة واجهة برمجة تطبيقات صور Nano Banana. سنأخذ مثالاً على معرف المهمة الذي تم إرجاعه من خدمة واجهة برمجة تطبيقات صور Nano Banana، ونوضح كيفية استخدام هذه الواجهة. لنفترض أن لدينا معرف مهمة: 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,
  "started_at": 1757183036.847,
  "finished_at": 1757183048.147,
  "elapsed": 11.3,
  "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: معلومات الاستجابة في المهمة.
created_at: وقت إنشاء المهمة، طابع زمني Unix (ثوانٍ، عائم).
started_at: وقت بدء تنفيذ المهمة، طابع زمني Unix (ثوانٍ، عائم).
finished_at: وقت إكمال المهمة، طابع زمني Unix (ثوانٍ، عائم). لا يتم إرجاع هذا الحقل إذا لم تكتمل المهمة.
elapsed: الوقت المستغرق لتنفيذ المهمة، بوحدة الثواني (عائم، يحتفظ بـ 3 أرقام عشرية). لا يتم إرجاع هذا الحقل إذا لم تكتمل المهمة.

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

هذا مخصص لاستعلام تفاصيل المهام لعدة معرفات، وما يميزها هو أنه يجب اختيار 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,
      "started_at": 1757183036.847,
      "finished_at": 1757183048.147,
      "elapsed": 11.3,
      "credential_id": "097b2987-62f4-4ac0-b0cc-aed41e372a07",
      "request": {
        "action": "generate",
        "prompt": "قط سيامي أبيض"
      },
      "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": "قط سيامي أبيض",
            "image_url": "https://platform.cdn.acedata.cloud/nanobanana/7e7bd000-698a-4e14-bb2d-3db61237e4bb.png"
          }
        ]
      }
    }
  ],
  "count": 1
}

返回结果一共有多个字段，其中 items 是包含了批量任务的具体详情信息，每个任务的具体信息与上文的字段一样，字段信息如下。

items，批量任务的所有具体详情信息。它是一个数组，每个数组的元素和上文查询单个任务的返回结果格式是一样的。
count，此处批量查询任务的个数。

错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：

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

错误响应示例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "فشل في الاسترجاع"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

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

البداية

دردشة الذكاء الاصطناعي

صورة الذكاء الاصطناعي

فيديو الذكاء الاصطناعي

الصوت الذكي

الويب والبيانات

CAPTCHA

الهوية

وكيل

متقدم

Coding

واجهة برمجة تطبيقات مهام Nano Banana والتكامل والاستخدام

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

مثال على صورة المهمة

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

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

CURL

بايثون

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

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

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

错误处理

错误响应示例

结论

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

​مثال على صورة المهمة

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

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

​CURL

​بايثون

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

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

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

​错误处理

​错误响应示例

​结论

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

مثال على صورة المهمة

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

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

CURL

بايثون

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

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

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

错误处理

错误响应示例

结论