# 任务与轮询

> 了解任务状态机、同步等待、轮询查询、取消任务以及结果文件的保留周期。

## 任务生命周期

每次生成请求都会创建一个任务对象（`object: "task"`），状态流转如下：

- `queued`：已受理并冻结预估费用，等待开始执行。只有 `queued` 状态的任务可以取消。
- `running`：生成中。
- `succeeded`：终态。生成文件在 `output` 中返回，`cost.status` 为 `"settled"`。
- `failed`：终态。失败原因在 `error` 中返回，`cost.status` 为 `"refunded"`，冻结金额全额退回。
- `canceled`：终态。在排队阶段被取消，`cost.status` 为 `"refunded"`。

## 同步等待与轮询

对于耗时较短的图片模型，可在 `POST /v1/tasks` 中传入 `wait_seconds`（1–60 秒），在一次请求内等待结果。对于视频等长耗时任务，建议使用默认 `wait_seconds: 0`，通过 [Webhook](/docs/webhooks) 接收回调，或每隔 2–5 秒轮询一次 `GET /v1/tasks/{id}`。

```bash
curl https://api.kerox.ai/v1/tasks/task_01JD8X9B4Q2M7T8N3K5P6R1S0V \
  -H "Authorization: Bearer $KEROX_API_KEY"
```
```python
import os
import time
import requests

headers = {"Authorization": f"Bearer {os.environ['KEROX_API_KEY']}"}
task_id = "task_01JD8X9B4Q2M7T8N3K5P6R1S0V"

while True:
    task = requests.get(
        f"https://api.kerox.ai/v1/tasks/{task_id}",
        headers=headers,
        timeout=30,
    ).json()
    if task["status"] in ("succeeded", "failed", "canceled"):
        print(task)
        break
    time.sleep(3)
```
```javascript
const headers = { Authorization: `Bearer ${process.env.KEROX_API_KEY}` };
const taskId = 'task_01JD8X9B4Q2M7T8N3K5P6R1S0V';

while (true) {
  const res = await fetch(`https://api.kerox.ai/v1/tasks/${taskId}`, { headers });
  const task = await res.json();
  if (['succeeded', 'failed', 'canceled'].includes(task.status)) {
    console.log(task);
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 3000));
}
```

## 列表查询与取消任务

- **任务列表**：`GET /v1/tasks?status=succeeded&model=bytedance/seedance-2.5&limit=20&cursor=...` 按时间倒序返回你的任务，覆盖 API、Studio 和 MCP 三种来源。可以按 `status`、`model`、`source` 筛选；`limit` 为 1–100（默认 20）。`has_more` 为 `true` 时，把 `next_cursor` 作为 `cursor` 传入取下一页。
- **取消排队任务**：`POST /v1/tasks/{id}/cancel` 可取消 `queued` 任务并立即释放冻结资金；若任务已开始或结束，则返回 HTTP `409`（`task_not_cancelable`）。

## 透传字段、超时与保留期

- **透传字段 `metadata`**：支持传入不超过 4 KB 的任意 JSON 对象（例如 `{"order_id": "A1001"}`），查询与 Webhook 回调会原样带回。
- **任务超时**：默认图片任务 10 分钟、视频任务 60 分钟（单个模型的精确上限见 `GET /v1/models/{id}` 的 `timeout_seconds`）。超时的任务会判为失败（`timeout`）并全额退回。
- **文件保留期**：生成结果与上传文件保留 7 天（详见 `expires_at`）；任务记录与钱包流水永久保留。
