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

# 批量生成

> 批量跑图时的模型选择、并发和成本控制

批量生成适合内容工厂、商品图、素材生成和 A/B 测试。关键不是单次请求能不能跑，而是并发、失败重试、成本和结果保存。

## 批量跑图前先确认

| 问题          | 去哪里看                                      |
| ----------- | ----------------------------------------- |
| 选哪个模型更便宜    | [模型对比](/models/comparison)                |
| 请求失败怎么重试    | [错误码与重试](/errors)                         |
| 并发怎么控       | [限流与并发](/production/rate-limits)          |
| 图片 URL 保存多久 | [输出图片保存](/image-generation/output-images) |
| 怎么避免成本失控    | [成本控制](/production/cost-control)          |

## 推荐做法

* 给每张图片生成业务侧 `task_id`
* 默认用 `n: 1` 单张循环，方便精确记录每张图状态和成本
* 记录 `prompt`、`model`、`size`、`n`、`response_format`、返回字段、错误码和消耗
* 对 429 / 临时 5xx / network timeout 做有限次数指数退避
* 把输出图片及时保存到自己的对象存储，不要依赖临时 URL
* 批量放大前先抽样 20-50 条真实 prompt，确认成功率、耗时和成本
* 余额不足按 `error.code: "insufficient_user_quota"` 判断，不要自动重试
* 每次请求保存 `X-Oneapi-Request-Id`，每张图片保存自己的业务 `task_id`

## 请求策略

| 策略      | 适合                      |
| ------- | ----------------------- |
| 单张循环    | 默认推荐；要精确记录每张图状态、成本和失败原因 |
| `n > 1` | 纯文生图，且模型/渠道明确支持多张返回     |
| 业务侧队列   | 内容工厂、CSV 批量、商品图任务       |

<Note>图片 fan-out 只适合纯文生图 JSON 请求。带 `image_urls`、`mask`、图片输入或编辑字段的请求，不要和 `n > 1` 混在一起。</Note>

## 任务状态建议

| 状态          | 说明                  |
| ----------- | ------------------- |
| `queued`    | 已进入业务队列，尚未请求 Tapapi |
| `running`   | 已开始请求模型             |
| `succeeded` | 已拿到图片，并已转存到自有存储     |
| `retrying`  | 本次失败，但属于可重试错误       |
| `failed`    | 已达到最大重试次数或错误不可重试    |

## 重试策略

| 错误                       | 建议                  |
| ------------------------ | ------------------- |
| 400 / 422                | 不重试，修正字段或 prompt    |
| 401                      | 不重试，检查 API Key      |
| 403                      | 不重试，检查账户状态、余额、分组和权限 |
| 429                      | 降低并发，指数退避后重试        |
| 临时 5xx / network timeout | 可以重试 1-2 次，并记录失败原因  |
| 504 / 524                | 先查业务状态和账单，再决定是否补跑   |

<Warning>不要在没有业务 `task_id` 的情况下无限重试。图片生成一旦成功，上游通常已经产生真实成本；重复请求可能生成多张不同图片，也会让对账变复杂。</Warning>

## 返回数量处理

| 情况           | 处理                                  |
| ------------ | ----------------------------------- |
| 返回数量等于请求 `n` | 正常处理并转存                             |
| 返回数量少于请求 `n` | 按实际返回保存，缺失图片单独补跑                    |
| 返回数量多于请求 `n` | 业务只处理需要的数量；计费会封顶到请求 `n`             |
| `data` 为空    | 按生成失败处理，记录模型、请求时间、错误信息和业务 `task_id` |

部分渠道在 `n > 1` 时会由 Tapapi fan-out 聚合多次单图请求。如果部分子请求失败，响应可能带上类似下面的 metadata：

```json theme={null}
{
  "metadata": {
    "tapapi_partial": true,
    "requested_n": 4,
    "returned_n": 3,
    "failed_requests": 1,
    "mode": "fanout"
  }
}
```

遇到 `tapapi_partial: true` 时，不要整批丢弃；应先保存已经返回的图片，再按缺失数量补跑。

## 语言示例

| 场景         | 文档                                                    |
| ---------- | ----------------------------------------------------- |
| Python 脚本  | [Python](/integrations/python)                        |
| Node.js 队列 | [Node.js / TypeScript](/integrations/node-typescript) |
| 不使用 SDK    | [HTTP REST](/integrations/http-rest)                  |

CSV 输入 / 输出模板和失败重跑策略会放在后续批量任务专题里。