Skip to main content

نظرة عامة

إنشاء صورة معدلة أو موسعة من صورة أصلية ووصف نصي. يتطلب نوع المحتوى multipart/form-data. يدعم المسار كلا النمطين:
  • مسار رفع multipart/form-data المتوافق مع OpenAI والموضح أدناه
  • طلبات JSON التي توفر image_url أو image_urls أو مراجع images الرسمية لعائلات الصور المدعومة من صورة إلى صورة
gpt-image-2 مدعوم هنا. يقبل رفع multipart باسم image، و JSON image_url / image_urls، ومراجع images[] الرسمية (image_url أو file_id) حتى 16 صورة مصدر. أنشئ قيم file_id أولاً عبر /v1/files. اضبط async: true لإرجاع مهمة أولاً؛ وتستخدم نماذج التحرير الرسمية FLUX/BFL تدفق الاستعلام عن المهمة نفسه.لا تقبل عمليات تحرير gpt-image-2 الحقل resolution؛ استخدم size لأبعاد الإخراج. يقبل background القيمتين auto وopaque، ولا يدعم transparent. للطلبات متعددة الصور أو عالية التأخير، يُفضّل استخدام async: true ثم الاستعلام عن المهمة المُعادة.طلبات Nano Banana مع صورة مرجعية (nano-banana وnano-banana-2 وnano-banana-pro) متاحة عبر /v1/images/generations مع operation: "image-to-image" وimage_urls، وليس عبر واجهة /v1/images/edits هذه.تقبل نماذج تحرير الصور xAI Grok Imagine (grok-imagine-image وgrok-imagine-image-quality وgrok-imagine-image-pro القديم) حتى 3 صور مصدر كحد أقصى. تفشل الطلبات التي تتجاوز 3 صور مصدر أثناء تحقق الإدخال مع 400 too_many_images.input_fidelity ليس جزءا من الحقول المدعومة الحالي في TokenLab لـ gpt-image-2؛ احذفه وإلا سيعيد الطلب 400 unsupported_parameter.

جسم الطلب

مهلة الطلبات المتزامنة: قد تعيد بعض طلبات الصور الصورة النهائية inline وتنتظر اكتمال التوليد. قد تستغرق طلبات الدقة العالية أو الجودة العالية ما يقارب دقيقة أو أكثر، لذا اضبط مهلة عميل HTTP على 120s على الأقل. إذا احتوت استجابة الإنشاء على status: "pending" أو task_id أو poll_url، فاتبع poll_url المُعاد بدلًا من الانتظار. عناوين الصور البعيدة: عندما يكون إدخال multipart مطلوبًا، تجلب TokenLab قيم JSON image_url أو image_urls أو images[].image_url وترسل البايتات كأجزاء multipart باسم image. يجب أن تكون العناوين عامة عبر http/https، بلا بيانات اعتماد مضمّنة أو fragments، وألا تشير إلى localhost أو نطاقات IP خاصة أو محجوزة؛ ويتم فحص كل إعادة توجيه من جديد. يجب أن تكون الحمولة التي تم جلبها صورة PNG أو JPEG أو WebP حقيقية. الحدود هي 50MB لكل صورة، و200MB إجمالاً للصور المجلبة من URL في الطلب الواحد، و timeout قدره 10s، وحتى 3 عمليات إعادة توجيه.
file
صور المصدر في multipart. كرّر حقل image لإرسال عدة صور مصدر لـ GPT Image. يجب أن تكون الملفات PNG أو JPEG أو WebP، بحد أقصى 16 صورة مصدر و50MB لكل ملف. تستخدم نماذج تحرير xAI Grok Imagine حقول الإدخال نفسها لكنها تحد صور المصدر بـ 3.
string
مطلوب
وصف نصي للتعديل المطلوب.
file
صورة إضافية تشير مناطقها الشفافة بالكامل إلى أماكن التعديل. يجب أن تكون ملف PNG صالح، أقل من 50MB، وبنفس أبعاد image.في طلبات JSON، يمكن أن يكون mask أيضًا كائنًا يحتوي على واحد فقط من image_url أو file_id؛ يجب أن تأتي قيم file_id من /v1/files وأن تبقى مرتبطة بإعدادات تحرير الصورة نفسها.
string
مطلوب
النموذج المستخدم لتحرير الصور. استخدم gpt-image-2 لتحريرات GPT Image، أو نموذج تحرير صور حاليًا يعيده GET /v1/models?recommended_for=image.
integer
افتراضي:"1"
عدد الصور المراد إنشاؤها. يجب أن يكون بين 1 و 10.
string
حجم الصورة المُنشأة. بالنسبة إلى gpt-image-2 استخدم auto أو WIDTHxHEIGHT؛ يجب أن تكون الأبعاد من مضاعفات 16، وأطول ضلع لا يتجاوز 3840px، ونسبة الطويل إلى القصير لا تتجاوز 3:1، وإجمالي البكسلات بين 655,360 و8,294,400.
string
افتراضي:"url"
تنسيق إرجاع الصور المُنشأة. يجب أن يكون url أو b64_json؛ والقيمة الافتراضية هي url.بالنسبة إلى طلبات gpt-image-2 على Azure Official أو الخدمات المتوافقة مع Azure، تحصل TokenLab على بيانات الصور بصيغة b64_json. عند طلب url ترفع TokenLab كل صورة إلى CDN وتعيد data[].url. إذا لم يكن تخزين CDN متاحًا أو فشل الرفع، يفشل الطلب بدلاً من تحويله إلى استجابة Base64. عند طلب b64_json يُعاد Base64 الخام.
boolean
افتراضي:"false"
اضبطه على true مع gpt-image-2 أو نماذج تحرير FLUX/BFL الرسمية لإرجاع مهمة قبل أن تكون الصورة النهائية جاهزة. تعيد التحريرات غير المتزامنة المكتملة روابط URL بغض النظر عن response_format المطلوب؛ استخدم الطلبات المتزامنة إذا كنت تحتاج إلى b64_json.
string
معرف فريد يمثل المستخدم النهائي لمراقبة سوء الاستخدام.

الاستجابة

integer
الطابع الزمني Unix لوقت إنشاء الصور.
array
مصفوفة الصور المُنشأة.كل عنصر يحتوي على:
  • url (string): رابط الصورة المعدلة (إذا كان response_format هو url)
  • b64_json (string): الصورة بترميز Base64 (إذا كان response_format هو b64_json)

استجابة المهمة غير المتزامنة

اضبط async: true مع gpt-image-2 أو نماذج تحرير FLUX/BFL الرسمية لإنشاء مهمة بدلاً من انتظار الصورة المحررة داخل الطلب. تتضمن الاستجابة status: "pending" وtask_id وpoll_url. استعلم عن /v1/tasks/{task_id} حتى تصل المهمة إلى completed أو failed. تعيد مهام التحرير غير المتزامنة روابط URL للصور النهائية فقط. إذا كنت تحتاج إلى بيانات b64_json الخام، فاستخدم طلبًا متزامنًا. قد يتم حجز المبلغ التقديري عند إنشاء المهمة. تُحاسَب المهام المكتملة حسب الاستخدام الفعلي، أما المهام الفاشلة أو المنتهية بالمهلة فيُحرَّر حجزها أو تُرد تكلفتها.

ملاحظات

تُعاد أخطاء جلب الصور البعيدة كأخطاء إدخال قبل بدء التوليد. العناوين غير المتاحة، timeout، استجابات 403/404، المضيفون الخاصون/الداخليون، بيانات الاعتماد أو fragments في URL، المحتوى غير الصوري، الصيغ غير المدعومة، وتجاوزات الحجم تعيد 400 أو 413 وتحدد إدخال image_url / image_urls[n]. بالنسبة إلى الأصول الخاصة أو المحمية بترويسات، ارفع ملفات multipart image مباشرة أو أنشئ مراجع /v1/files.