跳轉到主要內容
許多媒體端點是非同步的。創建請求開始工作並返回公共 TokenLab 任務身份；您的應用程式將輪詢直到該任務達到終端狀態。請勿圍繞上游任務 URL、路由 ID 或供應商回調行為構建客戶工作流程。

​
公共任務合約

創建響應可以包括：
欄位意義操作
id公共 TokenLab 任務 ID與您自己的任務記錄一起存儲
task_id相同公共任務身份的兼容別名將其視為等同於 id
status當前公共任務狀態當它不是終端狀態時開始輪詢
poll_url首選狀態 URL當存在時優先使用此 URL
model端點請求或解析的模型存儲以便支持和計費調和
/v1/tasks/{id} 是公共非同步媒體任務的標準固定狀態端點。可能存在媒體特定的狀態路由以保持兼容性，但新的集成應優先使用 poll_url 或 /v1/tasks/{id}。

​
推薦流程

  1. 驗證用戶請求並發送帶有明確 model 的創建調用。
  2. 在將控制權返回給 UI 之前，持久化 id / task_id、poll_url、端點、模型、用戶 ID 和您自己的任務 ID。
  3. 每 5-10s 輪詢長時間運行的媒體任務。
  4. 只有在任務為 completed 或 failed 時才停止。
  5. 在 completed 時，讀取媒體特定的結果欄位並存儲最終 URL 或元數據。
  6. 在 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"，以便舊的狀態處理繼續正常運作。

​
客戶端重試規則

網絡超時是重複任務的最常見來源。使用以下規則：
超時發生的位置更安全的行為
在您的伺服器接收到創建響應之前檢查伺服器日誌中的 request_id；僅在未創建任務的情況下重試
在創建響應被存儲之後繼續輪詢存儲的 task_id
在輪詢期間以退避方式重試狀態請求
在終端狀態之後除非用戶明確刷新記錄，否則不要再次輪詢
不要僅因為瀏覽器刷新或狀態輪詢失敗而發送第二個創建請求。

​
計費與結算

非同步任務在創建請求被接受時可以保留預估金額。最終結算在終端狀態之後進行。當可用時，任務狀態響應可以暴露 billing_transaction_id 和 X-Billing-Transaction-ID 標頭。 為了調和，請在您的日誌中聯合這些標識符：
  • 創建請求中的 request_id。
  • 任務中的 task_id / id。
  • 當存在時的 billing_transaction_id。
  • 您自己的用戶 ID、項目 ID 或任務 ID。

​
取消

DELETE /v1/tasks/{id} 是故意狹窄的。它目前支持排隊的 Volcengine Seedance 視頻任務，如 seedance-1.5-pro、seedance-2.0 和 seedance-2.0-fast。 不支持的任務返回 400 unsupported_task_cancel。已經運行或處於終端狀態的任務返回 409 task_not_cancellable。構建取消 UI 時應設為「請求取消」，而不是保證停止的按鈕。

​
疑難排解

症狀可能原因檢查內容
async_task_not_found任務未知、過期、對此 API 密鑰不可訪問，或不是公共非同步任務確認 API 密鑰擁有權和存儲的公共 task_id
任務似乎永遠無法完成客戶端不斷輪詢錯誤的 URL 或在終端狀態之前停止使用 poll_url 或 /v1/tasks/{id} 並檢查最新狀態
最終媒體 URL 缺失任務未完成，或上游任務完成但沒有可用輸出繼續輪詢直到終端，然後將缺失的輸出視為失敗
用戶看到重複項重試路徑在超時或刷新後創建了新任務通過您自己的任務 ID 和存儲的 task_id 去重
計費不匹配結算是非同步的或客戶端在比較供應商 ID比較 request_id、task_id 和 billing_transaction_id

​
支持包

聯繫支持時，請包括 request_id、task_id、billing_transaction_id（如果存在）、端點、模型、時間戳和經過清理的請求形狀。除非支持要求提供經過編輯的示例，否則請勿包括 API 密鑰、私人媒體、簽名 URL 或完整提示。

​
API 參考

主題參考
獲取任務狀態獲取任務狀態
取消任務取消任務
圖像生成圖像生成
視頻生成視頻生成
音樂生成音樂生成
3D 生成3D 生成
計費與定價計費與定價