核心指南
非同步任務與輪詢
建立媒體任務並等待完成結果
許多媒體 API 端點會回傳一個任務,而非直接回傳完成的檔案。請儲存回傳的任務 ID,並輪詢 GET /v1/tasks/{id} 直到狀態變為 completed(已完成)或 failed(失敗)。此單一端點適用於圖像、影片、音樂、3D、Worlds 以及非同步音訊轉錄任務。
非同步終端任務快照的生命週期與 30 天的請求/回應擷取視窗是分開的。產生的圖像、影片、音訊、3D 和 Worlds 檔案 URL 為 TokenLab 媒體結果 URL,有效期為 30 天。已完成任務的狀態讀取約可維持 7 天,因此請在任務完成後儘快儲存結果。回應中的 media_retention 欄位會報告每個項目的儲存狀態與 expires_at;當儲存狀態未及時得知時,這些欄位可能會缺失,但 URL 仍然有效。失敗與進行中的任務會回傳空的媒體 URL 欄位。請參閱 資料保留。
需儲存的欄位
建立回應可能包含:
| 欄位 | 含義 | 處理方式 |
|---|---|---|
id | TokenLab 任務 ID | 將其與您自己的工作記錄一起儲存 |
task_id | 同一任務 ID 的別名 | 將其視為與 id 等同 |
status | 當前任務狀態 | 持續檢查直到完成或失敗 |
poll_url | 任務的狀態 URL | 儲存它;使用任務 ID 輪詢 /v1/tasks/{id} |
model | 任務使用的模型 | 將其與任務記錄一起儲存 |
單一狀態端點
使用建立回應中的 id 或 task_id 來輪詢 GET /v1/tasks/{id}。它適用於所有任務類型。對於大多數任務,poll_url 即為此路徑。Worlds 的建立回應會在 /v1/worlds/generations/{id} 下回傳 poll_url;但對於 Worlds,同樣請使用任務 id 來輪詢 /v1/tasks/{id}。
針對特定類型的狀態路徑(例如 /v1/videos/generations/{id})仍支援現有的整合。新的整合應使用 /v1/tasks/{id}。
儲存任務並檢查狀態
在建立請求成功後,請立即儲存 id 或 task_id。同時儲存 poll_url、模型、端點以及您自己的使用者或工作 ID。對於長時間的媒體工作,每 5–10 秒檢查一次通常已足夠。
當狀態變為 completed 或 failed 時停止輪詢。已完成的任務包含媒體結果;失敗的任務包含您可以顯示或記錄的錯誤資訊。重試失敗的生成會建立一個新任務,並可能產生新的費用。
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"model": "veo3.1"
}輪詢範例
curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
-H "Authorization: Bearer sk-your-api-key"狀態包括 pending(待處理)、processing(處理中)、completed(已完成)與 failed(失敗)。已取消的任務會使用 failed 狀態,並同時包含 cancelled: true 與 cancellation_status: "cancelled"。
即使任務失敗,成功的狀態讀取仍會回傳 HTTP 200。請使用任務的 status 來判斷生成是否成功。error 欄位會保留其字串或物件格式。失敗的任務可能還包含 error_details,其中包含 status(業務錯誤狀態)、type、code、message、param 與 retryable。例如,error_details.status: 400 且 param: "size" 表示請求需要修正;這並不代表狀態請求本身失敗。當沒有特定的欄位資訊時,會省略 param。當 error_details.projection_version 為 2 時,message 是失敗的最終原因,通常是上游服務本身的解釋,例如參數限制或內容政策決策。對於在 Official 路由上執行的任務,error_details.upstream 也會攜帶上游回報的錯誤:message,以及已知時的 code、param 與 source(上游服務名稱)。請持續根據 code 與 type 進行分支處理;upstream.code 的值由上游服務定義,可能會有所變動。
在任務被接受前拒絕建立請求的錯誤,會使用標準的 HTTP 錯誤狀態與結構化的 error 物件。重複相同的冪等(idempotent)建立請求會保留該拒絕結果。失敗的狀態讀取不會改變任務的終端狀態。
避免重複任務
大多數重複生成的情況源於在逾時後重試建立請求。
| 逾時發生的位置 | 更安全的行為 |
|---|---|
| 在您的伺服器收到建立回應之前 | 使用相同的 Idempotency-Key 再次發送相同請求以取得原始任務。若無 Key,請檢查 request_id,僅在未建立任務時才重試 |
| 在儲存建立回應之後 | 恢復輪詢已儲存的 task_id |
| 在輪詢期間 | 使用退避機制(backoff)重試狀態請求 |
| 在終端狀態之後 | 除非使用者明確重新整理記錄,否則不要再次輪詢 |
請勿僅因為瀏覽器重新整理或狀態輪詢失敗就發送第二次建立請求。
帳務記錄
非同步任務在被接受時可能會預留其預估成本。最終金額會在任務完成或失敗後記錄。狀態回應可能包含 billing_transaction_id 與 X-Billing-Transaction-ID 標頭。
請將這些識別碼保存在一起:
- 來自建立請求的
request_id。 - 來自任務的
task_id/id。 - 出現時的
billing_transaction_id。 - 您自己的使用者 ID、專案 ID 或工作 ID。
取消任務
DELETE /v1/tasks/{id} 可以取消支援的 Seedance 影片任務(當它們仍在佇列中時),包括 seedance-2.0 與 seedance-2.0-fast。
不支援的任務會回傳 400 unsupported_task_cancel。已經在執行中或已完成的任務會回傳 409 task_not_cancellable。取消是一個請求,並不保證已經在進行中的工作會立即停止。成功的取消會回傳 200,並帶有 status: "failed"、cancelled: true 與 cancellation_status: "cancelled"。已取消的任務不會收費。
疑難排解
| 徵狀 | 可能原因 | 檢查項目 |
|---|---|---|
404 async_task_not_found | 任務 ID 未知、屬於其他工作區,或已完成的任務已超過狀態視窗 | 檢查已儲存的 task_id 與 API Key 所屬的工作區 |
403 task_not_owned | 無法確認當前工作區對該任務的所有權 | 確認與 API Key 關聯的工作區或組織 |
503 async_task_owner_unavailable | 目前無法檢查任務所有權。retryable 為 true | 使用退避機制重試狀態請求 |
| 任務似乎永遠不會完成 | 用戶端持續輪詢錯誤的 URL,或在終端狀態前停止 | 使用已儲存的任務 ID 輪詢 GET /v1/tasks/{id} 並檢查最新狀態 |
| 缺少最終媒體 URL | 任務未完成,或完成時沒有可用的檔案 | 持續輪詢直到完成,若完成後仍無結果則視為失敗 |
| 使用者看到重複內容 | 重試路徑在逾時或重新整理後建立了新任務 | 透過您自己的工作 ID 與已儲存的 task_id 進行去重 |
| 帳務不符 | 最終帳務尚未記錄,或比較了錯誤的 ID | 比較 request_id、task_id 與 billing_transaction_id |
提供給支援團隊的資訊
請包含 request_id、task_id、出現時的 billing_transaction_id、端點、模型、時間以及您發送的欄位名稱。除非支援團隊特別要求提供遮蔽後的範例,否則請勿發送 API Key、私人媒體、簽章 URL 或完整的提示詞(prompts)。
API 參考
請停止輪詢終端狀態的任務,並在遇到 401、403、404 或不可重試的錯誤時停止。若要無需輪詢即可接收任務結果,請使用 mt-… 管理 Token 設定 Webhook 管理 API。
任務回應也會攜帶 X-Task-ID、X-Task-Type 與 X-Billing-Transaction-ID 標頭,您可以將其記錄在任務 ID 旁邊。