任务查询与轮询

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

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

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

轮询适合什么

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

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

task_id | request_id | model | status | retry_count | error_code | quota | created_at | updated_at

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

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

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

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

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

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

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

异步任务可能先预扣额度。任务失败时会走失败返还；任务成功后如果实际消耗和预扣不同，会按最终结果差额结算。对账时以控制台用量和最终 quota 为准。托管异步任务如果超过平台任务超时窗口，会被标记为失败并进入返还流程；普通图片同步主路径仍建议由你的业务系统维护队列状态、超时状态和补跑次数。

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

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

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