الانتقال إلى المحتوى الرئيسي

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.

​
نظرة عامة

إنشاء صورة معدلة أو موسعة من صورة أصلية ووصف نصي. يتطلب نوع المحتوى multipart/form-data. يدعم المسار كلا النمطين:
  • مسار الرفع التقليدي multipart/form-data على نمط DALL-E والمذكور أدناه
  • طلبات 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 أو background؛ استخدم size لأبعاد الإخراج. للطلبات متعددة الصور أو عالية التأخير، يُفضّل استخدام 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 صور مصدر قبل تمريرها إلى upstream مع 400 too_many_images.ملاحظة توافق: إذا أرسل طلب gpt-image-2 الحقل input_fidelity، تزيله TokenLab قبل التمرير لأن GPT Image 2 يعالج مدخلات الصور تلقائيا بدقة عالية.

​
جسم الطلب

مهلة الطلبات المتزامنة: قد يعيد بعض مزودي الصور الذين يتم التوجيه إليهم الصورة النهائية 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 عمليات إعادة توجيه.
​
image
file
صور المصدر في multipart. كرّر حقل image لإرسال عدة صور مصدر لـ GPT Image. يجب أن تكون الملفات PNG أو JPEG أو WebP، بحد أقصى 16 صورة مصدر و50MB لكل ملف. تستخدم نماذج تحرير xAI Grok Imagine حقول الإدخال نفسها لكنها تحد صور المصدر بـ 3. لا تزال تعديلات DALL-E 2 القديمة بالماسك تتوقع مدخلات PNG ذات مناطق شفافة، أو mask منفصلاً.
​
prompt
string
مطلوب
وصف نصي للتعديل المطلوب.
​
mask
file
صورة إضافية تشير مناطقها الشفافة بالكامل إلى أماكن التعديل. يجب أن تكون ملف PNG صالح، أقل من 50MB، وبنفس أبعاد image.
​
model
string
افتراضي:"dall-e-2"
النموذج المستخدم لتحرير الصور. gpt-image-2 مدعوم؛ ويمكن الاستمرار في استخدام dall-e-2 لتحريرات DALL-E القديمة.
​
n
integer
افتراضي:"1"
عدد الصور المراد إنشاؤها. يجب أن يكون بين 1 و 10.
​
size
string
حجم الصورة المُنشأة. بالنسبة إلى gpt-image-2 استخدم auto أو WIDTHxHEIGHT؛ يجب أن تكون الأبعاد من مضاعفات 16، وأطول ضلع لا يتجاوز 3840px، ونسبة الطويل إلى القصير لا تتجاوز 3:1، وإجمالي البكسلات بين 655,360 و8,294,400. تدعم تحريرات DALL-E القديمة 256x256 أو 512x512 أو 1024x1024.
​
response_format
string
افتراضي:"url"
تنسيق إرجاع الصور المُنشأة. يجب أن يكون url أو b64_json؛ والقيمة الافتراضية هي url.بالنسبة إلى مسارات gpt-image-2 على Azure Official أو القنوات المتوافقة مع Azure، لا تمرّر TokenLab الحقل response_format إلى upstream. يحصل gateway دائمًا على بيانات الصور من upstream بصيغة b64_json؛ عند طلب url يرفع كل صورة إلى CDN ويعيد data[].url. إذا لم يكن تخزين CDN متاحًا أو فشل الرفع، يفشل الطلب بدلاً من الرجوع إلى Base64. عند طلب b64_json يُعاد Base64 الخام.
​
async
boolean
افتراضي:"false"
اضبطه على true مع gpt-image-2 أو نماذج تحرير FLUX/BFL الرسمية لإرجاع مهمة قبل أن تكون الصورة النهائية جاهزة. تعيد التحريرات غير المتزامنة المكتملة روابط URL بغض النظر عن response_format المطلوب؛ استخدم الطلبات المتزامنة إذا كنت تحتاج إلى b64_json.
​
user
string
معرف فريد يمثل المستخدم النهائي لمراقبة سوء الاستخدام.

​
الاستجابة

​
created
integer
الطابع الزمني Unix لوقت إنشاء الصور.
​
data
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 الخام، فاستخدم طلبًا متزامنًا. قد يتم حجز المبلغ التقديري عند إنشاء المهمة. تُحاسَب المهام المكتملة حسب الاستخدام الفعلي، أما المهام الفاشلة أو المنتهية بالمهلة فيُحرَّر حجزها أو تُرد تكلفتها. 
curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "image=@sunlit_lounge.png" \
  -F "mask=@mask.png" \
  -F "prompt=A sunlit indoor lounge area with a pool" \
  -F "n=1" \
  -F "size=1024x1024"

{
  "created": 1706000000,
  "data": [
    {
      "url": "https://..."
    }
  ]
}

​
ملاحظات

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