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

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

> Nano Banana Image Generation 集成指南 - XHuoAPI

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

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

قبل الاستخدام، يرجى الدخول إلى [واجهة برمجة تطبيقات صور نانو موز](https://api.xhuoapi.ai/documents/23985a11-d713-41d1-ad84-24b021805b3d) في منصة XHuoAPI والنقر على Acquire لتقديم طلب فتح. عادةً ما يتوفر حد مجاني للاستخدام عند التقديم لأول مرة. بعد الانتهاء من الفتح، يمكنك الحصول على رمز Bearer Token لاستخدامه في استدعاء واجهة برمجة التطبيقات.

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

* **عنوان URL الأساسي**: `https://api.xhuoapi.ai/v1`
* **نقطة النهاية**: `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`: يعتمد على معاينة صورة Gemini 3.1 Flash، جودة احترافية + سرعة Flash
  * `nano-banana-pro`: يعتمد على معاينة صورة Gemini 3 Pro، أعلى جودة
* **الاستدعاء غير المتزامن**: اختياري، عبر `callback_url` لاستقبال إشعارات إكمال المهمة والنتائج

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

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

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

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "prompt": "صورة قريبة واقعية لشخص مسن ياباني يصنع الفخار مع تجاعيد عميقة محفورة من الشمس وابتسامة دافئة وعارفة. إنه يقوم بفحص وعاء شاي تم تلميعه حديثًا بعناية. الإعداد هو ورشته الريفية المشرقة تحت الشمس. المشهد مضاء بضوء الساعة الذهبية الناعم المتدفق من خلال نافذة، مما يبرز القوام الدقيق للطين. تم التقاط الصورة بعدسة بورتريه 85 مم، مما ينتج عنه خلفية ناعمة ومشوشة (بوكيه). المزاج العام هادئ وماهر. اتجاه الصورة عمودي.",
    "count": 1
  }'
```

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

```python theme={null}
import requests

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

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

```json theme={null}
{
  "success": true,
  "task_id": "056f0589-a3dd-4ec2-8440-ad61f5038dfa",
  "trace_id": "c48de83f-0077-426e-b02b-ff1d58179064",
  "data": [
    {
      "prompt": "صورة قريبة واقعية لشخص مسن ياباني يصنع الفخار مع تجاعيد عميقة محفورة من الشمس وابتسامة دافئة وعارفة. إنه يقوم بفحص وعاء شاي تم تلميعه حديثًا بعناية. الإعداد هو ورشته الريفية المشرقة تحت الشمس. المشهد مضاء بضوء الساعة الذهبية الناعم المتدفق من خلال نافذة، مما يبرز القوام الدقيق للطين. تم التقاط الصورة بعدسة بورتريه 85 مم، مما ينتج عنه خلفية ناعمة ومشوشة (بوكيه). المزاج العام هادئ وماهر. اتجاه الصورة عمودي.",
      "image_url": "https://platform.cdn.xhuoapi.ai/nanobanana/69790adb-c85d-4362-ad9e-0c9ba4352cf4.png"
    }
  ]
}
```

### شرح الحقول

* `success`: هل كانت هذه الطلب ناجحة.
* `task_id`: معرف المهمة.
* `trace_id`: معرف تتبع السلسلة، لتسهيل استكشاف الأخطاء.
* `data[]`: قائمة النتائج.
  * `prompt`: نص التوجيه المستخدم للتوليد (عرض).
  * `image_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.xhuoapi.ai/v1/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "edit",
    "prompt": "دع هذا الرجل يرتدي هذا القميص",
    "image_urls": [
      "https://cdn.xhuoapi.ai/v8073y.png",
      "https://cdn.xhuoapi.ai/44xlah.png"
    ],
    "count": 1
  }'
```

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

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "edit",
    "prompt": "دع هذا الرجل يرتدي هذا القميص",
    "image_urls": [
        "https://cdn.xhuoapi.ai/v8073y.png",
        "https://cdn.xhuoapi.ai/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.xhuoapi.ai/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png"
    }
  ]
}
```

### شرح الحقول

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

***

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

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

1. أضف `callback_url` في جسم الطلب، مثل عنوان Webhook الخاص بخادمك (يجب أن يكون متاحًا على الإنترنت ويدعم POST JSON).
2. ستقوم واجهة برمجة التطبيقات **بإرجاع** استجابة تحتوي على `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.xhuoapi.ai/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` أو `nano-banana-pro`)، `aspect_ratio` (نسبة العرض إلى الارتفاع، مثل `1:1`، `16:9`)، `resolution` (الدقة، مثل `1K`، `2K`، `4K`)، `callback_url` (للاستدعاء غير المتزامن)
* **Headers**: يجب تقديم `authorization: Bearer {token}`؛ يُنصح بتعيين `accept` إلى `application/json`
* **إمكانية الوصول إلى الصور**: يجب أن تكون `image_urls` روابط مباشرة متاحة على الإنترنت (HTTP/HTTPS)، يُنصح باستخدام HTTPS
* **التماثل والتتبع**: احتفظ بـ `task_id` و `trace_id` لتسهيل استكشاف الأخطاء وإصلاحها وربط النتائج