الفيديو والمواد
الحصول على حالة الفيديو
الحصول على حالة ونتيجة مهمة الفيديو
GET /v1/videos/generations/{id} هو نقطة نهاية للتوافق. يظل مدعوماً لعمليات التكامل الحالية ويعيد النتيجة بنفس تنسيق GET /v1/tasks/{id}. عمليات التكامل الجديدة تستخدم الاستطلاع (polling) عبر GET /v1/tasks/{id}؛ راجع الحصول على حالة المهمة.
معاملات المسار (Path Parameters)
معرف المهمة (task ID) الذي تم إرجاعه بواسطة طلب إنشاء الفيديو. id و task_id يشيران إلى نفس المهمة.
إرجاع حالة المهمة يعطي HTTP 200 حتى في حال فشل المهمة؛ تحقق من status. المهمة منتهية الصلاحية أو غير المتاحة تعيد 404 async_task_not_found. المهمة التي لا تنتمي إلى مساحة العمل الخاصة بك تعيد 403 task_not_owned. الخطأ 503 async_task_owner_unavailable هو خطأ مؤقت: أعد محاولة الطلب.
الاستجابة (Response)
يتم إرجاع الحقول التي تصف النتائج، والأخطاء، والطوابع الزمنية، والنموذج عند توفرها للمهمة.
معرف المهمة.
نفس معرف المهمة مثل id.
رابط الحالة لهذه المهمة. قم بعمل استطلاع (poll) لـ GET /v1/tasks/{id} باستخدام id.
معرف معاملة الفوترة بعد التسوية. وهو منفصل عن معرف المهمة.
حالة المهمة: pending (قيد الانتظار)، processing (قيد المعالجة)، completed (مكتملة)، failed (فاشلة).
تقدم اختياري من 0 إلى 100. يتم إرجاعه فقط عند توفر قيمة تقدم حقيقية؛ استخدم status لتحديد الاكتمال.
رابط الفيديو الذي تم إنشاؤه (عند اكتماله). هو رابط TokenLab لنتائج الوسائط ويبقى صالحاً لمدة 30 يوماً؛ راجع تنزيل النتيجة. المهام الفاشلة وغير المكتملة لا تعيد رابط فيديو.
رابط آخر إطار تم إنشاؤه، عند طلبه باستخدام return_last_frame وكان النموذج يدعم ذلك.
نتيجة فيديو واحدة مع url و duration و width و height عند توفرها.
نتائج فيديو متعددة عندما تعيد المهمة أكثر من مخرج واحد.
سبب فشل المهمة (فقط عندما تكون status هي failed): سلسلة نصية، أو كائن يحتوي على message وعند معرفته، type و code و param و retryable. يمكن أن تحمل المهمة الفاشلة أيضاً error_details؛ راجع الوظائف غير المتزامنة والاستطلاع.
حالة حفظ الفيديو: days و items، كل منها يحتوي على url و kind و status و expires_at. قد يكون غائباً عندما لا تكون الحالة معروفة في الوقت المناسب؛ الرابط لا يزال يعمل.
الطابع الزمني للإنشاء.
الطابع الزمني لآخر تحديث.
النموذج المستخدم للمهمة.
الطلب
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 مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.
الموضع: header
معاملات المسار
معرف المهمة غير المتزامنة الذي يتم إرجاعه بواسطة id / task_id، أو المضمن في poll_url
الاستجابة
application/json
application/json
application/json
application/json
application/json
application/json
application/json