---
title: 非同步任務流程
description: 正確處理排隊、生成、完成與失敗狀態。
icon: workflow
---

影片生成不是同步請求。建立介面在任務成功提交後返回任務 ID，生成結果需要後續查詢。

```text
POST /v1/videos
       |
       v
    queued  --->  in_progress  --->  completed
                       |
                       +------------> failed
```

## 狀態說明

| 狀態 | 含義 | 客戶端行為 |
| --- | --- | --- |
| `queued` | 已進入任務佇列 | 等待後繼續查詢 |
| `in_progress` | 正在生成 | 等待後繼續查詢 |
| `completed` | 生成完成 | 呼叫內容介面獲取影片 |
| `failed` | 最終失敗 | 停止輪詢並記錄 `error` |
| `unknown` | 無法識別的狀態 | 記錄完整響應並聯系支援 |

## 輪詢策略

建議以 5 秒為初始間隔，並逐步增加到 10 至 15 秒：

```javascript
const delays = [5000, 5000, 10000, 10000, 15000];
```

- 對 `queued` 和 `in_progress` 繼續輪詢。
- 對 `completed` 和 `failed` 立即停止輪詢。
- 為每個業務任務設定合理的最長等待時間。
- 網路超時不代表影片任務失敗，可稍後使用原任務 ID 再查。

<Warning>
不要因為查詢介面暫時超時而重新建立任務。重新建立會產生獨立任務，並可能再次計費。
</Warning>

## 業務側狀態

建議在你的資料庫中至少儲存：

- 黑豬AI任務 ID
- 業務訂單 ID
- 模型名稱
- 提交時間和最後查詢時間
- 當前狀態與進度
- 最終錯誤資訊
- 結果是否已成功儲存

客戶端斷開不會自動取消已提交任務。頁面重新整理後，應從業務資料庫恢復任務 ID 並繼續查詢。