批量生成 - Tapapi 文档

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

批量跑图前先确认

问题	去哪里看
选哪个模型更便宜	模型对比
请求失败怎么重试	错误码与重试
并发怎么控	限流与并发
图片 URL 保存多久	输出图片保存
怎么避免成本失控	成本控制

推荐做法

给每张图片生成业务侧 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 批量、商品图任务

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

任务状态建议

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

重试策略

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

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

返回数量处理

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

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

{
  "metadata": {
    "tapapi_partial": true,
    "requested_n": 4,
    "returned_n": 3,
    "failed_requests": 1,
    "mode": "fanout"
  }
}

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

语言示例

场景	文档
Python 脚本	Python
Node.js 队列	Node.js / TypeScript
不使用 SDK	HTTP REST

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