Skip to main content
Tapapi 的信任承诺之一是失败不扣。这里说的是最终结算结果：系统可能先预扣额度，请求失败后再返还；成功后按实际用量结算，多退少补。 预扣、结算和返还可能不是同一毫秒完成。对账时不要只看“请求刚发出后的余额”，要以最终用量日志、余额变化和任务状态为准。

​
原则

对账时以控制台用量、最终余额和请求记录为准。前端显示失败不等于模型一定失败，必须结合服务端响应和保存结果判断。

​
预扣、结算和返还

生产请求可能经历这条链路：
这意味着你可能在短时间内看到余额先变化，再随着最终结算调整。不要把“请求刚发出后的余额”当成最终账单。

​
同步请求

文本和普通图片同步请求的常见链路是：

​
异步任务

视频或其他异步任务可能先创建任务并预扣额度。提交任务成功后会先形成一笔任务消费记录；后续轮询发现任务失败，会返还任务额度。任务成功后，只有在上游返回可用于重算的用量信息、并且该模型按倍率计费时，才可能根据实际用量做差额调整。
不要用“用户关闭页面”判断是否应该退款。只有平台或上游最终没有有效结果，才按失败返还处理。

​
图片接口的特殊情况

图片公开主路径的计费口径是：看实际返回的 data.length，再和请求的 n 取较小值。也就是说，请求 n=1 但上游意外返回 2 张，当前主路径最多按 1 张计费；请求 n=2 但只返回 1 张，则按 1 张处理。 如果响应里出现 metadata.tapapi_partial，说明图片 fanout 过程中有部分子请求失败。此时要同时记录 requested_n、returned_n 和 failed_requests，并把已返回图片先转存；不要把已经成功返回的图片也当失败重新生成。
图片 URL 下载失败、对象存储上传失败或前端展示失败，不等同于模型生成失败。只要平台已经拿到有效结果，通常仍按有效结果计费。

​
不应自动重试的计费错误

​
开发者建议

  • 保存每次请求的响应状态
  • 保存平台返回的 request_id、upstream_request_id 和业务侧 task_id
  • 保存返回图片数量和返回字段：url / b64_json
  • 记录请求的 n 和实际返回的 data.length
  • 如果是图片部分成功，记录 metadata.tapapi_partial、returned_n 和 failed_requests
  • 如果是任务或视频，记录顶层 code、message、任务 status 和 fail_reason
  • 不要把“前端显示失败”和“服务端生成失败”混为一类
  • 发现异常先带请求时间和模型名联系支持

​
联系支持时带上

  • 请求时间和时区
  • 模型名
  • request_id
  • upstream_request_id
  • HTTP 状态码
  • error.type、error.code 和 error.message
  • 任务或视频接口的顶层 code、message 和 data
  • 业务 task_id
  • 请求的 n、实际返回图片数、部分成功元数据和保存状态
  • 控制台用量截图或余额变化截图