نظرة عامة
للوكلاء البرمجيين، اكتشف أولًا القائمة القصيرة الموصى بها للصور باستخدام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صراحةً.
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} لاسترداد النتيجة.
النماذج المتاحة
هذه أمثلة حالية للنماذج وليست كتالوجًا ثابتًا. استخدم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. راجع حالة الصورة لمعرفة كيفية استرجاع النتائج.
التعامل مع الاستجابات غير المتزامنة
بالنسبة للنماذج غير المتزامنة، تحقّق مما إذا كانت الاستجابة تحتوي علىstatus: "pending":