واجهة برمجة تطبيقات صور نانو موز (Nano Banana Images API) - تعليمات الدمج

​

عملية التقديم

📘 الوثائق الكاملة: واجهة برمجة تطبيقات صور نانو موز →

​

نظرة عامة على الواجهة

• عنوان URL الأساسي: https://api.acedata.cloud
• نقطة النهاية: POST /nano-banana/images
• طريقة المصادقة: يتم تضمين authorization: Bearer {token} في رأس HTTP
• رؤوس الطلب:
  • accept: application/json
  • content-type: application/json
• الإجراء (action):
  • generate: توليد صورة بناءً على نص التوجيه
  • edit: تحرير الصورة بناءً على الصورة المعطاة
• النموذج (model) (اختياري):
  • nano-banana (افتراضي): يعتمد على صورة Gemini 2.5 Flash، سريع التكلفة، منخفض
  • nano-banana-2-lite: يعتمد على صورة Gemini 3.1 Flash Lite، يدعم فقط 1K، سريع في التوليد
  • nano-banana-2: يعتمد على صورة Gemini 3.1 Flash Image Preview، جودة احترافية + سرعة فلاش
  • nano-banana-pro: يعتمد على صورة Gemini 3 Pro Image Preview، أعلى جودة
  • nano-banana:official، nano-banana-2-lite:official، nano-banana-2:official، nano-banana-pro:official: النسخ الرسمية للنماذج، جودة الصورة واستقرار أفضل، تختلف في التسعير
• الاستدعاء غير المتزامن: اختياري، عبر callback_url لاستقبال إشعارات إكمال المهمة والنتائج
• عدد الصور: اختياري، عبر count لتحديد 1–4 صور، الافتراضي 1 صورة؛ يتم توليد كل صورة من خلال استدعاء مستقل؛ الفشل الفني العادي أو الرفض الأمني من قبل المزود يؤثر فقط على الاستدعاء المعني، بينما تعود الصور الناجحة الأخرى كالمعتاد، ويتم احتساب الرسوم بناءً على عدد الصور الناجحة الفعلي

​

البدء السريع: توليد صورة (action=generate)

​

مثال على الطلب (cURL)

curl -X POST 'https://api.acedata.cloud/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "model": "nano-banana-pro",
    "prompt": "صورة قريبة واقعية لشخص مسن ياباني يصنع الفخار مع تجاعيد عميقة محفورة من الشمس وابتسامة دافئة وعارفة. إنه يقوم بفحص وعاء شاي تم تلميعه حديثًا بعناية. الإعداد هو ورشته الريفية المشرقة تحت الشمس. المشهد مضاء بضوء الساعة الذهبية الناعم المتدفق من خلال نافذة، مما يبرز النسيج الدقيق للطين. تم التقاط الصورة بعدسة بورتريه 85 مم، مما يؤدي إلى خلفية ناعمة ومشوشة (بوكيه). المزاج العام هادئ وماهر. اتجاه الصورة عمودي.",
    "count": 1
  }'

​

مثال على الطلب (Python)

import requests

url = "https://api.acedata.cloud/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "generate",
    "model": "nano-banana-pro",
    "prompt": (
        "صورة قريبة واقعية لشخص مسن ياباني يصنع الفخار "
        "مع تجاعيد عميقة محفورة من الشمس وابتسامة دافئة وعارفة. إنه يقوم بفحص "
        "وعاء شاي تم تلميعه حديثًا بعناية. الإعداد هو ورشته الريفية المشرقة تحت "
        "الشمس. المشهد مضاء بضوء الساعة الذهبية الناعم المتدفق من خلال نافذة، "
        "مما يبرز النسيج الدقيق للطين. تم التقاط الصورة بعدسة بورتريه 85 مم، "
        "مما يؤدي إلى خلفية ناعمة ومشوشة (بوكيه). المزاج العام هادئ وماهر. "
        "اتجاه الصورة عمودي."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

​

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

{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "صورة قريبة واقعية لشخص مسن ياباني يصنع الفخار مع تجاعيد عميقة محفورة من الشمس وابتسامة دافئة وعارفة. إنه يقوم بفحص وعاء شاي تم تلميعه حديثًا بعناية. الإعداد هو ورشته الريفية المشرقة تحت الشمس. المشهد مضاء بضوء الساعة الذهبية الناعم المتدفق من خلال نافذة، مما يبرز النسيج الدقيق للطين. تم التقاط الصورة بعدسة بورتريه 85 مم، مما يؤدي إلى خلفية ناعمة ومشوشة (بوكيه). المزاج العام هادئ وماهر. اتجاه الصورة عمودي.",
      "image_url": "https://platform2.cdn.acedata.cloud/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336.png"
    }
  ]
}

​

شرح الحقول

• success: هل كانت هذه الطلبية ناجحة.
• task_id: معرف المهمة.
• trace_id: معرف تتبع السلسلة، لتسهيل استكشاف الأخطاء.
• count: عدد الصور المطلوبة للتوليد أو التحرير، يدعم 1–4، الافتراضي 1. تحتوي data فقط على الصور التي تم توليدها بنجاح، ويتم احتساب الرسوم بناءً على عدد الصور التي تم إرجاعها فعليًا. يتم فرض استخدام سياسة الأمان الأصلية للمزود على كل استدعاء توليد؛ إذا تم رفض استدعاء معين، فلن يؤثر ذلك على الاستدعاءات الناجحة الأخرى، وإذا تم رفض جميع الاستدعاءات، سيتم إرجاع 403.
• data[]: قائمة النتائج.
  • prompt: نص التوجيه المستخدم للتوليد (إعادة عرض).
  • image_url: رابط URL المباشر للصورة المولدة.

ملاحظة: /nano-banana/images تحتاج فقط إلى action و prompt لتوليد الصورة

​

تحرير الصورة (action=edit)

​

مثال على الطلب (cURL)

curl -X POST 'https://api.acedata.cloud/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "edit",
    "prompt": "دع هذا الرجل يرتدي هذا القميص",
    "image_urls": [
      "https://cdn.acedata.cloud/v8073y.png",
      "https://cdn.acedata.cloud/44xlah.png"
    ],
    "count": 1
  }'

​

مثال الطلب (بايثون)

import requests

url = "https://api.acedata.cloud/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "edit",
    "prompt": "دع هذا الرجل يرتدي هذا القميص",
    "image_urls": [
        "https://cdn.acedata.cloud/v8073y.png",
        "https://cdn.acedata.cloud/44xlah.png"
    ],
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

​

مثال الاستجابة الناجحة

{
  "success": true,
  "task_id": "93f11baf-347b-4bb4-9520-8653cb46d6a3",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": [
    {
      "prompt": "دع هذا الرجل يرتدي هذا القميص",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png"
    }
  ]
}

​

شرح الحقول

• image_urls[]: قائمة URL للصور المراد تعديلها (يجب أن تكون متاحة للوصول العام). يمكن إرسال عدة صور، وستقوم الخدمة بدمج هذه المواد مع prompt لإكمال التعديل.
• باقي الحقول كما في استجابة “توليد الصور”.

​

ردود الفعل غير المتزامنة (اختياري، موصى به)

1. أضف callback_url في جسم الطلب، مثل عنوان Webhook الخاص بخادمك (يجب أن يكون متاحًا للوصول العام، ويدعم POST JSON).
2. ستقوم API بإرجاع استجابة تحتوي على task_id على الفور (أو تحتوي على نتيجة أساسية).
3. عند الانتهاء من المهمة، ستقوم المنصة بإرسال JSON الكامل إلى callback_url بطريقة POST. يمكنك ربط الطلب بالنتيجة من خلال task_id.

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "قط سيامي أبيض",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
    }
  ]
}

​

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

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

​

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

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "خطأ داخلي في الخادم."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

مقارنة المعلمات والملاحظات

• مطلوب: action، prompt
• مخصص للتعديل: image_urls (مصفوفة، على الأقل 1 عنصر)
• اختياري: model (افتراضي nano-banana، يمكن اختيار nano-banana-2-lite، nano-banana-2، nano-banana-pro، أو النسخ الرسمية المقابلة :official)، aspect_ratio (نسبة العرض إلى الارتفاع، مثل 1:1، 16:9)، resolution (الدقة، مثل 1K، 2K، 4K؛ nano-banana-2-lite يدعم فقط 1K)، callback_url (للاستدعاء غير المتزامن)
• الرؤوس: يجب تقديم authorization: Bearer {token}؛ يُنصح بتعيين accept إلى application/json
• قابلية الوصول إلى الصور: يجب أن تكون image_urls روابط مباشرة متاحة للوصول العام (HTTP/HTTPS)، يُنصح باستخدام HTTPS
• التماثل والتتبع: احتفظ بـ task_id و trace_id، لتسهيل استكشاف الأخطاء وإصلاحها وربط النتائج