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

# 计费与退款

> 余额、充值、预扣结算、失败返还和对账

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

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

## 余额是什么

| 项    | 说明                      |
| ---- | ----------------------- |
| 余额额度 | API 调用可消耗的账户额度          |
| 用量   | 已成功结算的模型消耗              |
| 充值记录 | 支付订单和到账记录               |
| 消费日志 | 每次 API 请求的模型、耗时、用量和请求标识 |

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

## 充值

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

```text theme={null}
选择充值金额
  -> 创建支付订单 pending
  -> 完成支付
  -> 支付回调确认
  -> 订单变为 success
  -> 余额增加
```

| 状态        | 含义            |
| --------- | ------------- |
| `pending` | 已创建订单，等待支付或回调 |
| `success` | 已确认到账，额度已增加   |
| `failed`  | 支付失败或通道返回失败   |
| `expired` | 订单过期          |

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

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

## 余额不足

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

```json theme={null}
{
  "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` |
| 成功生成但未下载图片           | 通常正常计费                                     |

更详细的规则见 [失败不扣规则](/production/failure-refund)。

## 预扣与结算

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

```text theme={null}
请求进入 -> 预扣额度 -> 调用模型 -> 按实际结果结算
                         -> 失败则返还预扣
```

| 结果         | 结算方式 |
| ---------- | ---- |
| 实际消耗 = 预扣  | 不再调整 |
| 实际消耗 > 预扣  | 补扣差额 |
| 实际消耗 \< 预扣 | 返还差额 |
| 请求失败且无有效结果 | 返还预扣 |

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

## 现金退款边界

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

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

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

联系支持时带上：

* 账户 ID 或登录邮箱
* 充值订单号或支付截图
* 请求时间和模型名
* 业务 `task_id`
* `X-Oneapi-Request-Id` 或控制台 `request_id`
* HTTP 状态码和 `error.code`
* 控制台用量截图或余额变化截图

更多对账字段见 [余额与用量](/account/balance-usage)。充值未到账或重复支付的提交模板见 [联系支持](/support/contact)。