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

# 上线 Checklist

> 文本、图片和受控视频 API 接入生产前的最后检查

上线前用这份清单检查接入是否完整。不要只验证“某个接口能返回成功”，还要验证失败、超时、限流、计费、保存路径、任务轮询和排障链路。

视频 API 当前按受控开放处理。如果你的账号没有开通视频模型、价格或权限，不需要把视频项作为生产必检项。

## 1. 密钥与环境

* [ ] API Key 没有暴露在前端或公开仓库
* [ ] base\_url 指向 `https://tapapi.ai/v1`
* [ ] 前端只调用你的后端，不直接持有 Tapapi Key
* [ ] 生产、测试、批量任务使用不同业务标识或不同 API Key 管理
* [ ] 批量或自动化任务 Key 已设置额度上限，不使用无上限 Key 直接跑量
* [ ] 已按业务需要配置 Key 过期时间、模型白名单、IP 限制和分组
* [ ] 已确认控制台里账户余额、分组和可用模型
* [ ] 已设置余额不足或 Key 额度不足的告警/人工提醒
* [ ] 如需视频，已确认控制台可见对应视频模型、价格和账号权限

## 2. 接口调用

* [ ] 默认模型和兜底模型已确定
* [ ] 文本接口已确认 `POST /v1/chat/completions` 或 `POST /v1/responses` 的同步/流式两种返回处理
* [ ] 图片接口已确认使用 `POST /v1/images/generations` 作为文生图主路径
* [ ] 图片编辑、增强或私有路径只在对应模型文档明确要求时使用
* [ ] `response_format` 已确认，并同时兼容 `url` 和 `b64_json`
* [ ] 已确认默认 `n` 策略；批量任务优先 `n: 1`
* [ ] 已确认模型支持的 `size`、`quality` 和 `output_format`
* [ ] 如需视频，优先按 `/v1/videos` 提交、`/v1/videos/{task_id}` 查询、`/v1/videos/{task_id}/content` 获取内容
* [ ] `/v1/video/generations` 只在模型文档或受控接入说明要求时使用
* [ ] 业务日志会保存接口类型、模型、关键参数摘要和业务请求 ID

## 3. 错误处理

* [ ] 400 / 401 / 403 / 429 / 临时 5xx / timeout 已分别处理
* [ ] 余额不足按 `insufficient_user_quota` 判断，不依赖固定 `402`
* [ ] 预扣失败按 `pre_consume_token_quota_failed` 处理，不自动重试
* [ ] 参数错误、鉴权错误、余额不足、权限错误不会自动重试
* [ ] 429 有降并发、指数退避和最大重试次数
* [ ] 504 / 524 不会盲目重放，先查 `request_id` 和用量日志
* [ ] 普通 API 错误会记录 HTTP 状态码、`error.type`、`error.code`、`error.message`
* [ ] 任务/视频错误会额外记录顶层 `code`、`message`、`data`、任务状态和失败原因
* [ ] 每次异常都会记录 `request_id`；如果返回或日志中有 `upstream_request_id` 也一起保存

## 4. 限流与超时

* [ ] 文本、图片、视频分别设置业务侧并发上限
* [ ] 已理解平台限流是入口保护，不能替代你的业务队列和并发池
* [ ] worker 有最大重试次数和随机抖动
* [ ] 连续 429 会自动降并发或暂停放量
* [ ] 用户端不会无限等待生成结果
* [ ] 后端 timeout 长于前端等待时间，并会保存最终结果
* [ ] 流式文本已处理空 `delta`、ping/keep-alive、长时间无内容、连接中断和用户关闭页面
* [ ] 长任务不会让浏览器直接等待到底，而是进入业务队列或轮询流程
* [ ] 如需视频，已设置轮询间隔、最长等待时间和超时后的人工/自动处理策略

## 5. 输出保存

* [ ] 文本结果会保存最终完整内容、模型、token 用量和业务请求 ID
* [ ] 输出图片会保存到自有 COS、S3、R2 或 OSS
* [ ] 已处理 `data=[]`、返回张数少于预期、返回张数多于预期的情况
* [ ] 已记录 `requested_n`、`returned_n`、`saved_count` 和保存失败原因
* [ ] 已兼容图片部分成功元数据，例如 `metadata.tapapi_partial`、`failed_requests`
* [ ] 已记录每张图的业务 `task_id`、模型、prompt、返回字段和保存状态
* [ ] URL 下载失败时会先重试转存，不会直接重复生成
* [ ] 只返回 `b64_json` 时能正常解码并转存
* [ ] 如需视频，完成后会立刻下载或读取内容路径并转存，不长期依赖临时 URL

## 6. 计费与对账

* [ ] 账单和业务 `task_id` 能对上
* [ ] 每次请求都保存 `request_id`，有条件时保存 `upstream_request_id`
* [ ] 业务表记录 `token_name`、接口类型、模型、最终 `quota` 和请求结果
* [ ] 文本请求记录 `prompt_tokens`、`completion_tokens`、`total_tokens`
* [ ] 图片请求记录 `requested_n`、`returned_n`、`saved_count`、`failed_requests`
* [ ] 视频任务记录 `task_id`、状态、时长、分辨率、结果保存状态和最终 `quota`
* [ ] 余额不足时有提示或告警
* [ ] 已理解“预扣 -> 结算 -> 失败返还 / 差额结算”的链路
* [ ] 批量任务启动前已设置预算上限、Key 额度上限和 worker 停止阈值
* [ ] 已确认部分成功、无有效结果、转存失败分别如何影响业务账单展示

## 7. 任务与批量

* [ ] 批量任务有业务队列，不让浏览器直接等待所有结果
* [ ] 业务任务状态至少包含 `queued / running / retrying / succeeded / failed / canceled`
* [ ] 平台任务状态和业务任务状态分开保存，不把内部 `SUCCESS / FAILURE / IN_PROGRESS` 直接当产品文案
* [ ] 模型成功但转存失败时，会重试转存而不是重生图片
* [ ] 同一业务 `task_id` 有最大补跑次数
* [ ] 已限制用户重复提交和后台重复重试
* [ ] 已做幂等保护：刷新页面、重复点击、worker 重启不会无限创建新请求
* [ ] 审核拒绝、权限错误、余额不足不会进入无限重试
* [ ] 如需视频，已保存平台 `task_id`、进度、失败原因和内容转存状态

## 8. 上线前压测

* [ ] 用 20-50 条真实 prompt 或业务样本跑小样本
* [ ] 文本已覆盖同步和流式两种场景
* [ ] 图片已覆盖 `url`、`b64_json`、`n: 1` 和业务实际使用的多图策略
* [ ] 如需视频，已用已开通模型验证提交、轮询、失败、完成和内容转存
* [ ] 观察成功率、平均耗时、P95 耗时、429、5xx 和 timeout
* [ ] 验证失败不扣和最终账单
* [ ] 验证 URL / base64 两种返回都能保存
* [ ] 验证前端刷新、重复点击和 worker 重试不会重复提交失控
* [ ] 验证连续 429 后并发会下降
* [ ] 验证 `request_id` 能在控制台用量日志中定位
* [ ] 验证业务侧预算上限、Key 额度上限和余额停止阈值会生效

## 支持排障包

上线后遇到异常，先准备：

```text theme={null}
请求时间和时区：
接口类型：text / image / video
接口路径：
模型：
API Key 名称 / token_name：
request_id：
upstream_request_id：
业务 task_id / 视频 task_id：
HTTP 状态码：
error.type：
error.code：
error.message：
任务 code / message / status / fail_reason：
请求参数摘要：
文本 token 用量：
图片 requested_n / returned_n / saved_count / failed_requests：
视频状态 / 时长 / 分辨率 / 输出地址类型：
是否已经转存到自有存储：
控制台用量截图：
业务重试次数和 worker 日志：
```

相关页面：

* [错误码与排查](/errors)
* [限流与并发](/production/rate-limits)
* [超时与重试](/production/timeouts)
* [任务轮询策略](/production/task-polling)
* [失败返还与计费边界](/production/failure-refund)
* [成本控制](/production/cost-control)