الفيديو والمواد

الحصول على حالة الفيديو

الحصول على حالة ونتيجة مهمة الفيديو

GET
/v1/tasks/{id}

GET /v1/videos/generations/{id} هو نقطة نهاية للتوافق. يظل مدعوماً لعمليات التكامل الحالية ويعيد النتيجة بنفس تنسيق GET /v1/tasks/{id}. عمليات التكامل الجديدة تستخدم الاستطلاع (polling) عبر GET /v1/tasks/{id}؛ راجع الحصول على حالة المهمة.

معاملات المسار (Path Parameters)

idstringpathمطلوب

معرف المهمة (task ID) الذي تم إرجاعه بواسطة طلب إنشاء الفيديو. id و task_id يشيران إلى نفس المهمة.

إرجاع حالة المهمة يعطي HTTP 200 حتى في حال فشل المهمة؛ تحقق من status. المهمة منتهية الصلاحية أو غير المتاحة تعيد 404 async_task_not_found. المهمة التي لا تنتمي إلى مساحة العمل الخاصة بك تعيد 403 task_not_owned. الخطأ 503 async_task_owner_unavailable هو خطأ مؤقت: أعد محاولة الطلب.

الاستجابة (Response)

يتم إرجاع الحقول التي تصف النتائج، والأخطاء، والطوابع الزمنية، والنموذج عند توفرها للمهمة.

idstring

معرف المهمة.

task_idstring

نفس معرف المهمة مثل id.

poll_urlstring

رابط الحالة لهذه المهمة. قم بعمل استطلاع (poll) لـ GET /v1/tasks/{id} باستخدام id.

billing_transaction_idstring

معرف معاملة الفوترة بعد التسوية. وهو منفصل عن معرف المهمة.

statusstring

حالة المهمة: pending (قيد الانتظار)، processing (قيد المعالجة)، completed (مكتملة)، failed (فاشلة).

progressinteger

تقدم اختياري من 0 إلى 100. يتم إرجاعه فقط عند توفر قيمة تقدم حقيقية؛ استخدم status لتحديد الاكتمال.

video_urlstring

رابط الفيديو الذي تم إنشاؤه (عند اكتماله). هو رابط TokenLab لنتائج الوسائط ويبقى صالحاً لمدة 30 يوماً؛ راجع تنزيل النتيجة. المهام الفاشلة وغير المكتملة لا تعيد رابط فيديو.

last_frame_urlstring

رابط آخر إطار تم إنشاؤه، عند طلبه باستخدام return_last_frame وكان النموذج يدعم ذلك.

videoobject

نتيجة فيديو واحدة مع url و duration و width و height عند توفرها.

videosarray

نتائج فيديو متعددة عندما تعيد المهمة أكثر من مخرج واحد.

errorstring | object

سبب فشل المهمة (فقط عندما تكون status هي failed): سلسلة نصية، أو كائن يحتوي على message وعند معرفته، type و code و param و retryable. يمكن أن تحمل المهمة الفاشلة أيضاً error_details؛ راجع الوظائف غير المتزامنة والاستطلاع.

media_retentionobject

حالة حفظ الفيديو: days و items، كل منها يحتوي على url و kind و status و expires_at. قد يكون غائباً عندما لا تكون الحالة معروفة في الوقت المناسب؛ الرابط لا يزال يعمل.

createdinteger

الطابع الزمني للإنشاء.

updatedinteger

الطابع الزمني لآخر تحديث.

modelstring

النموذج المستخدم للمهمة.

الطلب

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

الاستجابة

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "veo3.1",
  "created": 1706000000,
  "updated": 1706000000
}

تنزيل النتيجة

يبدو video_url كالتالي: https://api.tokenlab.sh/v1/media-results/{id}.mp4?token=…. الرمز (token) الموجود في الرابط هو بيانات الاعتماد، لذا لا حاجة لترويسة Authorization. شارك الرابط فقط مع الأشخاص الذين يمكنهم مشاهدة الفيديو. الرابط يعيد التوجيه إلى الملف، لذا اتبع عمليات إعادة التوجيه عند التنزيل (curl -L).

  • يظل الرابط صالحاً لمدة 30 يوماً من تاريخ تسجيل النتيجة لأول مرة. قم بتنزيل الملف إذا كنت بحاجة إليه لفترة أطول؛ راجع الاحتفاظ بالبيانات.
  • 404 media_not_found: الرمز أو امتداد الملف لا يتطابق مع النتيجة. استخدم الرابط الدقيق الذي تلقيته.
  • 410 media_expired: انتهت فترة الـ 30 يوماً.
  • 502 أو 503 media_unavailable: النتيجة لا تزال قيد التسجيل، أو أن TokenLab مشغول. أعد المحاولة بعد تأخير Retry-After.
  • أضف metadata=true إلى الرابط لقراءة حالة الحفظ بدلاً من الملف.

يتم تسليم بعض النتائج كـ https://api.tokenlab.sh/v1/videos/generations/{id}/content. يحتاج هذا الرابط إلى نفس ترويسة Authorization: Bearer التي تستخدمها للاستطلاع، ولا يمكن فتحه إلا بواسطة مساحة العمل التي تمتلك المهمة.

الفاصل الزمني للتحقق

  • تحقق كل 5–10 ثوانٍ.
  • قم بزيادة الفاصل الزمني للمهام طويلة الأمد.
  • حدد أقصى وقت انتظار لتطبيقك.
  • توقف عندما تكون الحالة failed واعرض الـ error الذي تم إرجاعه.
import requests
import time

def wait_for_video(task_id, max_wait=600, interval=5):
    """Wait for video with timeout."""
    start = time.time()

    while time.time() - start < max_wait:
        response = requests.get(
            f"https://api.tokenlab.sh/v1/tasks/{task_id}",
            headers={"Authorization": "Bearer sk-your-api-key"}
        )
        response.raise_for_status()
        data = response.json()

        if data["status"] == "completed":
            return data["video_url"]
        elif data["status"] == "failed":
            raise Exception(data.get("error", "Video generation failed"))

        time.sleep(interval)

    raise TimeoutError("Video generation timed out")

التفويض

BearerAuth
AuthorizationBearer <token>

مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.

الموضع: header

معاملات المسار

id*string

معرف المهمة غير المتزامنة الذي يتم إرجاعه بواسطة id / task_id، أو المضمن في poll_url

الاستجابة

application/json

application/json

application/json

application/json

application/json

application/json

application/json