# 非同步任務

提交長任務、輪詢狀態、處理終態並取得結果。

部分 Felo 操作會立即回傳 `task_id`，並在背景完成。模式在各處都相同：提交、輪詢，然後取得結果。

## 兩種任務家族

| 家族 | 提交 | 輪詢 |
|--------|--------|------|
| Felo 工作流程 | `POST /v2/ppts`、`POST /v2/landing_page`、`POST /v2/mindmap` | `GET /v2/tasks/{task_id}/status` |
| 模型生成 | `POST /api/v1/videos/generations`、`POST /api/v1/images/generations` | `GET /api/v1/videos/generations/{task_id}`、`GET /api/v1/images/generations/{task_id}` |

PPTX 匯出是另一個非同步操作：`POST /v2/ppts/{ppt_business_id}/export`，然後 `GET /v2/ppts/{ppt_business_id}/export`。

SuperAgent 不是輪詢式 API。它回傳 `stream_key` 並使用 SSE；請參閱 [SuperAgent 參考](https://openapi.felo.ai/zh-TW/docs/api-reference/superagent.md)。

## 生命週期

1. **提交。** 送出模型或工作流程參數。提交成功會回傳 `task_id` 與初始狀態。
2. **輪詢。** 依固定間隔讀取任務 endpoint。在程式碼中保有間隔與最長等待時間。
3. **完成。** 成功時讀取結果 URL 或輸出欄位。失敗時讀取錯誤，判斷是否重新提交。

## 狀態值

Felo 工作流程任務使用大寫值：

| 狀態 | 含義 |
|--------|---------|
| `RUNNING` | 仍在處理 |
| `COMPLETED` | 成功完成 |
| `FAILED` | 終態失敗；讀取 `error_message` |
| `PENDING` | 在歷史回應中為終態；讀取 `error_message` |
| `EXPIRED` | 終態；任務已不再可用 |
| `CANCELED` | 終態；任務已取消 |

模型生成任務使用小寫值：`queued`、`running`、`succeeded`、`failed` 與 `interrupted`。失敗的任務可能包含帶有 `message` 與 `type` 的 `error` 物件。

後端演進時可能出現未知狀態值。除非文件另有說明，否則把未知值視為非終態。

## 輪詢

- Felo 工作流程任務：每 2–5 秒輪詢一次。
- 影片生成：每 5–10 秒輪詢一次。
- 圖像生成：從 2–5 秒開始，長時間任務逐步拉長間隔。
- 在終態、你選擇的逾時時間，或達到最大嘗試次數時停止。
- 許多用戶端同時輪詢時，加入 jitter。

簡單的 Node.js 迴圈：

```javascript
async function pollStatus(taskId, { timeoutMs = 10 * 60 * 1000 } = {}) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const response = await fetch(`https://openapi.felo.ai/v2/tasks/${taskId}/status`, {
      headers: { Authorization: `Bearer ${process.env.FELO_API_KEY}` },
    });
    if (!response.ok) throw new Error(`status ${response.status}`);
    const payload = await response.json();
    const status = payload.data?.status;
    if (status === "COMPLETED") return payload.data;
    if (["FAILED", "PENDING", "EXPIRED", "CANCELED"].includes(status)) {
      throw new Error(payload.data?.error_message || status);
    }
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
  throw new Error("task timed out");
}
```

## 取得結果

| 任務 | 結果 |
|------|--------|
| PPT | `GET /v2/tasks/{task_id}/historical` 會回傳 `ppt_url`、`ppt_biz_id`，以及在可用時回傳 `live_doc_url` |
| 落地頁 | 歷史回應會回傳頁面輸出，以及在可用時回傳 `live_doc_url` |
| 影片 / 圖像 | 輪詢回應會回傳 `outputs`；成功時，項目是可匿名下載的簽章媒體 URL。有效期與下載方式見[圖片生成](https://openapi.felo.ai/zh-TW/docs/guides/image-generation.md) |
| PPTX 匯出 | 只有在 `status` 為 `COMPLETED` 時，輪詢回應才會回傳 `download_url` 與 `expires_at` |

PPTX 簽名下載 URL 在簽發後 30 分鐘過期。再次呼叫 GET endpoint 取得新 URL；這不會重新生成檔案。

## 失敗處理

- 重試前先讀取任務的錯誤欄位。有些失敗由請求本身造成，會重複發生。
- 不要每次逾時就盲目重新提交；先確認任務是否仍是 `RUNNING`。
- `402` 表示額度不足。`429` 表示觸發限流。條件解除後才重試。
- 影片生成請求帶 callback 欄位會回傳 `400`；圖像生成會忽略這些欄位。請輪詢任務 endpoint，不要等待 webhook。

## 相關

- [PPT Task API](https://openapi.felo.ai/zh-TW/docs/api-reference/ppt-tasks.md)
- [Landing Page Task API](https://openapi.felo.ai/zh-TW/docs/api-reference/landing-page.md)
- [Model API 參考](https://openapi.felo.ai/zh-TW/docs/model-api)
- [圖片生成](https://openapi.felo.ai/zh-TW/docs/guides/image-generation.md)
- [錯誤、限流與重試](https://openapi.felo.ai/zh-TW/docs/guides/errors-and-limits.md)
