視頻與素材
取得影片狀態
取得影片產生任務的狀態與結果
路徑參數
idstringpath必填
從建立影片請求回傳的任務 ID。將 id 與 task_id 視為相同的非同步識別碼。
如果 create 回應回傳 poll_url,請呼叫該 URL。當它指向 /v1/tasks/{id} 時,視為固定的標準狀態端點。
已過期或不可用的公開任務可能回傳 404 async_task_not_found。無法確認目前 API 金鑰對任務的歸屬權限時,回傳 403 task_not_owned。
回應
結果、錯誤、時間戳記與模型欄位僅在任務提供時回傳。
idstring
正規的非同步任務識別符。
task_idstring
非同步任務識別符的別名。
poll_urlstring
當建立回應提供時,建議用來輪詢的 URL。
billing_transaction_idstring
當結算已完成時返回 TokenLab 帳單交易 ID。它對應 dashboard / 對帳使用的交易識別,與非同步 id / task_id 不同。
statusstring
任務狀態:pending、processing、completed、failed。
progressnumber
可選進度值。僅在任務提供真實進度時返回;請使用 status 判斷任務是否完成。
video_urlstring
產生影片的 URL(完成時)。
videoobject
單一影片資料,當可用時包含 url、duration、width 與 height。
videosarray
當生成任務回傳多個輸出時的多重影片資料。
errorstring | object
錯誤訊息(若失敗)。
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
}輪詢最佳做法
- 每 5 到 10 秒輪詢一次
- 對於較長的任務實作指數退避
- 設定最大逾時(例如:10 分鐘)
- 優雅地處理
failed狀態
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 Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。
位置: header
路徑參數
id*string
由 id / task_id 回傳,或嵌入於 poll_url 中的非同步任務 ID
回應
application/json
application/json
application/json
application/json