واجهة برمجة تطبيقات تعديل الصور GPT Image على TokenLab: نقطة النهاية الصحيحة وأشكال إدخال الصور

تُعد معالجة الصور وتعديلها من أكثر الأجزاء تطلباً في واجهة أي منتج للذكاء الاصطناعي: يقوم المستخدم برفع صورة، ويصف التعديل المطلوب، ويتوقع نتيجة فورية. إن التعديلات التي تستخدم عدة صور مصدرية، أو مساحة عمل كبيرة، أو موجهاً وصفياً (prompt) ثقيلاً تستغرق وقتاً أطول مما يسمح به استدعاء HTTP المتزامن العادي بأريحية. يغطي هذا الدليل نقطة نهاية TokenLab الصحيحة، والشكلين المدعومين لإدخال الصور، والتعديلات متعددة الصور، والمسار غير المتزامن (async) للطلبات التي تستغرق وقتاً طويلاً.

نقطة النهاية

تتواجد خدمة تعديل الصور عند POST /v1/images/edits — لاحظ صيغة الجمع edits. (من الأخطاء الشائعة كتابة /images/edit، وهو ليس المسار الموثق).

تدعم نقطة النهاية شكلين للطلب:

• تدفق رفع عبر multipart/form-data متوافق مع OpenAI.
• طلب JSON يوفّر مراجع image_url أو image_urls أو images[] الرسمية لعائلات تحويل صورة إلى صورة (image-to-image) المدعومة.

تم توثيق حقول الطلب والاستجابة الكاملة في مرجع واجهة برمجة تطبيقات تعديل الصور (Edit Image API reference).

ما يقبله gpt-image-2 هنا

• عمليات رفع image بصيغة Multipart.
• image_url أو image_urls عبر JSON.
• مراجع images[] الرسمية، حيث يحتوي كل كائن على واحد فقط تحديداً من image_url أو file_id.
• ما يصل إلى 16 صورة مصدرية لكل طلب.

بعض القيود التي يجدر بك معرفتها قبل كتابة التعليمات البرمجية:

• تعديلات gpt-image-2 لا تقبل resolution؛ استخدم size لأبعاد المخرجات (إما auto أو WIDTHxHEIGHT، بحيث تكون الأبعاد بمضاعفات العدد 16، وأطول حافة 3840px كحد أقصى، ونسبة الطول/العرض 3:1 كحد أقصى).
• يقبل background كلاً من auto أو opaque؛ ولا يدعم transparent.
• لا يُعد input_fidelity جزءاً من الحقول المدعومة لـ gpt-image-2؛ وإرساله يؤدي إلى إرجاع 400 unsupported_parameter.
• بالنسبة لطلبات JSON، قدّم واحداً فقط تحديداً من image_url أو image_urls أو images. يجب أن يحتوي كل كائن ضمن images[] على واحد فقط تحديداً من image_url أو file_id. ويجب إنشاء قيم file_id عبر /v1/files أولاً.
• تنتمي طلبات الصور المرجعية Nano Banana إلى /v1/images/generations مع operation: "image-to-image" و image_urls — وليس إلى /v1/images/edits.

عمليات رفع Multipart مقابل مراجع صور JSON

كلاهما يعمل مع gpt-image-2. اختر الطريقة التي تتوافق مع مكان تخزين بايتات صورتك حالياً.

Multipart — استخدم هذا الخيار عندما يحتوي تطبيقك على الملف بالفعل، سواء من خلال رفع مستخدم أو من أصل مُنشأ برمجياً. كرر حقل image لإرسال عدة مصادر. يجب أن تكون الملفات بصيغة PNG أو JPEG أو WebP، وبحجم أقصاه 50 MiB لكل ملف.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@subject.png" \
  -F "image=@background.png" \
  -F "prompt=Combine the subject with the new background." \
  -F "size=1024x1024"

عناوين JSON لمواقع الصور (JSON image URLs) — استخدم هذا الخيار عندما تكون الصور موجودة بالفعل على عنوان URL عام، أو عندما تكون قد أنشأتها في طلب TokenLab سابق ولديك عنوان URL لها مسبقاً.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "images": [
      {"image_url": "https://example.com/subject.png"},
      {"image_url": "https://example.com/background.png"}
    ],
    "prompt": "Combine the subject with the new background.",
    "size": "1024x1024",
    "async": true
  }'

يجب أن تكون عناوين URL البعيدة بروتوكولات عامة مثل http/https، وخالية من بيانات الاعتماد المضمنة أو الأجزاء (fragments)، ويجب ألا تشير إلى localhost أو نطاقات عناوين IP الخاصة أو المحجوزة. يجلب TokenLab البايتات ويسلمها للنموذج كأجزاء image متعددة الأجزاء (multipart). الحد الأقصى لكل صورة هو 50 MiB؛ والحد الإجمالي للصور المجلوبة عبر URL في طلب واحد هو 200 MiB؛ ومهلة الجلب هي 30 ثانية؛ ويتم تتبع ما يصل إلى 3 عمليات إعادة توجيه.

التعديلات متعددة الصور والاستقصاء غير المتزامن

تُعد التعديلات متعددة الصور الحالة الأكثر وضوحاً لاستخدام async: true. إن إرسال عدة صور مع مجموعة تعليمات معقدة من خلال استدعاء متزامن يعني إبقاء الاتصال مفتوحاً للمدة التي يحتاجها النموذج مهما طالت. عيّن async: true على gpt-image-2 (وكذلك على نماذج تعديل FLUX/BFL الرسمية) لتلقي مهمة بدلاً من ذلك:

{
  "created": 1706000000,
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "data": []
}

قم باستقصاء رابط poll_url المُرجع، أو الجأ كخيار بديل إلى GET /v1/tasks/{task_id}. الحالات الممكنة هي pending و processing و completed و failed. تُرجع مهمة الصورة المكتملة data[].url. يُعد التحقق كل 3-5 ثوانٍ كافياً؛ توقف عند الوصول إلى حالة نهائية بدلاً من الاستمرار في الاستقصاء.

curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"

تُرجع مهام التعديل غير المتزامنة عناوين URL للصور النهائية بغض النظر عن response_format المطلوب. إذا كنت بحاجة إلى صيغة b64_json الخام، فاستخدم طلباً متزامناً.

قد يقوم نظام الفوترة بحجز المبلغ التقديري عند إنشاء المهمة؛ وتتم فوترة المهمة المكتملة وفقاً للاستخدام الفعلي، بينما تقوم المهمة الفاشلة أو التي انتهت مهلتها بتحرير الحجز أو استرداده. راجع المهام غير المتزامنة والاستقصاء (Async jobs and polling) لدورة الحياة الكاملة، و الحصول على حالة الصورة (Get Image Status) لحقول الاستجابة.

متى تستخدم كل وضع

استخدم async: true عندما:

• ترسل صوراً مصدرية متعددة في طلب واحد.
• يكون الموجه أو مجموعة التعليمات معقدة بما يكفي ليكون وقت الإنشاء غير متوقع.
• تقوم بتشغيل التعديلات في مهمة خلفية (background job)، أو طابور انتظار (queue)، أو عملية دُفعية (batch process) بدلاً من طلب مباشر يواجه المستخدم.

ابق على الوضع المتزامن عندما:

• تجري تعديلاً على صورة واحدة بموجّه قصير.
• يفضل عميلك الفشل السريع بدلاً من الاستقصاء.

بالنسبة للمكالمات المتزامنة، اضبط مهلة عميل HTTP لديك على 120s على الأقل؛ فالطلبات ذات الدقة العالية أو الجودة الفائقة قد تستغرق ما يقارب دقيقة أو أكثر. إذا استمرت استجابة الإنشاء في العودة مع status: "pending" أو task_id أو poll_url، فانتقل إلى تدفق الاستقصاء المُرجع.

أخطاء الإدخال المتوقعة

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

تستخدم نماذج تعديل الصور xAI Grok Imagine (على سبيل المثال grok-imagine-image و grok-imagine-image-quality) حقول الإدخال نفسها ولكنها تحدد سقف الصور المصدرية بـ 3 صور؛ وإرسال أكثر من ذلك يرجع 400 too_many_images.

قائمة التحقق للتكامل

• استهدف POST /v1/images/edits وأرسل الـ model بشكل صريح.
• اختر عمليات رفع multipart أو مراجع JSON بناءً على المكان الذي تعيش فيه صورك بالفعل.
• أرسل واحداً فقط تحديداً من image_url أو image_urls أو images[] في طلبات JSON؛ ويحتوي كل إدخال في images[] على واحد فقط تحديداً من image_url أو file_id.
• استخدم async: true للتعديلات متعددة الصور أو الثقيلة؛ وقم باستقصاء poll_url المُرجع حتى تصل المهمة إلى completed أو failed.
• اضبط مهلات العميل على 120 ثانية على الأقل للطلبات المتزامنة، وتعامل مع استجابة pending باتباع poll_url.
• عند انتهاء مهلة العميل، تحقق مما إذا كانت هناك مهمة قد أُنشئت قبل إعادة محاولة طلب الإنشاء لتجنب التكاليف المكررة.

ابدأ الآن

استعلم عن GET /v1/models?recommended_for=image لمعرفة نماذج الصور الحالية، ثم افتح صفحة تفاصيل النموذج للتأكد من عملياته المدعومة وحقول الطلب قبل إرسال الطلب. أنشئ مفتاح API من لوحة التحكم لاختبار نقطة نهاية التعديل باستخدام صورك الخاصة.