TokenLab
الحصول على مفتاح API
التوثيقمرجع APIالتكاملات

الصور

تعديل صورة

تعديل صورة بناءً على وصف نصي وصورة مصدر

POST
/v1/images/edits

نظرة عامة

إنشاء صورة معدلة أو موسعة من صورة أصلية ووصف نصي.

يدعم المسار كلا النمطين:

  • مسار رفع 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-edit و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 حقيقية. الحدود هي 50 MiB لكل صورة، و200 MiB إجمالاً للصور المجلبة من URL في الطلب الواحد، و timeout قدره 30s، وحتى 3 عمليات إعادة توجيه.

يجب أن يتضمن طلب JSON حقلًا واحدًا فقط من image_url أو image_urls أو images. ويجب أن يحتوي كل كائن images[] على واحد فقط من image_url أو file_id. يشمل حد 200 MiB الإجمالي جميع صور المصدر والقناع.

imagefile

صور المصدر في multipart. كرّر حقل image لإرسال عدة صور مصدر لـ GPT Image. يجب أن تكون الملفات PNG أو JPEG أو WebP، بحد أقصى 16 صورة مصدر و50 MiB لكل ملف. تستخدم نماذج تحرير xAI Grok Imagine حقول الإدخال نفسها لكنها تحد صور المصدر بـ 3.

promptstringمطلوب

وصف نصي للتعديل المطلوب.

maskfile | object

صورة إضافية تشير مناطقها الشفافة بالكامل إلى أماكن التعديل. يجب أن تكون ملف PNG صالح، أقل من 50 MiB، وبنفس أبعاد image.

في طلبات JSON، يمكن أن يكون mask أيضًا كائنًا يحتوي على واحد فقط من image_url أو file_id؛ يجب أن تأتي قيم file_id من /v1/files وأن تبقى مرتبطة بإعدادات تحرير الصورة نفسها.

modelstringمطلوب

النموذج المستخدم لتحرير الصور. استخدم gpt-image-2 لتحريرات GPT Image، أو نموذج تحرير صور حاليًا يعيده GET /v1/models?recommended_for=image.

nintegerالافتراضي: 1

عدد الصور المطلوب إنشاؤها (1-10، بحسب النموذج).

sizestring

حجم الصورة المُنشأة. بالنسبة إلى gpt-image-2 استخدم auto أو WIDTHxHEIGHT؛ يجب أن تكون الأبعاد من مضاعفات 16، وأطول ضلع لا يتجاوز 3840px، ونسبة الطويل إلى القصير لا تتجاوز 3:1، وإجمالي البكسلات بين 655,360 و8,294,400.

response_formatstringالافتراضي: url

تنسيق إرجاع الصور المُنشأة. يجب أن يكون url أو b64_json؛ والقيمة الافتراضية هي url.

يعيد url روابط الصور في data[].url، ويعيد b64_json بيانات الصور بترميز Base64 في data[].b64_json.

asyncbooleanالافتراضي: false

اضبطه على true مع gpt-image-2 أو نماذج تحرير FLUX/BFL الرسمية لإرجاع مهمة قبل أن تكون الصورة النهائية جاهزة. تعيد التحريرات غير المتزامنة المكتملة روابط URL بغض النظر عن response_format المطلوب؛ استخدم الطلبات المتزامنة إذا كنت تحتاج إلى b64_json.

userstring

معرف فريد يمثل المستخدم النهائي لمراقبة سوء الاستخدام.

الاستجابة

createdinteger

الطابع الزمني Unix لوقت إنشاء الصور.

dataarray

مصفوفة الصور المُنشأة.

كل عنصر يحتوي على:

  • 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 "model=gpt-image-2" \
  -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://..."
    }
  ]
}

ملاحظات

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

ينشئ Hy Image 3.5 Preview صورًا مربعة بدقة 1024 بكسل انطلاقًا من النص، ويعدّل الصور المرجعية وفق تعليمات مكتوبة. يفيد في إعداد المسودات البصرية وتحسين التكوين.

{
  "model": "hy-image-v3.5-preview",
  "prompt": "Change the table to pale blue",
  "image_url": "https://example.com/reference.png",
  "size": "1024x1024",
  "n": 1,
  "response_format": "url"
}

التفويض

BearerAuth
AuthorizationBearer <token>

مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.

الموضع: header

الترويسات

X-TokenLab-Delivery-Policy?string

سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.

القيم المتاحة

  • "auto"
  • "verified"
  • "official"

جسم الطلب

الاستجابة

application/json

application/json

application/json

application/json

application/json

application/json

إنشاء صورة

السابق

إنشاء تنويع صورة

التالي