عملية التقديم
لاستخدام واجهة برمجة تطبيقات صور نانو موز، يجب أولاً الذهاب إلى وحدة التحكم في بيانات Ace للحصول على رمز API الخاص بك، احتفظ به للاستخدام لاحقًا.
إذا لم تقم بتسجيل الدخول أو التسجيل بعد، سيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء، سيتم إرجاعك تلقائيًا إلى الصفحة الحالية.
يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة. عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته مجانًا؛ عند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في وحدة التحكم.
📘 الوثائق الكاملة: واجهة برمجة تطبيقات صور نانو موز →
نظرة عامة على الواجهة
- عنوان URL الأساسي:
https://api.acedata.cloud - نقطة النهاية:
POST /nano-banana/images - طريقة المصادقة: يتم تضمين
authorization: Bearer {token}في رأس HTTP - رؤوس الطلب:
accept: application/jsoncontent-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:
- أضف
callback_urlفي جسم الطلب، مثل عنوان Webhook الخاص بخادمك (يجب أن يكون متاحًا على الإنترنت ويدعم POST JSON). - ستقوم API بإرجاع استجابة تحتوي على
task_idعلى الفور (أو تحتوي على نتيجة أساسية). - عند الانتهاء من المهمة، ستقوم المنصة بإرسال 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، أو النسخ الرسمية المقابلة: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لتسهيل استكشاف الأخطاء وإصلاحها وربط النتائج

