الأدلة الأساسية

المهام غير المتزامنة (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
إنشاء الـ 3D3D Generation
الفوترة والأسعارBilling & Pricing

توقف عن استطلاع المهام النهائية، وتوقف عند 401 أو 403 أو 404 أو أي خطأ لا يمكن إعادة محاولته. لتلقي نتائج المهام بدون استطلاع، قم بتهيئة API إدارة Webhook باستخدام رمز إدارة mt-….

تحمل استجابات المهام أيضاً رؤوس X-Task-ID و X-Task-Type و X-Billing-Transaction-ID، والتي يمكنك تسجيلها بجوار معرف المهمة.

في هذه الصفحة