الانتقال إلى المحتوى الرئيسي
العديد من نقاط النهاية للوسائط غير متزامنة. تبدأ طلبات الإنشاء العمل وتعيد هوية مهمة عامة من TokenLab؛ يقوم تطبيقك بالاستطلاع حتى تصل تلك المهمة إلى حالة نهائية. لا تبني سير عمل العملاء حول عناوين URL لمهام المصدر، أو معرفات التوجيه، أو سلوك ردود مزود الخدمة.

​
عقد المهمة العامة

يمكن أن تتضمن استجابات الإنشاء:
الحقلالمعنىماذا تفعل
idمعرف مهمة TokenLab العامةخزنه مع سجل وظيفتك الخاص
task_idاسم مستعار للتوافق لنفس هوية المهمة العامةاعتبره معادلاً لـ id
statusالحالة الحالية للمهمة العامةابدأ الاستطلاع عندما لا تكون نهائية
poll_urlعنوان URL المفضل للحالةاستخدم هذا أولاً عند وجوده
modelالنموذج المطلوب أو الذي تم حله بواسطة نقطة النهايةخزنه للدعم وتسوية الفواتير
/v1/tasks/{id} هو نقطة النهاية الثابتة القياسية لحالة وظائف الوسائط العامة غير المتزامنة. قد توجد مسارات حالة محددة للوسائط للتوافق، ولكن يجب أن تفضل التكاملات الجديدة poll_url أو /v1/tasks/{id}.

​
التدفق الموصى به

  1. تحقق من طلب المستخدم وأرسل مكالمة الإنشاء مع model صريح.
  2. احتفظ بـ id / task_id، poll_url، نقطة النهاية، النموذج، معرف المستخدم، ومعرف وظيفتك الخاص قبل إعادة التحكم إلى واجهة المستخدم.
  3. استطلع كل 5-10s للمهام الطويلة الأمد.
  4. توقف فقط عندما تكون المهمة مكتملة أو فشلت.
  5. عند الاكتمل، اقرأ حقول النتائج الخاصة بالوسائط وخزن عناوين URL النهائية أو البيانات الوصفية.
  6. عند الفشل، خزّن الخطأ العام وقدم إعادة المحاولة فقط كوظيفة جديدة مرئية للمستخدم.
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "model": "veo3.1"
}

​
مثال على الاستطلاع

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" بحيث تستمر معالجة الحالة القديمة في العمل.

​
قواعد إعادة المحاولة للعميل

تعتبر مهلات الشبكة المصدر الأكثر شيوعًا للوظائف المكررة. استخدم هذه القاعدة:
أين تحدث المهلةسلوك أكثر أمانًا
قبل أن يستقبل خادمك استجابة الإنشاءتحقق من سجلات الخادم لـ request_id؛ أعد المحاولة فقط إذا لم يتم إنشاء أي مهمة
بعد تخزين استجابة الإنشاءاستأنف الاستطلاع لـ task_id المخزنة
أثناء الاستطلاعأعد المحاولة لطلب الحالة مع التراجع
بعد الحالة النهائيةلا تستطلع مرة أخرى إلا إذا قام المستخدم بتحديث السجل بشكل صريح
لا ترسل طلب إنشاء ثانٍ لمجرد أن المتصفح تم تحديثه أو فشل استطلاع الحالة.

​
الفوترة والتسوية

يمكن أن تحتفظ الوظائف غير المتزامنة بمبلغ تقديري عندما يتم قبول طلب الإنشاء. تحدث التسوية النهائية بعد الحالة النهائية. عندما تكون متاحة، يمكن أن تكشف استجابات حالة المهمة عن billing_transaction_id ورأس X-Billing-Transaction-ID. للتسوية، انضم إلى هذه المعرفات في سجلاتك:
  • request_id من طلب الإنشاء.
  • task_id / id من المهمة.
  • billing_transaction_id عند وجوده.
  • معرف المستخدم الخاص بك، معرف المشروع، أو معرف الوظيفة.

​
الإلغاء

DELETE /v1/tasks/{id} ضيق عن عمد. يدعم حاليًا مهام فيديو Volcengine Seedance المعلقة مثل seedance-1.5-pro، seedance-2.0، و seedance-2.0-fast. تعود المهام غير المدعومة بـ 400 unsupported_task_cancel. المهام التي تعمل بالفعل أو النهائية تعود بـ 409 task_not_cancellable. قم ببناء واجهة إلغاء كـ “طلب الإلغاء” بدلاً من زر توقف مضمون.

​
استكشاف الأخطاء وإصلاحها

العرضالسبب المحتملماذا تتحقق
async_task_not_foundالمهمة غير معروفة، منتهية، غير قابلة للوصول إلى مفتاح API هذا، أو ليست مهمة غير متزامنة عامةتأكد من ملكية مفتاح API و task_id العامة المخزنة
المهمة لا تظهر أبدًا على أنها مكتملةيستمر العميل في استطلاع عنوان URL الخطأ أو توقف قبل الحالة النهائيةاستخدم poll_url أو /v1/tasks/{id} وتفقد الحالة الأخيرة
عنوان URL النهائي للوسائط مفقودالمهمة لم تكتمل، أو أكمل العمل العلوي بدون مخرجات قابلة للاستخداماستمر في الاستطلاع حتى النهاية، ثم تعامل مع المخرجات المفقودة على أنها فشلت
المستخدم يرى مكرراتأنشأ مسار إعادة المحاولة مهمة جديدة بعد المهلة أو التحديثقم بإزالة التكرار بواسطة معرف وظيفتك الخاص و task_id المخزنة
عدم تطابق الفوترةالتسوية غير متزامنة أو العميل يقارن معرفات المزودقارن request_id، task_id، و billing_transaction_id

​
حزمة الدعم

عند الاتصال بالدعم، قم بتضمين request_id، task_id، billing_transaction_id عند وجوده، نقطة النهاية، النموذج، الطابع الزمني، وشكل الطلب المنقح. لا تتضمن مفاتيح API، الوسائط الخاصة، عناوين URL الموقعة، أو المطالبات الكاملة ما لم يطلب الدعم عينة منقحة.

​
مرجع API

الموضوعالمرجع
الحصول على حالة المهمةالحصول على حالة المهمة
إلغاء المهمةإلغاء المهمة
إنشاء الصورإنشاء الصور
إنشاء الفيديوإنشاء الفيديو
إنشاء الموسيقىإنشاء الموسيقى
إنشاء ثلاثي الأبعادإنشاء ثلاثي الأبعاد
الفوترة والتسعيرالفوترة والتسعير