> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# واجهة برمجة تطبيقات صور نانو موز توضيح الاتصال

> Nano Banana Image Generation API guide - Ace Data Cloud

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

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

لاستخدام واجهة برمجة تطبيقات صور نانو موز، يجب أولاً الذهاب إلى [وحدة التحكم في بيانات Ace](https://platform.acedata.cloud/console/applications) للحصول على رمز API الخاص بك، احتفظ به للاستخدام لاحقًا.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

إذا لم تقم بتسجيل الدخول أو التسجيل بعد، سيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء، سيتم إرجاعك تلقائيًا إلى الصفحة الحالية.

**يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة.** عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته مجانًا؛ عند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في [وحدة التحكم](https://platform.acedata.cloud/console/coin).

> 📘 الوثائق الكاملة: [واجهة برمجة تطبيقات صور نانو موز →](https://platform.acedata.cloud/documents/nano-banana-images)

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

* **عنوان 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)

```bash theme={null}
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",
    "model": "nano-banana-pro",
    "prompt": "صورة قريبة واقعية لشخص مسن ياباني يصنع الفخار مع تجاعيد عميقة محفورة من الشمس وابتسامة دافئة وعارفة. إنه يقوم بفحص وعاء شاي تم تلميعه حديثًا بعناية. الإعداد هو ورشته الريفية المشرقة تحت الشمس. المشهد مضاء بضوء الساعة الذهبية الناعم المتدفق من خلال نافذة، مما يبرز الملمس الدقيق للطين. تم التقاطها بعدسة بورتريه 85 مم، مما ينتج عنه خلفية ناعمة ومشوشة (بوكيه). المزاج العام هادئ وماهر. اتجاه الصورة عمودي.",
    "count": 1
  }'
```

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

```python theme={null}
import requests

url = "https://api.acedata.cloud/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "generate",
    "model": "nano-banana-pro",
    "prompt": (
        "صورة قريبة واقعية لشخص مسن ياباني يصنع الفخار "
        "مع تجاعيد عميقة محفورة من الشمس وابتسامة دافئة وعارفة. إنه يقوم بفحص "
        "وعاء شاي تم تلميعه حديثًا بعناية. الإعداد هو ورشته الريفية المشرقة تحت "
        "الشمس. المشهد مضاء بضوء الساعة الذهبية الناعم المتدفق من خلال نافذة، "
        "مما يبرز الملمس الدقيق للطين. تم التقاطها بعدسة بورتريه 85 مم، مما "
        "ينتج عنه خلفية ناعمة ومشوشة (بوكيه). المزاج العام هادئ وماهر. اتجاه الصورة عمودي."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())
```

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

```json theme={null}
{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "صورة قريبة واقعية لشخص مسن ياباني يصنع الفخار مع تجاعيد عميقة محفورة من الشمس وابتسامة دافئة وعارفة. إنه يقوم بفحص وعاء شاي تم تلميعه حديثًا بعناية. الإعداد هو ورشته الريفية المشرقة تحت الشمس. المشهد مضاء بضوء الساعة الذهبية الناعم المتدفق من خلال نافذة، مما يبرز الملمس الدقيق للطين. تم التقاطها بعدسة بورتريه 85 مم، مما ينتج عنه خلفية ناعمة ومشوشة (بوكيه). المزاج العام هادئ وماهر. اتجاه الصورة عمودي.",
      "image_url": "https://platform2.cdn.acedata.cloud/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336.png"
    }
  ]
}
```

### توضيح الحقول

* `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)

```bash theme={null}
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 theme={null}
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())
```

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

```json theme={null}
{
  "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[]`：قائمة URL للصور المراد تعديلها (يجب أن تكون متاحة على الإنترنت). يمكن إرسال عدة صور، ستقوم الخدمة بدمج هذه المواد مع `prompt` لإكمال التعديل.
* الحقول الأخرى مثل "توليد الصور" تعود بنفس الشكل.

***

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

قد تحتاج عملية التوليد أو التعديل إلى بعض الوقت. لتجنب استهلاك الموارد بسبب الاتصالات الطويلة، يُنصح باستخدام `callback_url` عبر **استدعاء Webhook**:

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

**مثال على حمولة الاستدعاء** (هيكل الحقول متطابق مع الاستجابة الناجحة المتزامنة):

```json theme={null}
{
  "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`**：استثناء في الخادم.

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

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "خطأ داخلي في الخادم."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

***

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

* **مطلوب**：`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` لتسهيل استكشاف الأخطاء وإصلاحها وربط النتائج