معلمات المسار
معرّف المهمة المُعاد من طلب إنشاء الفيديو. اعتبر id و task_id نفس الهوية غير المتزامنة.
إذا أعادت استجابة الإنشاء قيمة poll_url، فاستدعِ ذلك العنوان بالضبط. عندما يشير إلى /v1/tasks/{id}، اعتبره نقطة النهاية الأساسية الثابتة لحالة المهمة. إذا لم تعد المهمة موجودة أو لم يعد بالإمكان حلها عبر عقد المهمة غير المتزامنة العام، فتعيد TokenLab القيمة async_task_not_found مع الرسالة Task not found or no longer available.
الاستجابة
المعرّف الرسمي للمهمة غير المتزامنة.
الاسم المستعار لمعرّف المهمة غير المتزامنة.
عنوان URL المفضل للاستعلام المتكرر عندما توفر استجابة الإنشاء واحدًا.
معرّف معاملة الفوترة في TokenLab عندما تكون التسوية قد اكتملت بالفعل. هذا هو معرّف المعاملة المستخدم في لوحة التحكم / المطابقة، وهو منفصل عن id / task_id غير المتزامن.
حالة المهمة: pending, processing, completed, failed.
قيمة تقدم اختيارية. لا تُعاد إلا عند توفر قيمة تقدم حقيقية؛ استخدم status لتحديد اكتمال المهمة.
عنوان URL للفيديو الناتج (عند الاكتمال).
حمولة فيديو مفردة تحتوي على الحقول url, duration, width, و height عندما تتوفر.
حمولات فيديو متعددة عندما تعيد مهمة التوليد أكثر من مخرج واحد.
cURL
Python
JavaScript
Go
PHP
curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
-H "Authorization: Bearer sk-your-api-key"
import requests
import time
task_id = "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
while True :
response = requests.get(
f "https://api.tokenlab.sh/v1/tasks/ { task_id } " ,
headers = { "Authorization" : "Bearer sk-your-api-key" }
)
data = response.json()
print ( f "Status: { data[ 'status' ] } " )
if data[ "status" ] == "completed" :
print ( f "Video URL: { data[ 'video_url' ] } " )
break
elif data[ "status" ] == "failed" :
print ( f "Error: { data[ 'error' ] } " )
break
time.sleep( 5 ) # Poll every 5 seconds
const taskId = 'ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' ;
async function pollForVideo () {
while ( true ) {
const response = await fetch (
`https://api.tokenlab.sh/v1/tasks/ ${ taskId } ` ,
{ headers: { 'Authorization' : 'Bearer sk-your-api-key' } }
);
const data = await response . json ();
console . log ( `Status: ${ data . status } ` );
if ( data . status === 'completed' ) {
console . log ( `Video URL: ${ data . video_url } ` );
return data . video_url ;
} else if ( data . status === 'failed' ) {
throw new Error ( data . error );
}
await new Promise ( r => setTimeout ( r , 5000 ));
}
}
package main
import (
" encoding/json "
" fmt "
" net/http "
" time "
)
func main () {
taskID := "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
for {
req , _ := http . NewRequest ( "GET" ,
fmt . Sprintf ( "https://api.tokenlab.sh/v1/tasks/ %s " , taskID ), nil )
req . Header . Set ( "Authorization" , "Bearer sk-your-api-key" )
client := & http . Client {}
resp , _ := client . Do ( req )
var result map [ string ] interface {}
json . NewDecoder ( resp . Body ). Decode ( & result )
resp . Body . Close ()
fmt . Printf ( "Status: %s \n " , result [ "status" ])
if result [ "status" ] == "completed" {
fmt . Printf ( "Video URL: %s \n " , result [ "video_url" ])
break
} else if result [ "status" ] == "failed" {
fmt . Printf ( "Error: %s \n " , result [ "error" ])
break
}
time . Sleep ( 5 * time . Second )
}
}
<? php
$taskId = 'ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' ;
while ( true ) {
$ch = curl_init ( "https://api.tokenlab.sh/v1/tasks/{ $taskId }" );
curl_setopt_array ( $ch , [
CURLOPT_RETURNTRANSFER => true ,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer sk-your-api-key'
]
]);
$response = curl_exec ( $ch );
curl_close ( $ch );
$data = json_decode ( $response , true );
echo "Status: { $data ['status']} \n " ;
if ( $data [ 'status' ] === 'completed' ) {
echo "Video URL: { $data ['video_url']} \n " ;
break ;
} elseif ( $data [ 'status' ] === 'failed' ) {
echo "Error: { $data ['error']} \n " ;
break ;
}
sleep ( 5 );
}
Response (pending)
Response (processing)
Response (completed)
Response (failed)
{
"id" : "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ,
"task_id" : "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ,
"poll_url" : "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ,
"status" : "pending" ,
"model" : "veo3.1" ,
"created" : 1706000000 ,
"updated" : 1706000000
}
{
"id" : "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ,
"task_id" : "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ,
"poll_url" : "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ,
"status" : "processing" ,
"model" : "veo3.1" ,
"created" : 1706000000 ,
"updated" : 1706000030
}
{
"id" : "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ,
"task_id" : "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ,
"poll_url" : "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ,
"billing_transaction_id" : "cmo164zyc0s48jpgegi80vqv4" ,
"status" : "completed" ,
"video_url" : "https://assets.tokenlab.sh/videos/abc123.mp4" ,
"model" : "veo3.1" ,
"created" : 1706000000 ,
"updated" : 1706000060
}
{
"id" : "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ,
"task_id" : "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ,
"poll_url" : "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ,
"status" : "failed" ,
"error" : "Content policy violation" ,
"model" : "veo3.1" ,
"created" : 1706000000 ,
"updated" : 1706000060
}
أفضل ممارسات الاستطلاع
استعلم كل 5-10 ثوانٍ
طبّق آلية تراجع أُسِّي (exponential backoff) للمهام الطويلة
حدد مهلة قصوى (مثلاً، 10 دقائق)
تعامل مع الحالة failed بشكل ملائم
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" }
)
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" )