أدلة الوسائط
توليد الصور
توليد أو تعديل الصور والتعامل مع الملفات الجاهزة أو المهام غير المتزامنة
يدعم 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
| الموضوع | المرجع |
|---|---|
| إنشاء صورة | إنشاء صورة |
| تعديل صورة | تعديل صورة |
| إنشاء تباين صورة | إنشاء تباين صورة |
| الحصول على حالة الصورة | الحصول على حالة الصورة |
| الحصول على حالة المهمة | الحصول على حالة المهمة |