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

# توليد الصور

> اختر نقطة نهاية صورة TokenLab المناسبة، أرسل طلبات مدركة للنموذج، وتعامل مع نتائج الصور المتزامنة أو غير المتزامنة بأمان.

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

## متى تستخدم كل نقطة نهاية

| سير العمل للمستخدم    | نقطة النهاية                  | استخدم عندما                                                                                                                                  | تجنب عندما                                         |
| --------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| تحويل النص إلى صورة   | `POST /v1/images/generations` | يبدأ المستخدم من موجه فقط                                                                                                                     | تحتاج إلى تدفق تحرير صورة GPT رسمي                 |
| تحويل الصورة إلى صورة | `POST /v1/images/generations` | تشير وثائق النموذج إلى الصور المرجعية من خلال `operation: "image-to-image"` بالإضافة إلى `image_url`، `image_urls`، أو `reference_image_urls` | يتوقع النموذج إدخال تحرير متعدد الأجزاء            |
| تحرير الصورة          | `POST /v1/images/edits`       | تقوم بتحرير صورة موجودة باستخدام نموذج تحرير مدعوم مثل نموذج عائلة GPT Image                                                                  | تستخدم أسلوب توليد صورة Nano Banana                |
| تباين                 | `POST /v1/images/variations`  | تحافظ على تكامل متوافق مع التباين القديم                                                                                                      | تقوم ببناء تدفق صورة مرجعية جديد                   |
| الحالة                | `GET /v1/tasks/{id}`          | تعيد استجابة الإنشاء `task_id`، `status: "pending"`، أو `poll_url`                                                                            | تحتوي استجابة الإنشاء بالفعل على `data[]` النهائية |

دائمًا أرسل `model`. نقاط نهاية الصور لا تعتمد عمدًا على نموذج افتراضي ضمني تاريخي لحركة المرور الإنتاجية.

## اختر نموذجًا

ابدأ باكتشاف النموذج، ثم افحص عقد TokenLab للنموذج المحدد:

```bash theme={null}
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"
```

بالنسبة للنماذج غير المتعلقة بالدردشة، قد تتضمن استجابة القائمة `tokenlab.public_contract_summary`. قد تكشف صفحات تفاصيل النموذج عن `tokenlab.public_contract` بشكل كامل. استخدم تلك الحقول للتأكيد:

* العملية المدعومة، مثل `text-to-image`، `image-to-image`، أو `image-edit`.
* نقطة النهاية المتوقعة من قبل النموذج.
* الشكل الذي يجب استخدامه للمرجع، مثل `image_url`، `image_urls`، `reference_image_urls`، `image` متعدد الأجزاء، أو `images[]` بتنسيق JSON.
* ما إذا كان النموذج يقبل `size`، `aspect_ratio`، `resolution`، `quality`، `background`، `output_format`، أو `response_format`.

## قواعد شكل الطلب

* تستخدم طلبات نمط `gpt-image-2` حقول `size`، `quality`، وحقول التحرير على غرار OpenAI. اترك الحقول الاختيارية عند رغبتك في أن يستخدم النموذج أو TokenLab القيم الافتراضية التلقائية.
* عادةً ما تستخدم عائلات الصور Gemini وNano Banana `aspect_ratio`؛ أرسل `resolution` فقط عندما يكشف عقد النموذج عنها.
* ينتمي تحويل الصورة إلى صورة Nano Banana إلى `/v1/images/generations` مع `operation: "image-to-image"` وعناوين URL للصور المرجعية.
* لا تقبل `/v1/images/generations` `images[]` أو `file_id` على المستوى الأعلى؛ تلك هي أشكال تدفق التحرير.
* يجب أن تكون مراجع الصور البعيدة عناوين URL عامة `http` أو `https`. لا ترسل عناوين URL لشبكة خاصة، أو بيانات اعتماد مضمنة، أو أجزاء URL، أو عناوين URL موقعة قد تنتهي صلاحيتها قبل بدء المعالجة.

## مثال تحويل النص إلى صورة

```bash theme={null}
curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "صورة منتج نظيفة لكوب قهوة خزفي على مكتب من الجوز",
    "size": "1024x1024",
    "response_format": "url"
  }'
```

## مثال صورة مرجعية

```bash theme={null}
curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana",
    "operation": "image-to-image",
    "prompt": "احتفظ بشكل المنتج، غير الخلفية إلى إعداد استوديو مشرق",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'
```

## التعامل مع النتائج

يمكن أن تكون استجابات الصور متزامنة أو غير متزامنة:

* تعيد الاستجابات المتزامنة `data[]` النهائية مع `url` أو `b64_json`.
* تعيد الاستجابات غير المتزامنة `id`، `task_id`، `status`، وعادةً `poll_url`.
* يفضل استخدام `poll_url` عندما يكون موجودًا. إذا كنت بحاجة إلى مسار ثابت، استعلم عن `GET /v1/tasks/{id}`.
* استخدم الطلبات المتزامنة عندما تحتاج تحديدًا إلى `b64_json`؛ نتائج الصور غير المتزامنة موجهة نحو URL.

```bash theme={null}
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"
```

احتفظ بعنوان URL للصورة المعادة، ومعرف المهمة، والنموذج، ومعرف المستخدم/الوظيفة الخاص بك. لا تستمر في الاستعلام بعد حالة نهائية.

## قائمة التحقق للإنتاج

* تحقق من مدخلات المستخدم قبل استدعاء TokenLab: طول الموجه، عدد الصور، إمكانية الوصول إلى URL، ونوع الملف.
* اضبط مهلات HTTP عالية بما يكفي للطلبات المتزامنة عالية الدقة. استخدم الوضع غير المتزامن حيثما كان متاحًا للأعمال الطويلة.
* قم بتخزين `request_id`، `task_id`، `poll_url`، النموذج، نقطة النهاية، وشكل الطلب المنظف للدعم.
* عند انتهاء مهلة العميل، تحقق مما إذا تم إنشاء مهمة قبل إعادة محاولة طلب الإنشاء.
* قم بمصالحة التكلفة مع سجلات الاستخدام و`billing_transaction_id` عند وجودها، وليس مع معرفات مهام المزود.

## الأخطاء الشائعة

| العرض                                       | السبب المحتمل                                     | الحل                                                                 |
| ------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------- |
| `400` مع `param: "model"`                   | نموذج مفقود صريح                                  | استعلم عن `/v1/models?recommended_for=image` وأرسل `model`           |
| حقل غير مدعوم                               | الحقل غير موجود في العقد العام لذلك النموذج       | أزل الحقل أو اختر نموذج/نقطة نهاية توثق ذلك                          |
| لا يوجد `b64_json` في النتيجة غير المتزامنة | تعيد مهام الصور غير المتزامنة نتائج موجهة نحو URL | استخدم الوضع المتزامن للإخراج بتنسيق base64                          |
| تم رفض الصورة المرجعية                      | نقطة نهاية خاطئة أو URL خاص/منتهي الصلاحية        | تطابق الشكل المرجعي الموثق للنموذج واستخدم عناوين URL القابلة للوصول |

## مرجع API

| الموضوع                | المرجع                                                              |
| ---------------------- | ------------------------------------------------------------------- |
| إنشاء صورة             | [إنشاء صورة](/ar/api-reference/images/create-image)                 |
| تحرير صورة             | [تحرير صورة](/ar/api-reference/images/edit-image)                   |
| إنشاء تباين صورة       | [إنشاء تباين صورة](/ar/api-reference/images/create-variation)       |
| الحصول على حالة الصورة | [الحصول على حالة الصورة](/ar/api-reference/images/get-image-status) |
| الحصول على حالة المهمة | [الحصول على حالة المهمة](/ar/api-reference/tasks/get-task-status)   |