> ## 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. # إنشاء صورة > ينشئ صورة بناءً على prompt ## نظرة عامة للوكلاء البرمجيين، اكتشف أولًا القائمة القصيرة الموصى بها للصور باستخدام `GET /v1/models?recommended_for=image`، ثم أرسل `model` المختار صراحةً إلى هذه النقطة النهائية. `gpt-image-2` هو نموذج GPT Image تُحسب تكلفته حسب الـ tokens. تتبع TokenLab تفاصيل `usage` الرسمية من OpenAI لتسوية tokens إدخال النص، وإدخال الصور، والإدخال المخزن مؤقتًا عند الإبلاغ عنه، وtokens إخراج الصور؛ ولا يتم التعامل معه كنموذج بسعر ثابت لكل صورة. بالنسبة إلى إنشاء الصور باستخدام `gpt-image-2`، تدعم الواجهة العامة المعلمات `prompt` و`n` و`size` و`quality` و`response_format` و`async` و`background` و`output_format` و`output_compression` أو `compression` و`moderation` و`user`. إذا لم ترسل `size` أو `quality` تستخدم TokenLab القيمة `auto`؛ ويجب أن تستخدم قيم `size` المخصصة عقد `WIDTHxHEIGHT` المرن الموضح أدناه. `input_fidelity` ليس جزءا من الحقول المدعومة الحالي في TokenLab لـ `gpt-image-2`؛ احذفه وإلا سيعيد الطلب `400 unsupported_parameter`. ### ملاحظات سلوك النموذج Google Gemini في عقد اختيار واحد: * تدعم `gemini-3.1-flash-image` و`gemini-3-pro-image` و`nano-banana-pro` كلًا من `aspect_ratio` و`resolution` (`1k` و`2k` و`4k`) في عمليات text-to-image وimage-edit/image-to-image العامة. * يدعم `nano-banana-2` كلًا من `aspect_ratio` و`resolution` (`1k` و`2k` و`4k`) في text-to-image فقط ضمن عقد TokenLab الحالي. * تدعم `gemini-2.5-flash-image` و`nano-banana` و`nano-banana-edit` الحقل `aspect_ratio` لكنها لا تعرض اختيار `resolution` عامًا. * لطلبات Nano Banana مع صورة مرجعية، استخدم `nano-banana-edit` أو `nano-banana-pro` على هذه الواجهة (`/v1/images/generations`) مع `operation: "image-to-image"` و`image_urls`. لا ترسل طلبات Nano Banana المرجعية إلى `/v1/images/edits`. * في طلبات Nano Banana image-to-image، يمكن لـ `nano-banana-pro` تضمين `resolution` (`1k` و`2k` و`4k`)؛ ويجب على `nano-banana-edit` حذفها. أما `nano-banana` و`nano-banana-2` فهما نموذجا text-to-image في الحقول المدعومة الحالي. * يمكن إرسال الصور المرجعية في هذه الواجهة عبر JSON `image_url` / `image_urls` أو كملف multipart باسم `image`. لا تقبل `/v1/images/generations` الحقول `images[]` أو `file_id`؛ تُستخدم مراجع `/v1/files` فقط مع نماذج `/v1/images/edits` التي توثق `images[].file_id` صراحةً. لأسَر صور Google، فضّل `aspect_ratio` وأرسل `resolution` فقط عندما يذكرها النموذج صراحةً. نماذج صور xAI Grok Imagine (`grok-imagine-image` و`grok-imagine-image-quality` و`grok-imagine-image-pro` القديم) تدعم `aspect_ratio` مع `resolution` (`1k` و`2k`). يبقى `grok-imagine-image-pro` كمعرّف توافق لـ `grok-imagine-image-quality`. ## جسم الطلب **مهلة الطلبات المتزامنة:** قد تعيد بعض طلبات الصور الصورة النهائية inline وتنتظر اكتمال التوليد. قد تستغرق طلبات الدقة العالية أو الجودة العالية ما يقارب دقيقة أو أكثر، لذا اضبط مهلة عميل HTTP على `120s` على الأقل. إذا احتوت استجابة الإنشاء على `status: "pending"` أو `task_id` أو `poll_url`، فاتبع `poll_url` المُعاد بدلًا من الانتظار. النموذج المطلوب استخدامه، مثل `gpt-image-2` أو `flux-pro` أو `qwen-image-plus` أو `nano-banana-pro`. استخدم `GET /v1/models?recommended_for=image` للحصول على قائمة التوصيات الحالية. وصف نصي للصورة المطلوبة. رابط HTTPS عام لصورة مرجعية في توليد image-to-image. في طلبات Nano Banana المرجعية، اجعل `operation` تساوي `image-to-image`؛ يمكن لـ `nano-banana-pro` تضمين `resolution`، بينما يجب على `nano-banana-edit` حذفها. روابط HTTPS عامة لصور مرجعية. استخدمها لصورة مرجعية واحدة أو أكثر في طلبات JSON. لا تدعم هذه الواجهة `file_id` أو `images[]`. روابط صور مرجعية إضافية خاصة بالنموذج للمزوّدين الذين يميزون بين صورة الإدخال الأساسية والصور المرجعية. ملف صورة مرجعية multipart لتوليد image-to-image. استخدمه عندما تكون الصورة المصدر خاصة أو تتطلب ترويسات. هذا يختلف عن `file_id` من /v1/files؛ هذه الواجهة لا تقبل `file_id`. عدد الصور المطلوب إنشاؤها (1-10، بحسب النموذج). حجم الصورة. استخدمه لعائلات الصور بأسلوب OpenAI والنماذج الأخرى التي تقبل أحجام بكسل دقيقة. بالنسبة إلى `gpt-image-2`، تقبل `size` القيمة `auto` أو `WIDTHxHEIGHT`. يجب أن يكون كل من البعدين من مضاعفات 16، وألا يتجاوز أطول ضلع `3840px`، وألا تتجاوز نسبة الضلع الطويل إلى القصير `3:1`، وأن يكون إجمالي عدد البكسلات بين `655,360` و`8,294,400`. لا تُعد `aspect_ratio` و`resolution` جزءًا من الحقول المدعومة الحالي في TokenLab لـ `gpt-image-2`. بالنسبة إلى عائلات صور Google Gemini، يتم التعامل مع `size` كاسم بديل للتوافق يطابق عقد `aspect_ratio` العام للنموذج، و`resolution` عند دعمه. لهذه النماذج، يُفضّل إرسال `aspect_ratio` مباشرةً. محدد نسبة الأبعاد بحسب النموذج. القيم الشائعة في عائلات صور Google تشمل `1:1` و `16:9` و `9:16` و `3:2` و `2:3`. محدد دقة الإخراج بحسب النموذج. مدعوم في `gemini-3.1-flash-image` و`gemini-3-pro-image` لعمليات text-to-image وimage-edit، وفي `nano-banana-pro` لعمليات text-to-image وimage-to-image، وفي `nano-banana-2` لعملية text-to-image فقط. القيم النموذجية هي `1k` و`2k` و`4k`. لا ترسل هذه المعلمة إلى عائلات صور Gemini التي تدعم النسبة فقط إلا إذا وثّقها النموذج صراحةً. لنماذج صور xAI Grok Imagine استخدم `1k` أو `2k`. جودة الصورة. تستخدم نماذج GPT Image مثل `gpt-image-2` القيم `auto` أو `low` أو `medium` أو `high`. قد تستخدم عائلات صور أخرى قيمًا خاصة بالمزوّد؛ راجع metadata النموذج المحدد قبل إرسال قيم غير افتراضية. تنسيق الاستجابة: `url` أو `b64_json`. القيمة الافتراضية هي `url`. بالنسبة إلى طلبات `gpt-image-2` على Azure Official أو الخدمات المتوافقة مع Azure، تحصل TokenLab على بيانات الصور بصيغة `b64_json`. عند طلب `url` ترفع TokenLab كل صورة إلى CDN وتعيد `data[].url`. إذا لم يكن تخزين CDN متاحًا أو فشل الرفع، يفشل الطلب بدلاً من تحويله إلى استجابة Base64. عند طلب `b64_json` يُعاد Base64 الخام. اضبطه على `true` مع `gpt-image-2` أو نماذج الصور الرسمية FLUX/BFL لإنشاء مهمة أولاً. تعيد مهام الصور غير المتزامنة المكتملة روابط URL بغض النظر عن `response_format` المطلوب؛ استخدم الطلبات المتزامنة إذا كنت تحتاج إلى `b64_json`. محدد نمط اختياري. أرسله فقط عندما يوثّقه النموذج المحدد صراحة؛ احذفه مع `gpt-image-2` ما لم تذكر metadata النموذج خلاف ذلك. معرّف فريد للمستخدم النهائي. ## الاستجابة ### الاستجابة المضمنة الطابع الزمني Unix لوقت الإنشاء. مصفوفة من الصور المُنشأة. يحتوي كل كائن على: * `url` (string): عنوان URL للصورة المُنشأة * `b64_json` (string): صورة مرمّزة بـ Base64 (إذا تم طلبها) * `revised_prompt` (string): نسخة prompt معدّلة اختيارية عندما يعيدها النموذج المحدد ### استجابة المهمة غير المتزامنة اضبط `async: true` مع `gpt-image-2` أو نماذج الصور الرسمية FLUX/BFL لإنشاء مهمة بدلاً من انتظار الصورة النهائية داخل طلب الإنشاء. تتضمن الاستجابة `status: "pending"` و`task_id` و`poll_url`. استعلم عن `/v1/tasks/{task_id}` حتى تصل المهمة إلى `completed` أو `failed`. تعيد مهام الصور غير المتزامنة روابط URL للصور النهائية فقط. إذا كنت تحتاج إلى بيانات `b64_json` الخام، فاستخدم طلبًا متزامنًا. قد يتم حجز التكلفة المقدّرة عند إنشاء المهمة. تُحاسب المهام المكتملة حسب الاستخدام الفعلي، وتُحرر أو تُسترد تكلفة المهام الفاشلة أو المنتهية بالمهلة. طابع Unix الزمني لوقت الإنشاء. معرّف المهمة الفريد للاستطلاع. الحالة الأولية: `pending`. عنوان URL نسبي للاستطلاع للحصول على النتائج، على سبيل المثال `/v1/tasks/{id}`. يبقى فارغًا أثناء كون المهمة قيد الانتظار. وتُرجِع مهام الصور المكتملة عناوين URL للصور المُولَّدة في `data[].url`. عند تلقي `status: "pending"`، استخدم `poll_url` أو `GET /v1/tasks/{task_id}` لاسترداد النتيجة. ```bash cURL theme={null} curl -X POST "https://api.tokenlab.sh/v1/images/generations" \ -H "Authorization: Bearer sk-your-api-key" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3-pro-image", "prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill", "aspect_ratio": "16:9", "resolution": "2k", "n": 1 }' ``` ```python Python theme={null} from openai import OpenAI client = OpenAI( api_key="sk-your-api-key", base_url="https://api.tokenlab.sh/v1" ) response = client.images.generate( model="gemini-3-pro-image", prompt="A cinematic portrait of a white cat sitting on a rainy windowsill", aspect_ratio="16:9", resolution="2k", n=1 ) print(response.data[0].url) ``` ```javascript JavaScript theme={null} import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'sk-your-api-key', baseURL: 'https://api.tokenlab.sh/v1' }); const response = await client.images.generate({ model: 'gemini-3-pro-image', prompt: 'A cinematic portrait of a white cat sitting on a rainy windowsill', aspect_ratio: '16:9', resolution: '2k', n: 1 }); console.log(response.data[0].url); ``` ```php PHP theme={null} true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', 'Authorization: Bearer sk-your-api-key' ], CURLOPT_POSTFIELDS => json_encode([ 'model' => 'gemini-3-pro-image', 'prompt' => 'A cinematic portrait of a white cat sitting on a rainy windowsill', 'aspect_ratio' => '16:9', 'resolution' => '2k', 'n' => 1 ]) ]); $response = curl_exec($ch); curl_close($ch); $data = json_decode($response, true); echo $data['data'][0]['url']; ``` مثال لعائلة صور تدعم النسبة فقط: بالنسبة إلى `gemini-2.5-flash-image` أو `nano-banana` أو `nano-banana-edit`، أرسل `aspect_ratio` لكن احذف `resolution`: ```json theme={null} { "model": "gemini-2.5-flash-image", "prompt": "A clean editorial product shot of a citrus soda can", "aspect_ratio": "16:9" } ``` مثال Nano Banana Pro مع صورة مرجعية: أرسل الطلب إلى `/v1/images/generations` وليس إلى `/v1/images/edits`. `resolution` اختياري ويمكن ضبطه على `1k` أو `2k` أو `4k`: ```json theme={null} { "model": "nano-banana-pro", "prompt": "Create a clean cinematic character image based on the reference images", "operation": "image-to-image", "image_urls": ["https://example.com/reference-1.png"], "aspect_ratio": "1:1", "resolution": "2k" } ``` للصور المصدر الخاصة أو المحلية، استخدم رفع multipart مباشرًا. لا ترسل `file_id` إلى `/v1/images/generations`: ```bash theme={null} curl -X POST "https://api.tokenlab.sh/v1/images/generations" \ -H "Authorization: Bearer sk-your-api-key" \ -F "model=nano-banana-pro" \ -F "prompt=Create a clean cinematic character image based on this reference" \ -F "operation=image-to-image" \ -F "image=@reference.png" \ -F "aspect_ratio=1:1" \ -F "resolution=2k" ``` ```json Synchronous Response theme={null} { "created": 1706000000, "data": [ { "url": "https://...", "revised_prompt": "A fluffy white cat with bright eyes sitting peacefully on a wooden windowsill, watching raindrops stream down the glass window..." } ] } ``` ```json Async Task Response theme={null} { "created": 1706000000, "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "status": "pending", "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "data": [] } ``` ## النماذج المتاحة هذه أمثلة حالية للنماذج وليست كتالوجًا ثابتًا. استخدم `GET /v1/models?recommended_for=image` أو صفحة Models لمعرفة التوفر والأسعار الأحدث. | النموذج | النوع | الميزات | | -------------------- | ----------------------- | ----------------------------------------------- | | `gpt-image-2` | متزامن أو قائم على مهمة | نموذج GPT Image بتسعير حسب التوكنات وأحجام مرنة | | `flux-pro` | غالبًا قائم على مهمة | واقعي تصويريًا، جودة عالية | | `qwen-image-plus` | غالبًا قائم على مهمة | عرض نص قوي واتباع جيد للـ prompt | | `nano-banana-pro` | غالبًا قائم على مهمة | سير عمل صور مرجعية وإخراج عالي الدقة | | `grok-imagine-image` | غالبًا قائم على مهمة | توليد صور xAI مع اختيار النسبة والدقة | | `ideogram-v3` | غالبًا قائم على مهمة | عرض نص قوي | **النماذج غير المتزامنة** تُرجع `status: "pending"` وتتطلب polling. راجع [حالة الصورة](/api-reference/images/get-image-status) لمعرفة كيفية استرجاع النتائج. ## التعامل مع الاستجابات غير المتزامنة بالنسبة للنماذج غير المتزامنة، تحقّق مما إذا كانت الاستجابة تحتوي على `status: "pending"`: ```python theme={null} import requests import time def generate_image(prompt, model="flux-pro"): # Create image request response = requests.post( "https://api.tokenlab.sh/v1/images/generations", headers={"Authorization": "Bearer sk-your-api-key"}, json={"model": model, "prompt": prompt} ) data = response.json() # Check if async if data.get("status") == "pending": task_id = data["task_id"] poll_url = data.get("poll_url") print(f"Async task started: {task_id}") # Poll for result while True: status_resp = requests.get( f"https://api.tokenlab.sh{poll_url}" if poll_url else f"https://api.tokenlab.sh/v1/tasks/{task_id}", headers={"Authorization": "Bearer sk-your-api-key"} ) status_data = status_resp.json() if status_data["status"] == "completed": return status_data["data"][0]["url"] elif status_data["status"] == "failed": raise Exception(status_data.get("error", "Generation failed")) time.sleep(3) else: # Sync response return data["data"][0]["url"] # Usage url = generate_image("a beautiful sunset over mountains", model="flux-pro") print(f"Generated image: {url}") ```