*更新日期: 2026-11-07*

# 计费与产物

币种固定 `CNY`。单价见 `GET /v1/models` 里的 `pricing`。

## 什么时候扣

| 能力 | 成功条件 | 计量 |
|------|----------|------|
| 对话 | 非流式成功返回；流式在 `[DONE]` 前写完 usage 且流正常结束 | 实际 `prompt_tokens` + `completion_tokens` |
| 生图 | 同步成功 | `data.length`（至少按 1 张） |
| 视频 | 状态 `completed`（转存后或直出上游地址） | 创建时的 `duration` 或 `seconds`（默认 5） |

失败、超时、策略拒绝不扣费。发请求前会按估算占用余额，失败或未完成时释放；长任务以终态实扣为准。没有自动退款接口。

分辨率 `size` 可能乘系数，以模型目录里的定价为准。对话按百万 token 分别设置输入、输出单价。

## `usage.cost`

成功响应里可能有：

```json
"cost": { "amount": "0.0021", "currency": "CNY" }
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `amount` | string | 本次扣费金额 |
| `currency` | string | 固定 `CNY` |

`cost` 是可选字段，有时不会返回。解析时按可选处理。

各能力 `usage` 其余字段：

| 能力 | 字段 |
|------|------|
| 对话 | `prompt_tokens` / `completion_tokens` / `total_tokens` |
| 生图 | `images_generated` |
| 视频 | `seconds`（仅 `completed` 时出现） |

## 查询余额

**GET** `/v1/balance`

无请求体，也没有查询参数。鉴权与其它 `/v1` 相同。不计费，不占对话 / 生图 / 生视频 RPM。余额为 0 或为负时，这个 GET 仍返回 200，不会变成 `insufficient_quota`。

返回的是**当前这把 Key 还能花的余额**，进行中的占用已经扣掉：

- 主账户 Key：主账户余额，`scope` 为 `tenant`
- 子账户 Key：该子账户额度，`scope` 为 `sub_account`，看不到主账户余额

```bash
curl $BASE/v1/balance \
  -H "Authorization: Bearer $MOMO_API_KEY"
```

主账户 Key：

```json
{
  "object": "balance",
  "balance": "12.50",
  "currency": "CNY",
  "scope": "tenant"
}
```

子账户 Key：

```json
{
  "object": "balance",
  "balance": "3.20",
  "currency": "CNY",
  "scope": "sub_account"
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `object` | string | 固定 `balance` |
| `balance` | string | 固定两位小数，多余位数向下取整 |
| `currency` | string | 固定 `CNY` |
| `scope` | string | `tenant` 或 `sub_account` |

`balance` 示例：`12.5` → `"12.50"`，`12.599` → `"12.59"`，`0.009` → `"0.00"`，`-1.231` → `"-1.24"`。

实际扣费仍按更高精度记账。`usage.cost.amount`、子账户划拨 `amount`、以及 `/v1/sub-accounts` 里的 `quota_balance` 都不是这个两位截断。所以实际余额还有 `0.009` 时，这里会显示 `"0.00"`，但生成请求仍按实际余额判断：大于 0 就不会因为显示成 `"0.00"` 被拒绝。

Key 无效、已吊销，或账户停用：`401` + `invalid_api_key`。

## 产物 URL

图（`url` 模式）和视频默认会先转存到平台存储，再返回稳定路径。URL 有保留期，过期后会失效。请当作短期可访问地址缓存，不要假设永久。上架视频模型可以关闭产物转存，此时视频 `url` 可能直接指向上游，有效期由上游决定；无法安全直出时会自动回退转存。

`b64_json` 图片仍会写入平台存储（响应返回 base64），对话文本不转存。Prompt 不会在响应里回显原文。

> **余额为 0**
>
> 不能再 `POST` 生成，但 `GET /v1/models`、`GET /v1/balance` 和 `GET /v1/tasks/{id}` 仍可用。

子账户有独立 `quota_balance`：用子账户 Key 调生成时只扣该额度；主账户可用 `/v1/sub-accounts` 划拨 / 收回，见 [子账户](/docs/sub-accounts)。
