非同步任務
取得任務狀態
檢索任何非同步任務的狀態與結果:圖像、影片、音樂、3D、Worlds 以及非同步音訊轉錄
概覽
使用 GET /v1/tasks/{id} 來檢查任何非同步任務。它適用於圖像、影片、音樂、3D、Worlds 以及非同步音訊轉錄任務。請傳入建立回應中的 id 或 task_id。
World 結果欄位(例如 world_id 和 world_marble_url)記錄在 取得 World 狀態 中。對於 World 任務,X-Task-Type 為 3d。
對於大多數任務,建立回應中的 poll_url 即為此路徑。Worlds 的建立回應會在 /v1/worlds/generations/{id} 下回傳一個 poll_url;對於 Worlds,同樣請輪詢 /v1/tasks/{id} 並使用該任務的 id。
各模態的狀態路徑(例如 /v1/images/{id}、/v1/videos/generations/{id}、/v1/music/generations/{id} 和 /v1/3d/generations/{id})為相容性端點。這些端點對於現有的整合仍維持支援。
當任務失敗時,狀態讀取會回傳 HTTP 200。請讀取 status 而非 HTTP 代碼來查看結果。結果欄位取決於任務類型;請參閱 取得圖像狀態、取得影片狀態、取得音樂狀態 以及 取得 3D 狀態。結果連結為 TokenLab 媒體結果 URL,有效期為 30 天;請參閱 資料保留。
路徑參數
建立請求所回傳的 id 或 task_id。
回應
當任務可用時,會回傳描述結果、錯誤、時間戳記與模型的欄位。
標準非同步任務識別碼。
非同步任務識別碼別名。
此任務的狀態 URL。請使用 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 中回傳 URL。
選用的進度值。僅在有實際進度值可用時回傳;請使用 status 來判斷是否完成。
任務完成並產生影片時的結果資產 URL。
單一影片負載,包含可用的 url、duration、width 和 height。
當有多個輸出可用時的多個影片負載。
任務失敗的原因:字串,或包含 message 的物件,若已知則包含 type、code、param 和 retryable。
任務失敗時的詳細資訊:status、message、type、code、retryable,以及當請求欄位出錯時的 param。
結果連結的儲存狀態:包含 days 以及 items[](包含 url、kind、status 和 expires_at)。此欄位可能不存在;連結仍然有效。
建立時間戳記(若可用)。
最後更新時間戳記(若可用)。
任務所使用的模型(若可用)。
回應標頭
成功的狀態回應包含以下標頭:
| 標頭 | 說明 |
|---|---|
X-Task-ID | 公開任務 ID |
X-Task-Type | 任務系列,例如 image、video、music、3d 或 audio |
Cache-Control | no-store。請勿快取狀態回應 |
X-Billing-Transaction-ID | 帳單交易 ID(若已記錄) |
X-Task-Cost | 已結算的任務成本(若任務已結算) |
錯誤行為
| HTTP | 代碼 | 含義 |
|---|---|---|
400 | missing_task_id, invalid_task_id | 缺少任務 ID 或任務 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 Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。
位置: header
路徑參數
由 id / task_id 回傳,或嵌入於 poll_url 中的非同步任務 ID
回應
application/json
application/json
application/json
application/json
application/json
application/json
application/json