> ## 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.

# 同步与异步

> 图片生成的同步返回、业务队列和轮询设计

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

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

## 当前口径

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

## 推荐业务流程

```text theme={null}
用户提交生成任务
  -> 你的后端创建业务 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` 当作当前图片接口稳定能力
* 批量任务只记录总状态，不记录每张图的返回字段、错误码和消耗
* 用户取消前端任务后，假设上游生成也一定取消

图片批量策略见 [批量生成](/image-generation/batch-generation)，输出保存见 [输出图片保存](/image-generation/output-images)。