أدلة الوسائط

توليد الصور

توليد أو تعديل الصور والتعامل مع الملفات الجاهزة أو المهام غير المتزامنة

يدعم TokenLab تحويل النص إلى صورة، وتحويل صورة إلى صورة، وتعديل الصور. تختلف المعلمات (Parameters) حسب النموذج، لذا تحقق من حقول الطلب الخاصة بالنموذج المختار قبل إرسال الطلب.

اختيار نقطة النهاية (Endpoint)

ما تحتاجهنقطة النهايةاستخدمها عندمالا تستخدمها لـ
نص إلى صورةPOST /v1/images/generationsيبدأ المستخدم بنص فقطتعديل ملف GPT Image موجود
صورة إلى صورةPOST /v1/images/generationsيقبل النموذج operation: "image-to-image" وروابط الصورالنماذج التي تتطلب إدخال تعديل متعدد الأجزاء (multipart)
تعديل صورةPOST /v1/images/editsيقوم نموذج تعديل مدعوم بتغيير صورة موجودةتوليد مرجع بنمط Nano Banana
تباين (Variation)POST /v1/images/variationsيستخدم تكامل موجود بالفعل API التبايناتميزة صورة مرجعية جديدة
الحالةGET /v1/tasks/{id}استجابة الإنشاء تعيد task_id أو status: "pending" أو poll_urlاستجابة الإنشاء تحتوي بالفعل على data[] النهائية

قم دائماً بإرسال model؛ حيث لا تقوم واجهات برمجة تطبيقات الصور باختيار نموذج افتراضي نيابة عنك.

اختيار نموذج

اعثر على نماذج الصور الحالية باستخدام:

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

افتح تفاصيل النموذج المختار للتأكد من:

  • العملية المدعومة، مثل text-to-image أو image-to-image أو image-edit.
  • نقطة نهاية الطلب المتوقعة من قبل النموذج.
  • كيفية إرسال المراجع: image_url أو image_urls أو reference_image_urls أو image متعدد الأجزاء أو images[] بتنسيق JSON.
  • ما إذا كان النموذج يقبل size أو aspect_ratio أو resolution أو quality أو background أو output_format أو response_format.

الحقول الخاصة بالنموذج

  • تستخدم الطلبات بنمط gpt-image-2 حقول size و quality وحقول التعديل المشابهة لـ OpenAI. بالنسبة للتوليد والتعديلات باستخدام هذا النموذج، يقبل background القيمة auto أو opaque؛ بينما لا يتم دعم transparent. احذف الحقول الاختيارية لاستخدام الإعدادات الافتراضية التلقائية.
  • تستخدم عائلات صور Gemini و Nano Banana عادةً aspect_ratio؛ لا ترسل resolution إلا عندما تظهر في تفاصيل النموذج. في النماذج ذات مستويات الدقة، يتم إرسال size بقيمة 1K أو 2K أو 4K كـ resolution؛ سيتم رفض أي مستوى يختلف عن resolution.
  • ينتمي Nano Banana (صورة إلى صورة) إلى /v1/images/generations مع operation: "image-to-image" وروابط الصور المرجعية.
  • لا تقبل /v1/images/generations حقل images[] أو file_id على المستوى الأعلى؛ فهذه أشكال خاصة بمسار التعديل.
  • يجب أن تكون مراجع الصور البعيدة روابط http أو https عامة. لا ترسل روابط شبكة خاصة، أو بيانات اعتماد مضمنة، أو أجزاء روابط (URL fragments)، أو روابط موقعة قد تنتهي صلاحيتها قبل بدء المعالجة.

مثال على تحويل النص إلى صورة

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean product photo of a ceramic coffee cup on a walnut desk",
    "size": "1024x1024",
    "response_format": "url"
  }'

مثال على الصورة المرجعية

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "operation": "image-to-image",
    "prompt": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

الحصول على الصورة

يمكن أن تكون استجابات الصور متزامنة أو غير متزامنة:

  • تعيد الاستجابات المتزامنة data[] النهائية مع url أو b64_json.
  • تعيد الاستجابات غير المتزامنة id و task_id و status وعادةً poll_url. أرسل "async": true على نموذج يدعم التنفيذ غير المتزامن العام للحصول على مهمة بدلاً من انتظار الصورة.
  • للتحقق من مهمة غير متزامنة، اتصل بـ GET /v1/tasks/{id} باستخدام id أو task_id المعاد.
  • استخدم طلباً متزامناً عندما تحتاج إلى b64_json؛ حيث تستخدم نتائج الصور غير المتزامنة روابط (URLs).

روابط نتائج الصور هي روابط وسائط TokenLab التي تظل صالحة لمدة 30 يوماً. يقوم media_retention.items بالإبلاغ عن حالة حفظ كل عنصر و expires_at؛ قد تحذف الاستجابة media_retention عندما لا تكون حالة الحفظ معروفة في الوقت المناسب، وسيظل الرابط يعمل. نتائج Base64 المضمنة تقع خارج نطاق الاحتفاظ بنسخ الروابط هذا. حفظ الصورة يدوياً في مكتبة الوسائط يمنحها دورة حياة منفصلة. راجع الاحتفاظ بالبيانات.

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

احتفظ برابط الصورة المعادة، ومعرف المهمة (task ID)، والنموذج، ومعرف المستخدم/الوظيفة الخاص بك. لا تستمر في الاستعلام (polling) بعد الوصول إلى حالة نهائية.

قبل الإطلاق

  • تحقق من مدخلات المستخدم قبل الاتصال بـ TokenLab: طول النص (prompt)، وعدد الصور، وإمكانية الوصول إلى الرابط، ونوع الملف.
  • اضبط مهلات HTTP (timeouts) لتكون عالية بما يكفي للطلبات المتزامنة عالية الدقة. استخدم async: true حيثما يدعم النموذج ذلك للمهام الطويلة.
  • قم بتخزين request_id و task_id و poll_url والنموذج ونقطة النهاية وأسماء الحقول المرسلة.
  • عندما يعيد طلب الصورة مهمة، فإن Idempotency-Key يجعل طلب الإنشاء آمناً لإعادة المحاولة: بعد مهلة العميل، أرسل نفس الطلب بنفس المفتاح للحصول على تلك المهمة. بالنسبة لطلب يعيد الصورة مباشرة، قد تؤدي إعادة المحاولة بنفس المفتاح إلى إرجاع حالة مهمة بدلاً من الصورة، أو 409 مع idempotent_response_not_replayable. بدون مفتاح، تحقق مما إذا كانت المهمة قد تم إنشاؤها قبل إعادة المحاولة.
  • استخدم Usage و billing_transaction_id للرسوم النهائية.

الأخطاء الشائعة

العرضالسبب المحتملالحل
400 مع param: "model"فقدان النموذج الصريحاستعلم عن /v1/models?recommended_for=image وأرسل model
حقل غير مدعومالحقل غير موثق لهذا النموذجاحذف الحقل أو اختر نموذجاً/نقطة نهاية توثقه
لا يوجد b64_json في النتيجة غير المتزامنةمهام الصور غير المتزامنة تعيد نتائج موجهة للروابطاستخدم الوضع المتزامن لمخرجات base64
رفض الصورة المرجعيةنقطة نهاية خاطئة أو رابط خاص/منتهي الصلاحيةطابق شكل المرجع الموثق للنموذج واستخدم روابط يمكن الوصول إليها

مرجع API

الموضوعالمرجع
إنشاء صورةإنشاء صورة
تعديل صورةتعديل صورة
إنشاء تباين صورةإنشاء تباين صورة
الحصول على حالة الصورةالحصول على حالة الصورة
الحصول على حالة المهمةالحصول على حالة المهمة

في هذه الصفحة