الأدلة الأساسية
المهام غير المتزامنة (Async jobs) والاستطلاع (Polling)
إنشاء مهام الوسائط وانتظار النتيجة النهائية
تُرجع العديد من نقاط نهاية الوسائط مهمة بدلاً من ملف جاهز. احفظ معرف المهمة (task ID) المُرجع وقم باستطلاع GET /v1/tasks/{id} حتى تصبح الحالة completed (مكتملة) أو failed (فاشلة). تخدم نقطة النهاية هذه مهام الصور، والفيديو، والموسيقى، والـ 3D، والـ Worlds، ونسخ الصوت غير المتزامن.
تتمتع لقطات المهام الطرفية غير المتزامنة بدورة حياة منفصلة عن نافذة التقاط الطلب/الاستجابة التي تبلغ 30 يوماً. روابط ملفات الصور والفيديو والصوت والـ 3D والـ Worlds التي يتم إنشاؤها هي روابط وسائط TokenLab تظل صالحة لمدة 30 يوماً. تعمل قراءات حالة المهام المنتهية لمدة 7 أيام تقريباً، لذا احفظ النتيجة بمجرد اكتمال المهمة. تُبلغ حقول media_retention في الاستجابة عن حالة حفظ كل عنصر وتاريخ انتهاء صلاحيته expires_at؛ قد تكون هذه الحقول غائبة عندما لا تُعرف حالة الحفظ في الوقت المناسب، ومع ذلك يظل الرابط يعمل. تُرجع المهام الفاشلة والتي قيد التنفيذ حقول روابط وسائط فارغة. راجع الاحتفاظ بالبيانات.
الحقول المطلوب حفظها
يمكن أن تتضمن استجابات الإنشاء ما يلي:
| الحقل | المعنى | ما يجب فعله |
|---|---|---|
id | معرف مهمة TokenLab | احفظه مع سجل الوظيفة الخاص بك |
task_id | اسم آخر لنفس معرف المهمة | تعامل معه كمعادل لـ id |
status | حالة المهمة الحالية | استمر في التحقق حتى تنتهي أو تفشل |
poll_url | رابط الحالة للمهمة | احفظه؛ قم باستطلاع /v1/tasks/{id} باستخدام معرف المهمة |
model | النموذج المستخدم للمهمة | احفظه مع سجل المهمة |
نقطة نهاية واحدة للحالة
قم باستطلاع GET /v1/tasks/{id} باستخدام id أو task_id من استجابة الإنشاء. تعمل هذه الطريقة مع كل أنواع المهام. بالنسبة لمعظم المهام، يكون poll_url هو نفس هذا المسار. تُرجع استجابة إنشاء Worlds رابط poll_url تحت /v1/worlds/generations/{id}؛ قم باستطلاع /v1/tasks/{id} باستخدام معرف المهمة id لمهام Worlds أيضاً.
تظل مسارات الحالة الخاصة بكل نمط، مثل /v1/videos/generations/{id}، مدعومة لعمليات التكامل الحالية. يجب أن تستخدم عمليات التكامل الجديدة /v1/tasks/{id}.
حفظ المهمة والتحقق من حالتها
احفظ id أو task_id بمجرد نجاح طلب الإنشاء. قم بتخزين poll_url والنموذج ونقطة النهاية ومعرف المستخدم أو الوظيفة الخاص بك معها. بالنسبة لمهام الوسائط الطويلة، عادة ما يكون التحقق كل 5–10 ثوانٍ كافياً.
توقف عندما تصبح الحالة completed أو failed. تحتوي المهمة المكتملة على نتيجة الوسائط؛ وتحتوي المهمة الفاشلة على الخطأ الذي يمكنك عرضه أو تسجيله. إعادة محاولة إنشاء فاشل تؤدي إلى إنشاء مهمة جديدة وقد تؤدي إلى تكلفة جديدة.
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"model": "veo3.1"
}مثال على الاستطلاع (Polling)
curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
-H "Authorization: Bearer sk-your-api-key"الحالات هي pending (قيد الانتظار)، وprocessing (قيد المعالجة)، وcompleted (مكتملة)، وfailed (فاشلة). تستخدم المهمة الملغاة failed مع cancelled: true و cancellation_status: "cancelled".
تُرجع قراءة الحالة الناجحة HTTP 200 حتى عندما تكون المهمة قد فشلت. استخدم status الخاصة بالمهمة لتقرر ما إذا كان الإنشاء قد نجح. يحتفظ حقل error بشكله كسلسلة نصية أو كائن. قد تتضمن المهام الفاشلة أيضاً error_details مع status (حالة خطأ العمل)، وtype (النوع)، وcode (الرمز)، وmessage (الرسالة)، وparam (المعامل)، وretryable (قابلية إعادة المحاولة). على سبيل المثال، error_details.status: 400 مع param: "size" يعني أن الطلب يحتاج إلى تصحيح؛ ولا يعني أن طلب الحالة نفسه قد فشل. يتم حذف param عندما لا يُعرف حقل محدد. عندما يكون error_details.projection_version هو 2، تكون message هي السبب النهائي للفشل، وعادة ما تكون تفسير الخدمة الأولية (upstream service)، مثل حد المعاملات أو قرار سياسة المحتوى. بالنسبة لمهمة تم تشغيلها على مسار رسمي (Official route)، يحمل error_details.upstream أيضاً خطأ الخدمة الأولية كما تم الإبلاغ عنه: message، بالإضافة إلى code وparam وsource (اسم الخدمة الأولية) عند معرفته. استمر في التفريع بناءً على code وtype؛ قيم upstream.code محددة بواسطة الخدمة الأولية وقد تتغير.
الأخطاء التي ترفض طلب الإنشاء قبل قبول المهمة تستخدم حالة خطأ HTTP العادية وكائن error المهيكل. تكرار نفس طلب الإنشاء المتماثل (idempotent) يحافظ على هذا الرفض. قراءة الحالة الفاشلة لا تغير الحالة النهائية للمهمة.
تجنب المهام المكررة
تأتي معظم عمليات الإنشاء المكررة من إعادة محاولة طلب الإنشاء بعد انتهاء المهلة (timeout).
| متى تحدث المهلة | السلوك الأكثر أماناً |
|---|---|
| قبل أن يتلقى خادمك استجابة الإنشاء | أرسل نفس الطلب مرة أخرى مع نفس Idempotency-Key للحصول على المهمة الأصلية. بدون مفتاح، تحقق من request_id وأعد المحاولة فقط إذا لم يتم إنشاء أي مهمة |
| بعد تخزين استجابة الإنشاء | استأنف استطلاع task_id المخزن |
| أثناء الاستطلاع | أعد محاولة طلب الحالة مع التراجع (backoff) |
| بعد الحالة النهائية | لا تقم بالاستطلاع مرة أخرى إلا إذا قام المستخدم بتحديث السجل صراحةً |
لا ترسل طلب إنشاء ثانٍ لمجرد أن المتصفح قد تم تحديثه أو فشل استطلاع الحالة.
سجلات الفوترة
قد تحجز المهمة غير المتزامنة تكلفتها المقدرة عند قبولها. يتم تسجيل المبلغ النهائي بعد انتهاء المهمة أو فشلها. قد تتضمن استجابات الحالة billing_transaction_id ورأس X-Billing-Transaction-ID.
احتفظ بهذه المعرفات معاً:
request_idمن طلب الإنشاء.task_id/idمن المهمة.billing_transaction_idعند وجوده.- معرف المستخدم أو معرف المشروع أو معرف الوظيفة الخاص بك.
الإلغاء
يمكن لـ DELETE /v1/tasks/{id} إلغاء مهام فيديو Seedance المدعومة أثناء وجودها في قائمة الانتظار، بما في ذلك seedance-2.0 و seedance-2.0-fast.
تُرجع المهام غير المدعومة 400 unsupported_task_cancel. تُرجع المهمة التي تعمل بالفعل أو انتهت 409 task_not_cancellable. الإلغاء هو طلب، وليس ضماناً بأن العمل الجاري بالفعل سيتوقف. يُرجع الإلغاء الناجح 200 مع status: "failed" و cancelled: true و cancellation_status: "cancelled". المهمة الملغاة لا يتم محاسبتك عليها.
استكشاف الأخطاء وإصلاحها
| العرض | السبب المحتمل | ما يجب التحقق منه |
|---|---|---|
404 async_task_not_found | معرف المهمة غير معروف، أو ينتمي إلى مساحة عمل أخرى، أو أن المهمة المنتهية تجاوزت نافذة الحالة الخاصة بها | تحقق من task_id المحفوظ ومساحة عمل مفتاح API |
403 task_not_owned | لا يمكن تأكيد ملكية المهمة لمساحة العمل الحالية | أكد مساحة العمل أو المؤسسة المرتبطة بمفتاح API |
503 async_task_owner_unavailable | تعذر التحقق من ملكية المهمة في الوقت الحالي. retryable هو true | أعد محاولة طلب الحالة مع التراجع (backoff) |
| المهمة لا تبدو وكأنها تنتهي أبداً | العميل يستمر في استطلاع الرابط الخطأ أو توقف قبل الحالة النهائية | قم باستطلاع GET /v1/tasks/{id} باستخدام معرف المهمة المحفوظ وافحص الحالة الأخيرة |
| رابط الوسائط النهائي مفقود | المهمة لم تكتمل، أو انتهت بدون ملف قابل للاستخدام | استمر في الاستطلاع حتى تنتهي، ثم تعامل مع النتيجة المفقودة على أنها فاشلة |
| المستخدم يرى تكرارات | مسار إعادة المحاولة أنشأ مهمة جديدة بعد انتهاء المهلة أو التحديث | قم بإزالة التكرار بواسطة معرف الوظيفة الخاص بك و task_id المخزن |
| عدم تطابق الفوترة | لم يتم تسجيل الفوترة النهائية بعد، أو تتم مقارنة معرفات خاطئة | قارن request_id و task_id و billing_transaction_id |
ما يجب إرساله للدعم
قم بتضمين request_id و task_id و billing_transaction_id عند وجوده، ونقطة النهاية، والنموذج، والوقت، وأسماء الحقول التي أرسلتها. لا ترسل أبداً مفاتيح API، أو وسائط خاصة، أو روابط موقعة، أو مطالبات (prompts) كاملة إلا إذا طلب الدعم تحديداً مثالاً منقحاً.
مرجع API
| الموضوع | المرجع |
|---|---|
| الحصول على حالة المهمة | الحصول على حالة المهمة |
| إلغاء المهمة | إلغاء مهمة |
| إنشاء الصور | Image Generation |
| إنشاء الفيديو | توليد الفيديو |
| إنشاء الموسيقى | Music Generation |
| إنشاء الـ 3D | 3D Generation |
| الفوترة والأسعار | Billing & Pricing |
توقف عن استطلاع المهام النهائية، وتوقف عند 401 أو 403 أو 404 أو أي خطأ لا يمكن إعادة محاولته. لتلقي نتائج المهام بدون استطلاع، قم بتهيئة API إدارة Webhook باستخدام رمز إدارة mt-….
تحمل استجابات المهام أيضاً رؤوس X-Task-ID و X-Task-Type و X-Billing-Transaction-ID، والتي يمكنك تسجيلها بجوار معرف المهمة.