Skip to main content
تتناول هذه الوثيقة الاتصال واستخدام واجهة برمجة تطبيقات صور نانو موز. تدعم هذه الواجهة قدرتين: توليد الصور (generate) و تحرير الصور (edit).

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

لاستخدام واجهة برمجة تطبيقات صور نانو موز، يجب أولاً الذهاب إلى وحدة التحكم في بيانات Ace للحصول على رمز API الخاص بك، احتفظ به للاستخدام لاحقًا. إذا لم تقم بتسجيل الدخول أو التسجيل بعد، سيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء، سيتم إرجاعك تلقائيًا إلى الصفحة الحالية. يمكن استخدام رمز 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)

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

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

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

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

توضيح الحقول

  • success: هل كانت هذه الطلبية ناجحة.
  • task_id: معرف المهمة.
  • trace_id: معرف تتبع السلسلة، لتسهيل استكشاف الأخطاء.
  • count: عدد الصور المطلوبة للتوليد أو التحرير، يدعم 1–4، الافتراضي 1. في حالة الفشل الجزئي، تحتوي data فقط على الصور الناجحة.
  • data[]: قائمة النتائج.
    • prompt: نص التوجيه المستخدم للتوليد (عرض).
    • image_url: رابط 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)

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

شرح الحقول

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

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

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

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

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

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


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

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