核心指南
非同步任務與輪詢
創建非同步媒體任務，輪詢公共 TokenLab 任務狀態，並在不使用供應商特定 ID 的情況下對賬最終結果。
許多媒體端點是非同步的。創建請求開始工作並返回公共 TokenLab 任務身份；您的應用程式將輪詢直到該任務達到終端狀態。請勿圍繞上游任務 URL、路由 ID 或供應商回調行為構建客戶工作流程。
公共任務合約
創建響應可以包括：
| 欄位 | 意義 | 操作 |
|---|---|---|
id | 公共 TokenLab 任務 ID | 與您自己的任務記錄一起存儲 |
task_id | 相同公共任務身份的兼容別名 | 將其視為等同於 id |
status | 當前公共任務狀態 | 當它不是終端狀態時開始輪詢 |
poll_url | 首選狀態 URL | 當存在時優先使用此 URL |
model | 端點請求或解析的模型 | 存儲以便支持和計費調和 |
/v1/tasks/{id} 是公共非同步媒體任務的標準固定狀態端點。可能存在媒體特定的狀態路由以保持兼容性，但新的集成應優先使用 poll_url 或 /v1/tasks/{id}。
推薦流程
- 驗證用戶請求並發送帶有明確
model的創建調用。 - 在將控制權返回給 UI 之前，持久化
id/task_id、poll_url、端點、模型、用戶 ID 和您自己的任務 ID。 - 每
5-10s輪詢長時間運行的媒體任務。 - 只有在任務為
completed或failed時才停止。 - 在
completed時，讀取媒體特定的結果欄位並存儲最終 URL 或元數據。 - 在
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} 的支援範圍有意保持較窄。目前在所選任務支援取消時，可用於排隊中的 Seedance 影片任務，例如 seedance-1.5-pro、seedance-2.0 和 seedance-2.0-fast。
不支持的任務返回 400 unsupported_task_cancel。已經運行或處於終端狀態的任務返回 409 task_not_cancellable。構建取消 UI 時應設為「請求取消」，而不是保證停止的按鈕。
疑難排解
| 症狀 | 可能原因 | 檢查內容 |
|---|---|---|
404 async_task_not_found | 任務已過期或已不可用 | 檢查已儲存的 task_id 和 poll_url |
403 task_not_owned | 無法確認任務屬於目前工作區 | 確認 API 金鑰所屬的工作區或組織 |
| 任務似乎永遠無法完成 | 客戶端不斷輪詢錯誤的 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 或完整提示。