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

