> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 非同步任務與輪詢

> 創建非同步媒體任務，輪詢公共 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}`。

## 推薦流程

1. 驗證用戶請求並發送帶有明確 `model` 的創建調用。
2. 在將控制權返回給 UI 之前，持久化 `id` / `task_id`、`poll_url`、端點、模型、用戶 ID 和您自己的任務 ID。
3. 每 `5-10s` 輪詢長時間運行的媒體任務。
4. 只有在任務為 `completed` 或 `failed` 時才停止。
5. 在 `completed` 時，讀取媒體特定的結果欄位並存儲最終 URL 或元數據。
6. 在 `failed` 時，存儲公共錯誤並僅作為新的用戶可見任務提供重試。

```json theme={null}
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "model": "veo3.1"
}
```

## 輪詢範例

```bash theme={null}
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 參考

| 主題     | 參考                                                     |
| ------ | ------------------------------------------------------ |
| 獲取任務狀態 | [獲取任務狀態](/zh-Hant/api-reference/tasks/get-task-status) |
| 取消任務   | [取消任務](/zh-Hant/api-reference/tasks/cancel-task)       |
| 圖像生成   | [圖像生成](/zh-Hant/guides/image-generation)               |
| 視頻生成   | [視頻生成](/zh-Hant/guides/video-generation)               |
| 音樂生成   | [音樂生成](/zh-Hant/guides/music-generation)               |
| 3D 生成  | [3D 生成](/zh-Hant/guides/3d-generation)                 |
| 計費與定價  | [計費與定價](/zh-Hant/guides/billing)                       |