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

# 任务查询与轮询

> 异步任务、状态查询和结果获取

这页说明异步任务、轮询和业务侧队列设计。当前文本和普通图片请求优先按同步接口理解；长任务、视频任务和批量任务建议在业务侧建立任务队列。

<Warning>当前图片生成主线不是 Tapapi 托管任务轮询接口。图片批量、排队、进度展示，应优先在你的业务系统里实现。</Warning>

视频 API 按受控开放维护，底层存在任务状态和轮询逻辑，也有任务提交、查询和内容获取接口；但不是所有账户、所有模型都默认开放统一托管查询接口。文档先给出业务侧实现方式，避免用户误以为所有任务都有同一个公开 task endpoint。

## 轮询适合什么

| 场景      | 说明                       |
| ------- | ------------------------ |
| 长时间生成   | 避免客户端一直等待；当前建议查询你的业务任务状态 |
| 批量任务    | 每张图独立记录状态；当前建议由你的业务队列管理  |
| 后台处理    | 生成完成后再通知用户；当前通知逻辑由业务系统实现 |
| 视频或更长任务 | 按受控开放能力确认，不默认作为所有用户的生产承诺 |

## 业务侧状态建议

下面是你的业务系统建议保存的状态，不是 Tapapi 内部任务状态。业务状态可以根据产品体验增加 `retrying`、`canceled` 等中间态。

| 状态        | 含义                   |
| --------- | -------------------- |
| queued    | 已接收，等待处理             |
| running   | 正在生成                 |
| retrying  | 临时失败后等待有限重试          |
| succeeded | 成功                   |
| failed    | 失败                   |
| canceled  | 用户取消业务任务；不代表已经取消上游生成 |

建议你的业务系统至少保存：

```text theme={null}
task_id | request_id | model | status | retry_count | error_code | quota | created_at | updated_at
```

## 当前图片推荐实现

```text theme={null}
前端创建任务
  -> 你的后端写入 queued
  -> worker 调用 Tapapi 同步接口
  -> 成功后转存图片并写入 succeeded
  -> 失败后按 error.code 决定 retrying 或 failed
  -> 前端轮询你的业务任务接口
```

图片接口返回成功后，要先把图片转存到自己的对象存储，再把业务任务标记为 `succeeded`。如果模型已经成功但转存失败，不要重复生成，应该重试转存。

## 视频/异步状态口径

视频和异步任务内部会出现这些状态：

| 内部状态          | 对外含义         |
| ------------- | ------------ |
| `NOT_START`   | 任务已创建但尚未开始处理 |
| `SUBMITTED`   | 已提交上游        |
| `QUEUED`      | 上游排队中        |
| `IN_PROGRESS` | 正在生成         |
| `SUCCESS`     | 已完成          |
| `FAILURE`     | 失败           |
| `UNKNOWN`     | 状态未知，需要继续排查  |

面向客户展示时，可以映射成：

| 展示状态          | 来源                     |
| ------------- | ---------------------- |
| `queued`      | `SUBMITTED` / `QUEUED` |
| `in_progress` | `IN_PROGRESS`          |
| `completed`   | `SUCCESS`              |
| `failed`      | `FAILURE`              |
| `unknown`     | `UNKNOWN` 或上游未返回明确状态   |

<Note>视频任务成功后可能有结果 URL、进度、失败原因和异步计费调整。具体字段以受控开放接口返回为准，不建议在公开业务里提前写死未确认字段。</Note>

任务类错误响应可能直接返回 `code`、`message`、`status_code` 语义，而不一定是普通同步接口的 `{ "error": ... }` 结构。业务侧应统一记录任务 `code`、`message`、HTTP 状态码、`task_id` 和模型名。

## 失败与计费

业务队列里要把“请求失败”和“图片保存失败”分开：

| 阶段         | 计费和处理               |
| ---------- | ------------------- |
| 请求未进入模型    | 通常不应扣费              |
| 模型失败且无有效结果 | 以最终结算返还为准           |
| 模型成功但转存失败  | 通常已生成成功，应继续重试转存     |
| 用户取消前端等待   | 不代表模型请求已经取消，需要看后端结果 |

异步任务可能先预扣额度。任务失败时会走失败返还；任务成功后如果实际消耗和预扣不同，会按最终结果差额结算。对账时以控制台用量和最终 `quota` 为准。

托管异步任务如果超过平台任务超时窗口，会被标记为失败并进入返还流程；普通图片同步主路径仍建议由你的业务系统维护队列状态、超时状态和补跑次数。

## 轮询频率建议

图片业务侧队列可以轮询你自己的业务接口：

| 阶段   | 建议               |
| ---- | ---------------- |
| 刚提交后 | 1-2 秒后再第一次查询     |
| 生成中  | 每 2-5 秒查询一次      |
| 长任务  | 逐步拉长到 10-15 秒    |
| 连续失败 | 停止轮询，展示失败原因和重试入口 |

视频或托管异步任务查询建议更保守：

| 阶段     | 建议            |
| ------ | ------------- |
| 刚提交后   | 5-10 秒后再第一次查询 |
| 排队中    | 每 10-20 秒查询一次 |
| 生成中    | 每 15-30 秒查询一次 |
| 超过预期时间 | 标记为待确认，不要无限等待 |

不要把轮询做成无上限的高频请求。轮询本身也会消耗系统资源，批量任务尤其要控制。