المهام غير المتزامنة

الحصول على حالة المهمة

استرجاع حالة ونتيجة أي مهمة غير متزامنة (async): الصور، الفيديو، الموسيقى، 3D، العوالم (Worlds)، ونسخ الصوت غير المتزامن

GET
/v1/tasks/{id}

نظرة عامة

استخدم 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)

idstringpathمطلوب

معرف id أو task_id الذي تم إرجاعه بواسطة طلب الإنشاء.

الاستجابة

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

idstring

المعرف الأساسي للمهمة غير المتزامنة.

task_idstring

اسم مستعار لمعرف المهمة غير المتزامنة.

poll_urlstring

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

billing_transaction_idstring

معرف معاملة الفوترة، عند تسجيل واحدة للمهمة. يحمل رأس X-Billing-Transaction-ID نفس القيمة. إنه معرف فوترة، وليس معرف مهمة.

statusstring

حالة المهمة: pending (قيد الانتظار)، processing (قيد المعالجة)، completed (مكتملة)، failed (فاشلة)، أو timeout (انتهت المهلة). توقف عن الاستطلاع عند الوصول إلى completed أو failed أو timeout. يتم تمثيل المهام الملغاة كـ failed مع cancelled: true.

cancelledboolean

تكون true عندما يتم إلغاء مهمة غير متزامنة في قائمة الانتظار قبل التنفيذ.

cancellation_statusstring

علامة الإلغاء. تظهر كـ cancelled عند نجاح الإلغاء.

dataarray

بالنسبة لمهام الصور المكتملة، يتم إرجاع نتائج الصور المولدة هنا. تُرجع مهام الصور روابط في data[].url.

progressnumber

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

video_urlstring

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

videoobject

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

videosarray

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

errorstring | object

سبب فشل المهمة: سلسلة نصية، أو كائن يحتوي على message وعند معرفته، type و code و param و retryable.

error_detailsobject

تفاصيل الفشل عند فشل المهمة: status و message و type و code و retryable و param عند وجود خطأ في حقل الطلب.

media_retentionobject

حالة حفظ روابط النتائج: days و items[] مع url و kind و status و expires_at. قد تكون غائبة؛ الروابط لا تزال تعمل.

createdinteger

الطابع الزمني للإنشاء عند توفره.

updatedinteger

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

modelstring

النموذج المستخدم من قبل المهمة عند توفره.

رؤوس الاستجابة (Response Headers)

تتضمن استجابات الحالة الناجحة هذه الرؤوس:

الرأسالوصف
X-Task-IDمعرف المهمة العام
X-Task-Typeعائلة المهمة، مثل image أو video أو music أو 3d أو audio
Cache-Controlno-store. لا تقم بتخزين استجابات الحالة مؤقتاً
X-Billing-Transaction-IDمعرف معاملة الفوترة، عند تسجيل واحدة
X-Task-Costتكلفة المهمة المسواة، عند تسوية المهمة

سلوك الخطأ

HTTPالكودالمعنى
400missing_task_id, invalid_task_idمعرف المهمة مفقود أو ليس معرف مهمة صالحاً
403task_not_ownedالمهمة لا تنتمي إلى مساحة العمل الخاصة بمفتاح API هذا. توقف عن استطلاعها
404async_task_not_foundانتهت صلاحية المهمة أو أنها غير متاحة
503async_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
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