المهام غير المتزامنة
الحصول على حالة المهمة
استرجاع حالة ونتيجة أي مهمة غير متزامنة (async): الصور، الفيديو، الموسيقى، 3D، العوالم (Worlds)، ونسخ الصوت غير المتزامن
نظرة عامة
استخدم GET /v1/tasks/{id} للتحقق من أي مهمة غير متزامنة. تخدم هذه النقطة مهام الصور، الفيديو، الموسيقى، 3D، العوالم، ونسخ الصوت غير المتزامن. قم بتمرير id أو task_id من استجابة الإنشاء.
حقول نتائج العوالم، مثل world_id و world_marble_url، موثقة في الحصول على حالة العالم. بالنسبة لمهمة العالم، تكون قيمة X-Task-Type هي 3d.
بالنسبة لمعظم المهام، يكون poll_url في استجابة الإنشاء هو نفس هذا المسار. تُرجع استجابة إنشاء العوالم poll_url تحت /v1/worlds/generations/{id}؛ قم بعمل استطلاع (poll) لـ /v1/tasks/{id} باستخدام id المهمة للعوالم أيضاً.
مسارات الحالة الخاصة بكل نمط (modality)، مثل /v1/images/{id} و /v1/videos/generations/{id} و /v1/music/generations/{id} و /v1/3d/generations/{id}، هي نقاط نهاية للتوافق. تظل مدعومة لعمليات التكامل الحالية.
تُرجع قراءة الحالة HTTP 200 للمهمة التي فشلت. اقرأ status، وليس كود HTTP، لمعرفة النتيجة. تعتمد حقول النتيجة على نوع المهمة؛ راجع الحصول على حالة الصورة و الحصول على حالة الفيديو و الحصول على حالة الموسيقى و الحصول على حالة 3D. روابط النتائج هي روابط TokenLab لنتائج الوسائط التي تظل صالحة لمدة 30 يوماً؛ راجع الاحتفاظ بالبيانات.
معاملات المسار (Path Parameters)
معرف id أو task_id الذي تم إرجاعه بواسطة طلب الإنشاء.
الاستجابة
يتم إرجاع الحقول التي تصف النتائج، والأخطاء، والطوابع الزمنية، والنموذج عند توفرها للمهمة.
المعرف الأساسي للمهمة غير المتزامنة.
اسم مستعار لمعرف المهمة غير المتزامنة.
رابط الحالة لهذه المهمة. قم بعمل استطلاع GET /v1/tasks/{id} باستخدام id.
معرف معاملة الفوترة، عند تسجيل واحدة للمهمة. يحمل رأس X-Billing-Transaction-ID نفس القيمة. إنه معرف فوترة، وليس معرف مهمة.
حالة المهمة: pending (قيد الانتظار)، processing (قيد المعالجة)، completed (مكتملة)، failed (فاشلة)، أو timeout (انتهت المهلة). توقف عن الاستطلاع عند الوصول إلى completed أو failed أو timeout. يتم تمثيل المهام الملغاة كـ failed مع cancelled: true.
تكون true عندما يتم إلغاء مهمة غير متزامنة في قائمة الانتظار قبل التنفيذ.
علامة الإلغاء. تظهر كـ cancelled عند نجاح الإلغاء.
بالنسبة لمهام الصور المكتملة، يتم إرجاع نتائج الصور المولدة هنا. تُرجع مهام الصور روابط في data[].url.
قيمة تقدم اختيارية. يتم إرجاعها فقط عند توفر قيمة تقدم حقيقية؛ استخدم status لتحديد الاكتمال.
رابط أصل النتيجة عند اكتمال المهمة وإنتاج فيديو.
حمولة فيديو واحدة مع url و duration و width و height عند توفرها.
حمولة فيديوهات متعددة عند توفر أكثر من مخرج واحد.
سبب فشل المهمة: سلسلة نصية، أو كائن يحتوي على message وعند معرفته، type و code و param و retryable.
تفاصيل الفشل عند فشل المهمة: status و message و type و code و retryable و param عند وجود خطأ في حقل الطلب.
حالة حفظ روابط النتائج: days و items[] مع url و kind و status و expires_at. قد تكون غائبة؛ الروابط لا تزال تعمل.
الطابع الزمني للإنشاء عند توفره.
الطابع الزمني لآخر تحديث عند توفره.
النموذج المستخدم من قبل المهمة عند توفره.
رؤوس الاستجابة (Response Headers)
تتضمن استجابات الحالة الناجحة هذه الرؤوس:
| الرأس | الوصف |
|---|---|
X-Task-ID | معرف المهمة العام |
X-Task-Type | عائلة المهمة، مثل image أو video أو music أو 3d أو audio |
Cache-Control | no-store. لا تقم بتخزين استجابات الحالة مؤقتاً |
X-Billing-Transaction-ID | معرف معاملة الفوترة، عند تسجيل واحدة |
X-Task-Cost | تكلفة المهمة المسواة، عند تسوية المهمة |
سلوك الخطأ
| HTTP | الكود | المعنى |
|---|---|---|
400 | missing_task_id, invalid_task_id | معرف المهمة مفقود أو ليس معرف مهمة صالحاً |
403 | task_not_owned | المهمة لا تنتمي إلى مساحة العمل الخاصة بمفتاح API هذا. توقف عن استطلاعها |
404 | async_task_not_found | انتهت صلاحية المهمة أو أنها غير متاحة |
503 | async_task_owner_unavailable | لا يمكن قراءة المهمة في الوقت الحالي. حاول مجدداً |
{
"error": {
"message": "Task not found or no longer available.",
"type": "invalid_request_error",
"code": "async_task_not_found"
}
}الطلب
curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
-H "Authorization: Bearer sk-your-api-key"{ "id": "string", "status": "pending", "progress": 0, "created": 0, "updated": 0, "model": "string", "video": { "url": "string", "duration": 0, "width": 0, "height": 0 }, "error": "string", "error_details": { "projection_version": 0, "status": 400, "message": "string", "type": "string", "code": "string", "param": "string", "retryable": true, "upstream": { "source": "string", "code": "string", "message": "string", "param": "string" } }, "task_id": "string", "poll_url": "string", "cancelled": true, "cancellation_status": "cancelled", "billing_transaction_id": "string", "video_url": "string", "last_frame_url": "string", "videos": [ {} ], "data": [ {} ], "audio_url": "string", "title": "string", "lyrics": "string", "model_url": "string", "glb_url": "string", "fbx_url": "string", "media_retention": { "days": 0, "items": [ { "url": "http://example.com", "kind": "image", "content_type": "string", "status": "saving", "expires_at": "2019-08-24T14:15:22Z" } ] }}التفويض
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