الانتقال إلى المحتوى الرئيسي
تقدم هذه المقالة تكامل واستخدام Nano Banana Images API. تدعم هذه الواجهة قدرتين: توليد الصور (generate) وتحرير الصور (edit).

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

لاستخدام Nano Banana Images API، انتقل أولاً إلى لوحة تحكم Ace Data Cloud للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقاً. إذا لم تكن قد سجلت الدخول أو أنشأت حساباً بعد، فسيتم تحويلك تلقائياً إلى صفحة تسجيل الدخول لدعوتك إلى التسجيل وتسجيل الدخول، وبعد الإكمال ستعود تلقائياً إلى الصفحة الحالية. يمكن استخدام API Token واحد لاستدعاء جميع خدمات المنصة، ولا حاجة للتقديم بشكل منفصل لكل خدمة. سيمنحك أول طلب حصة مجانية لتجربة الخدمة مجاناً؛ وعندما لا تكفي الحصة، يمكنك شحن الرصيد العام في لوحة التحكم.
📘 الوثائق الكاملة: Nano Banana Images API →

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

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

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

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

مثال طلب (cURL)

مثال طلب (Python)

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

شرح الحقول

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

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

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

مثال طلب (cURL)

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

مثال على الإرجاع الناجح

وصف الحقول

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

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

قد يستغرق التوليد أو التحرير بعض الوقت. لتجنب استهلاك الموارد بسبب الاتصالات الطويلة، يوصى باستخدام استدعاء Webhook عبر callback_url:
  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: فشلت المصادقة أو الرمز المميز مفقود.
  • 403 forbidden: رفضت سياسة الأمان الأصلية للمزوّد الطلب أو نتيجة التوليد. لن يُرجع هذا الاستدعاء صورة ولن يتم احتساب رسوم؛ وقد تظل طلبات الصور المتعددة تُرجع وتُحتسب رسوم للاستدعاءات الناجحة الأخرى.
  • 429 too_many_requests: تجاوز معدل الطلبات الحد المسموح.
  • 500 api_error: استثناء في جانب الخادم.

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


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

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