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 额度上限和余额停止阈值会生效