دليل TokenLab لإلغاء مهام Seedance وفوترة المهام الموجودة في قائمة الانتظار

تُعد مهام توليد الفيديو غير متزامنة. عندما ترسل طلب توليد فيديو عبر POST /v1/videos/generations، تُرجع TokenLab معرّف المهمة وتضع المهمة في قائمة الانتظار. إذا تم إرسال طلب عن طريق الخطأ، أو تكرر أثناء إعادة محاولة على الشبكة، أو تخلى عنه المستخدم النهائي، فإن إلغاء المهمة أثناء وجودها في قائمة الانتظار يمنع فرض رسوم حوسبة وتوليد غير ضرورية.

يوضح هذا الدليل كيفية استدعاء نقطة نهاية إلغاء المهمة، والتعامل مع رموز استجابة واجهة برمجة التطبيقات (API)، وإدارة حجوزات الفوترة وانتقالات الاستقصاء.

آلية عمل إلغاء المهام

يستهدف إلغاء المهام الوظائف غير المتزامنة التي لا تزال في قائمة الانتظار بحالة pending. بمجرد أن يبدأ عامل النموذج في توليد الإطارات (مما ينقل المهمة إلى الحالة processing) أو تصل المهمة إلى حالة نهائية (completed أو failed)، لا يمكن إجراء الإلغاء بعد ذلك.

تدعم TokenLab الإلغاء في نماذج فيديو Seedance الموجودة في قائمة الانتظار بما في ذلك seedance-2.0، وseedance-2.0-fast، وseedance-2.5. بالنسبة لعمليات التكامل التي تستخدم نقطة نهاية التوافق مع Volcengine، راجع مرجع إلغاء المهام المتوافقة مع Volc.

حالات دورة حياة المهمة

• pending: المهمة في قائمة الانتظار وتنتظر عاملاً متاحاً. الإلغاء مدعوم في هذه النافذة الزمنية.
• processing: بدأ تنفيذ النموذج. سيتم رفض طلبات الإلغاء.
• completed: اكتمل توليد الفيديو بنجاح. النتيجة جاهزة.
• failed: واجهت المهمة خطأً أو تم إلغاؤها قبل التنفيذ.

دلالات الرسوم والحجز

وفقاً لـ دليل الفوترة والتسعير الخاص بـ TokenLab، تتبع فوترة مهام الوسائط غير المتزامنة نموذج حجز وتسوية من مرحلتين:

1. التفويض المسبق / الحجز: عند قبول مهمة فيديو غير متزامنة، قد تحتجز TokenLab أو تحجز مبلغاً تقديرياً بناءً على النموذج والمعلمات المحددة.
2. التسوية: لا تتم تسوية الرسوم النهائية إلا عندما تصل المهمة إلى completed. تُرفق المهام المكتملة معرّف billing_transaction_id يمثل قيد دفتر الأستاذ النهائي.
3. الإلغاء والفشل: المهام التي تنتهي بحالة failed—بما في ذلك تلك التي تم إلغاؤها أثناء وجودها في قائمة الانتظار—لا تُفرض عليها رسوم. يتم تحرير أي حجز غير مستخدم أو حجز مؤقت وإعادته إلى رصيد مساحة العمل الخاصة بك.

نظراً لأن المهمة الملغاة في قائمة الانتظار لا تكمل التوليد أبداً، فإنها لا تُنتج تسوية فوترة مكتملة.

إلغاء مهمة في قائمة الانتظار عبر واجهة برمجة التطبيقات (API)

لإلغاء مهمة، أرسل طلب DELETE إلى /v1/tasks/{id} مع معرّف المهمة الذي تم إرجاعه أثناء الإنشاء. للحصول على تفاصيل المخطط الكاملة، راجع مرجع واجهة برمجة التطبيقات لإلغاء المهام.

مثال على الطلب

curl -X DELETE "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"

استجابة النجاح (HTTP 200)

عندما يتم إلغاء المهمة بنجاح قبل بدء التنفيذ، تستجيب واجهة برمجة التطبيقات بـ HTTP 200. تنتقل حالة المهمة مباشرةً إلى failed، وتُميّز بـ cancelled: true:

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "failed",
  "cancelled": true,
  "cancellation_status": "cancelled",
  "error": "Task cancelled before execution"
}

رموز الخطأ والتعامل مع الرفض

لا تفترض أن استدعاء DELETE ينجح دائماً. يجب أن يتعامل تطبيقك مع حالات أخطاء HTTP محددة:

حالة HTTP	رمز الخطأ	المعنى	الإجراء الموصى به
400	unsupported_task_cancel	النموذج أو نوع المهمة لا يدعم الإلغاء.	اترك المهمة تكتمل بشكل طبيعي أو راجع دعم النموذج.
403	task_not_owned	مفتاح واجهة برمجة التطبيقات لا يملك المهمة.	تحقق من بيانات اعتماد مساحة العمل ونطاق مفتاح واجهة برمجة التطبيقات.
404	async_task_not_found	معرّف المهمة غير موجود أو انتهت صلاحيته.	تأكد من معرّف المهمة المخزن في قاعدة بيانات قائمة الانتظار المحلية لديك.
409	task_not_cancellable	بدأت المهمة بالفعل في processing أو أنها في حالة نهائية (completed/failed).	تقبل أن التوليد قيد التنفيذ بالفعل؛ لا تُعد محاولة استدعاء الحذف في حلقة تكرارية.

استقصاء المهام الملغاة

عند استقصاء مهمة عبر GET /v1/tasks/{id} أو poll_url المرتجع (كما هو موضح في دليل الوظائف غير المتزامنة والاستقصاء)، ضع السلوكيات التالية في الاعتبار:

1. HTTP 200 في المهام النهائية: تُرجع قراءة حالة مهمة فاشلة أو ملغاة الرمز HTTP 200. افحص حقلي status و cancelled في نص JSON بدلاً من الاعتماد على رموز استجابة HTTP.
2. تحديد الحالة: تعرض المهمة الملغاة "status": "failed"، و "cancelled": true، و "cancellation_status": "cancelled".
3. غياب معرّفات التسوية: لن تحتوي المهام الملغاة على billing_transaction_id نظراً لعدم حدوث أي تسوية للرسوم.

import time
import requests

def cancel_and_verify(task_id: str, api_key: str):
    url = f"https://api.tokenlab.sh/v1/tasks/{task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    # Attempt cancellation
    cancel_res = requests.delete(url, headers=headers)
    if cancel_res.status_code == 200:
        data = cancel_res.json()
        if data.get("cancelled"):
            print(f"Task {task_id} successfully cancelled.")
            return True
    elif cancel_res.status_code == 409:
        print(f"Task {task_id} already in progress or terminal; cannot cancel.")
    else:
        print(f"Cancellation rejected with HTTP {cancel_res.status_code}: {cancel_res.text}")

    # Poll task to determine terminal state
    poll_res = requests.get(url, headers=headers)
    if poll_res.ok:
        status_data = poll_res.json()
        print(f"Current status: {status_data.get('status')}, cancelled: {status_data.get('cancelled', False)}")
    return False

قائمة التحقق لتكامل قائمة الانتظار في بيئة الإنتاج

عند دمج مسارات عمل فيديو Seedance في بنيات المشغلات (workers)، اتبع أفضل الممارسات التالية:

• حفظ المعرّفات فوراً: قم بتخزين كل من id (أو task_id) و poll_url من استجابة POST /v1/videos/generations قبل إرسال المهام التابعة.
• إزالة التكرار عند الإرسال: امنع توليد المهام غير المقصود عن طريق إلغاء تكرار النقرات المزدوجة من جانب العميل وإعادة المحاولات على الشبكة قبل إنشاء المهام.
• التعامل مع 409 كخطأ غير حرج: إذا أرجع طلب الإلغاء 409 task_not_cancellable، فتعامل معه على أنه إشارة إلى أن المعالجة قد بدأت. اعتمد كحل بديل انتظار النتيجة والتخلص من المخرجات إذا لم تعد مطلوبة.
• تحليل علامة الإلغاء: في حلقة الاستقصاء، تحقق من كل من status == "failed" و cancelled is True للتمييز بين عمليات الإلغاء التي بدأها المستخدم وأخطاء البنية التحتية.
• تسوية الفوترة باستخدام معرّفات المعاملات: احفظ billing_transaction_id فقط عندما يكون موجوداً في المهام المكتملة. لا تتوقع وجود معرّفات معاملات في المهام الملغاة أو الفاشلة.

للاطلاع على أنماط تكامل إضافية، راجع دليل توليد الفيديو ومرجع واجهة برمجة التطبيقات للحصول على حالة الفيديو.