الانتقال إلى المحتوى الرئيسي
تقدم هذه الوثيقة شرحًا لتكامل واستخدام واجهة برمجة تطبيقات صور نانو موز. تدعم هذه الواجهة قدرتين: توليد الصور (generate) و تحرير الصور (edit).

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

قبل الاستخدام، يرجى الدخول إلى واجهة برمجة تطبيقات صور نانو موز في منصة Ace Data Cloud والنقر على Acquire لتقديم طلب فتح. عادةً ما يتوفر حد مجاني للاستخدام عند التقديم لأول مرة. بعد الانتهاء من الفتح، يمكنك الحصول على رمز Bearer Token لاستخدامه في استدعاء واجهة برمجة التطبيقات.

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

  • عنوان 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: يعتمد على معاينة صورة Gemini 3.1 Flash، جودة احترافية + سرعة Flash
    • nano-banana-pro: يعتمد على معاينة صورة Gemini 3 Pro، أعلى جودة
  • الاستدعاء غير المتزامن: اختياري، عبر callback_url لاستقبال إشعارات إكمال المهمة والنتائج

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

الحد الأدنى من المعلمات المطلوبة: action، prompt عندما ترغب فقط في توليد صورة بناءً على نص التوجيه، قم بتعيين action إلى generate، وقدم نص prompt واضح.

​
مثال على الطلب (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",
    "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",
    "prompt": (
        "صورة قريبة واقعية لشخص مسن ياباني يصنع الفخار "
        "مع تجاعيد عميقة محفورة من الشمس وابتسامة دافئة وعارفة. إنه يقوم بفحص "
        "وعاء شاي تم تلميعه حديثًا بعناية. الإعداد هو ورشته الريفية المشرقة تحت "
        "الشمس. المشهد مضاء بضوء الساعة الذهبية الناعم المتدفق من خلال "
        "نافذة، مما يبرز القوام الدقيق للطين. تم التقاط الصورة بعدسة بورتريه 85 مم، "
        "مما ينتج عنه خلفية ناعمة ومشوشة (بوكيه). المزاج العام هادئ وماهر. "
        "اتجاه الصورة عمودي."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

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

{
  "success": true,
  "task_id": "056f0589-a3dd-4ec2-8440-ad61f5038dfa",
  "trace_id": "c48de83f-0077-426e-b02b-ff1d58179064",
  "data": [
    {
      "prompt": "صورة قريبة واقعية لشخص مسن ياباني يصنع الفخار مع تجاعيد عميقة محفورة من الشمس وابتسامة دافئة وعارفة. إنه يقوم بفحص وعاء شاي تم تلميعه حديثًا بعناية. الإعداد هو ورشته الريفية المشرقة تحت الشمس. المشهد مضاء بضوء الساعة الذهبية الناعم المتدفق من خلال نافذة، مما يبرز القوام الدقيق للطين. تم التقاط الصورة بعدسة بورتريه 85 مم، مما ينتج عنه خلفية ناعمة ومشوشة (بوكيه). المزاج العام هادئ وماهر. اتجاه الصورة عمودي.",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/69790adb-c85d-4362-ad9e-0c9ba4352cf4.png"
    }
  ]
}

​
شرح الحقول

  • success: هل كانت هذه الطلب ناجحة.
  • task_id: معرف المهمة.
  • trace_id: معرف تتبع السلسلة، لتسهيل استكشاف الأخطاء.
  • data[]: قائمة النتائج.
    • prompt: نص التوجيه المستخدم للتوليد (عرض).
    • image_url: رابط الصورة الناتجة.
ملاحظة: /nano-banana/images تحتاج فقط إلى action و prompt لتوليد الصورة

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

عندما ترغب في تحرير صورة موجودة، قم بتعيين action إلى edit، ومرر قائمة روابط الصور التي ترغب في تحريرها عبر image_urls (صورة واحدة أو أكثر)، مع تقديم وصف لهدف التحرير في prompt. على سبيل المثال، إذا قدمنا صورة لشخص وصورة لملابس، يمكننا جعل الشخص يرتدي هذه الملابس، ويمكننا تمرير روابط الصور مع تعيين action إلى edit، يمكن أن تكون الروابط HTTP، بروتوكول https أو http، أو يمكن أن تكون صورة مشفرة بتنسيق Base64، مثل data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....

​
مثال على الطلب (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
  }'

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

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[]: قائمة روابط الصور التي سيتم تحريرها (يجب أن تكون متاحة للجمهور). يمكن تمرير عدة صور، وستقوم الخدمة بدمج هذه المواد مع prompt لإكمال التحرير.
  • الحقول الأخرى مشابهة لتلك التي تم إرجاعها في “توليد الصورة”.

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

يمكن أن تستغرق عملية التوليد أو التحرير بعض الوقت. لتجنب استهلاك الموارد بسبب الاتصالات الطويلة، يُنصح باستخدام استدعاء Webhook عبر callback_url:
  1. أضف callback_url في جسم الطلب، مثل عنوان Webhook الخاص بخادمك (يجب أن يكون متاحًا على الإنترنت ويدعم POST JSON).
  2. ستقوم واجهة برمجة التطبيقات بإرجاع استجابة تحتوي على 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: فشل في التحقق من الهوية أو نقص في الرمز المميز.
  • 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 (مصفوفة، على الأقل عنصر واحد)
  • اختياري: model (افتراضي nano-banana، يمكن اختيار nano-banana-2 أو nano-banana-pro)، aspect_ratio (نسبة العرض إلى الارتفاع، مثل 1:1، 16:9)، resolution (الدقة، مثل 1K، 2K، 4K)، callback_url (للاستدعاء غير المتزامن)
  • Headers: يجب تقديم authorization: Bearer {token}؛ يُنصح بتعيين accept إلى application/json
  • إمكانية الوصول إلى الصور: يجب أن تكون image_urls روابط مباشرة متاحة على الإنترنت (HTTP/HTTPS)، يُنصح باستخدام HTTPS
  • التماثل والتتبع: احتفظ بـ task_id و trace_id لتسهيل استكشاف الأخطاء وإصلاحها وربط النتائج