计费与退款 - Tapapi 文档

Tapapi 的计费核心是余额额度。你充值后会获得可用于 API 调用的额度；每次请求会根据模型、分组、输入输出、图片张数或任务结果扣减额度。

控制台展示的余额、用量记录和充值记录是对账主入口。不同支付方式、最低充值金额、充值档位和折扣都可能由后台配置调整，请以控制台当前展示为准。

余额是什么

内部计费使用 quota 作为额度单位。通常可以把 500000 quota 理解为约 1 USD 额度，但生产对账不要自己换算，优先看控制台展示和最终账单。

充值入口会显示当前可用支付方式、最低充值金额、充值档位和折扣。常见流程：

选择充值金额
  -> 创建支付订单 pending
  -> 完成支付
  -> 支付回调确认
  -> 订单变为 success
  -> 余额增加

普通用户可在控制台查看近期充值记录，用于排障和对账。长期财务归档建议自己保存订单号、支付截图和发票/收据材料。

不要把“支付页面显示成功”当成最终到账依据。最终以控制台订单状态和余额变化为准；如果支付成功但余额未增加，请在 /wallet 使用“充值未到账？订单申诉”，并附订单号和支付截图。

余额不足或订阅额度不足时，请求通常不会进入正式生成，也不应扣费。API 侧常见表现是：

{
  "error": {
    "message": "...",
    "type": "new_api_error",
    "code": "insufficient_user_quota"
  }
}

处理建议：

场景	建议
HTTP 403 + `insufficient_user_quota`	提醒充值、升级或切换账户
API Key 自身额度不足	检查 Key 的额度限制
模型权限不足	检查账户分组和模型可用性
批量任务余额不足	停止队列，不要自动重试

排查余额不足时，保存 HTTP 状态码、error.code、模型名、业务 task_id 和 X-Oneapi-Request-Id。

失败不扣看最终结算结果：系统可能先预扣额度，模型请求失败后再返还。平台或上游失败、网络中断、没有生成结果的超时，最终不应扣费；如果模型已经成功返回有效结果，则通常正常计费。当前公开稳定的图片主路径按成功返回的图片结果结算：

情况	计费口径
HTTP 200 且返回图片	正常计费
HTTP 200 但 `data=[]`	当前图片价格模型按 0 张处理
上游多返回图片	当前主路径会把计费张数封顶到你请求的 `n`
`n > 1` 部分成功	按实际有效返回处理，业务侧应记录 `metadata.tapapi_partial`
成功生成但未下载图片	通常正常计费

更详细的规则见失败不扣规则。

生产请求可能经历这条链路：

请求进入 -> 预扣额度 -> 调用模型 -> 按实际结果结算
                         -> 失败则返还预扣

这意味着请求刚发出时看到的余额不一定是最终账单。对账时看最终用量记录、余额变化和业务请求记录。

这里要区分两类“退款”：

类型	含义
失败返还	API 请求失败后，系统把预扣额度返还到账户余额
现金退款	对已充值但未消费余额做支付渠道或人工退款

失败返还是计费系统的一部分；现金退款不是 API 自动流程。现金退款、异常扣费、重复支付、支付成功未到账等问题，请通过支持渠道提交工单处理。联系支持时带上：

更多对账字段见余额与用量。充值未到账或重复支付的提交模板见联系支持。