同步与异步 - Tapapi 文档

图片生成主线以同步返回为主：你的后端请求 Tapapi，Tapapi 在同一次 HTTP 响应里返回图片 url 或 b64_json。如果产品需要排队、进度、重试或批量任务，建议在你的业务系统里实现异步体验。

不要把 webhook、tapapi_task_id、image_urls 当作图片接口的通用生产字段。当前图片 webhook 和 Tapapi 托管轮询接口不作为公开稳定能力承诺。

当前口径

场景	建议
单张文生图	后端同步等待 Tapapi 响应
高质量或耗时模型	后端设置合理超时，失败后按错误码有限重试
批量生成	业务侧队列 + 单张任务状态
前端进度展示	前端轮询你的业务任务接口
图片 webhook	当前不要传 `webhook`
视频任务	按视频 API 的任务口径处理

推荐业务流程

用户提交生成任务
  -> 你的后端创建业务 task_id
  -> 写入 queued 状态
  -> worker 调用 Tapapi 同步图片接口
  -> 读取 data[].url 或 data[].b64_json
  -> 转存图片到你的对象存储
  -> 记录 X-Oneapi-Request-Id
  -> 写入 succeeded / retrying / failed
  -> 前端轮询你的业务 task_id

这样可以把“模型同步生成”和“产品异步体验”分开：Tapapi 负责生成结果，你的系统负责队列、进度、重试、通知和对账。

状态建议

状态	含义
`queued`	任务已创建，等待 worker 执行
`running`	已开始请求 Tapapi
`succeeded`	已拿到图片，并已转存到自有存储
`retrying`	本次失败，但属于可重试错误
`failed`	不可重试，或已达到最大重试次数
`canceled`	用户取消业务任务；不代表已取消上游生成

什么时候需要队列

批量生成商品图、封面、广告素材
用户不适合一直等待同一个 HTTP 请求
需要展示排队、生成中、成功、失败状态
需要限制并发、预算或每个用户的任务数
需要对 429、临时 5xx、network timeout 做有限重试
需要把图片结果统一转存到自己的对象存储

不建议

让浏览器直接长时间等待模型结果
没有业务 task_id 就无限重试
只保存 Tapapi 返回 URL，不做自有存储转存
把 webhook 当作当前图片接口稳定能力
批量任务只记录总状态，不记录每张图的返回字段、错误码和消耗
用户取消前端任务后，假设上游生成也一定取消

图片批量策略见批量生成，输出保存见输出图片保存。