# 计费与额度

搞懂怎么计费,才能用得明白、花得放心。

---

## 按 token 计费

模型按 **token**(文字的最小计费单位)收费,粗略地说:1 个英文单词 ≈ 1 token,1~2 个汉字 ≈ 1 token。

一次调用分两部分计费:

| 类型 | 指什么 | 特点 |
|------|--------|------|
| **输入 token** | 你发给模型的内容(含历史对话、文件) | 较便宜 |
| **输出 token** | 模型返回的内容 | 通常比输入贵 3~5 倍 |
| **缓存写入** | 本次把可复用上下文写入缓存 | 可能单独计入 `cache_creation_tokens` / 5m / 1h 写入 |
| **缓存命中** | 复用之前处理过的内容 | 计入 `cache_read_tokens`,通常比正常输入更省 |

**一句话:说得越长、回得越长、轮次越多,token 越多,费用越高;命中缓存越多越省。**

---

## cost / total_cost / actual_cost 怎么看

控制台和 `/v1/usage` 里会同时出现几种成本口径:

| 字段 | 含义 | 用途 |
|------|------|------|
| `input_cost` / `output_cost` / `cache_*_cost` | 各类 token 按基础价格算出的分项成本 | 排查是哪类 token 花钱 |
| `cost` / `total_cost` | 倍率前的基础成本合计;部分聚合接口用 `cost` 命名 | 对照模型官方价、理解原始消耗 |
| `rate_multiplier` | 用户/分组倍率快照 | 解释基础成本如何变成实际扣费 |
| `actual_cost` | 实际从余额、订阅额度或 API Key quota 扣掉的金额 | 看账单、看剩余额度时以它为准 |

常见公式:

```text
actual_cost = total_cost × rate_multiplier
```

图片、视频、按次计费、分层价格(`billing_tier`)或服务层级(`service_tier`)场景可能不是单纯文本 token 价格；用量日志还可能记录 `billing_mode`、`image_count`、`image_size`、`image_output_tokens` 等字段。但页面展示仍遵循同一思路:**`total_cost`/`cost` 是基础口径,`actual_cost` 是最终扣费口径**。

真实扣费边界：用户余额、订阅额度、API Key quota、API Key 金额限速通常按 `actual_cost` 记账。图片请求在当前实现里可能不计入某些 Key quota 或金额限速，因此“图片扣费正常但 Key quota 没动”不一定是 bug。排查单笔媒体扣费时，优先看用量明细里的 `billing_tier`、`request_type`、图片尺寸/数量和输出 token 字段。

---

## 实际扣费 = 基础成本 × 分组/用户倍率

倍率有几层，含义不同：

- **分组倍率** 是当前分组的默认扣费倍率。
- **用户专属倍率** 命中时会覆盖分组默认倍率；没有专属规则时回到分组倍率。
- **媒体/搜索/音频价格** 可能使用独立价格或独立倍率，不一定套普通文本倍率。
- 图片、视频、搜索、音频等显式非文本计费以控制台展示、用量明细和当前分组价格为准。

---

## 非 token 计费模式

除了文本 token，部分能力会使用更细的 `billing_mode`：

| billing_mode | 场景 | 计费/排账提示 |
|---|---|---|
| `image` | `/v1/images/*`、Responses 图片桥接 | 看图片数量、尺寸 tier、输入/输出尺寸、图片输出 token/成本 |
| `video` | Grok-only `/v1/videos/*` | 按分辨率 tier + 秒数/视频数量；只适用于已开通视频的 Grok 分组 |
| `search` | Grok Web Search / tool search 计费 | 常按每 1k 次调用的显式价格折算 |
| `audio` | realtime / TTS / STT | 分别关注分钟数、字符数或小时数 |
| `per_request` | 按次或按上下文窗口分层的渠道 | 看请求次数、`billing_tier` 与渠道定价；找不到 tier 时可能回退默认按次价 |

更具体地看：

- `token`：可能包含输入、输出、缓存写、缓存读、5m/1h 缓存写、图片输入 token、图片输出 token、`service_tier=priority/flex`、长上下文倍率。
- `image`：通常按图片数量 × 1K/2K/4K 单价；分组价格优先，缺省时可能回落渠道/内置默认价。2K/4K 在默认估算中可能按 1K 的倍数折算。
- `video`：Grok-only，按分辨率 tier × 秒数 × 视频数；tier 支持 480p、720p、1080p、4K；缺 tier 时可能回落到最高已配置价格。
- `search`：按每 1k 次搜索/工具调用价格折算为单次；未配置或非正数时这段成本可为 0。
- `audio`：realtime 按分钟、TTS 按百万字符、STT 按小时；未配置或非正数时这段成本可为 0。

这些价格不是所有用户固定相同；会随当前分组、模型和站点价格策略变化。对账时以控制台可见价格、用量明细里的 `billing_mode` / `actual_cost` 和实际响应为准。

排账时不要只看 token 是否为 0。图片、视频、搜索、音频可能本来就不是按输入/输出 token 计费；应结合 `request_type`、`billing_mode`、媒体字段、`actual_cost` 和控制台分组/渠道定价判断。

---

倍率越低越省。不同[分组](#/api-key)对应不同上游与倍率,具体数值以控制台 [api.clomio.ai](https://api.clomio.ai) 实时显示为准。倍率的详细解释见 [常见问题](#/faq)。

---

## 套餐、余额、Key 额度的优先理解

你可以把额度分成三层:

| 层级 | 在哪里看 | 影响 |
|------|------|------|
| **账户余额** | 控制台余额、`/v1/usage` 的 `balance` | 没有订阅/Key 限制时,按 `actual_cost` 扣余额 |
| **套餐/订阅** | 控制台「订阅与余额」、`/subscriptions`、`/subscriptions/active`、`/subscriptions/progress`、`/subscriptions/summary`、`/v1/usage` 的 `subscription` | 可能有日/周/月美元额度与到期时间 |
| **API Key quota** | API Key 设置、`/v1/usage` 的 `quota` | 给单个 Key 设独立总额度,用完后这个 Key 不再可用 |
| **用户级平台额度** | 控制台平台额度、`/api/v1/user/platform-quotas` | 按平台限制 daily/weekly/monthly 美元用量,和 Key quota、订阅额度分开计算 |

建议给 Claude、Codex、Grok、脚本任务分别建 Key。这样即使同一个账户共享余额,也能用 Key quota 控制某个工具最多花多少。

`/user/platform-quotas` 返回 `platform_quotas` 数组,平台包括 `anthropic`、`openai`、`gemini`、`antigravity`、`kiro`、`grok`。每个平台可包含 `daily_limit_usd`、`weekly_limit_usd`、`monthly_limit_usd`、对应 `*_usage_usd`、`*_window_start` 和 `*_window_resets_at`;过期窗口在响应中会按当前口径 lazy zero,重置时间可能为 `null`。

请求前会先做资格检查：简易模式可能跳过计费检查；订阅分组优先检查订阅状态、过期时间和日/周/月订阅额度；余额模式要求余额大于 0 且不低于最小保留额；用户级 platform quota 只在余额模式生效，订阅模式豁免。API Key 金额限速、API Key RPM、用户/分组 RPM 则是额外限制，两种模式都可能遇到。

没有“逐请求冻结余额”的强冻结模型。通常是请求前检查余额/额度，成功记录用量后按 `request_id + api_key_id` 幂等扣费；并发很高时，预检和后扣之间可能发生竞争，系统会记录扣费结果并刷新/失效余额缓存。因此排查余额异常时要看 `request_id`、`actual_cost`、扣费时间和幂等记录，而不是只看请求开始时的余额。

---

## 并发、RPM 和金额限速

除了余额/套餐,还可能遇到三类限制。控制台若显示“平台额度”,其来源是 `/user/platform-quotas`,用于查看用户级平台限额与已用量:

| 限制 | 含义 | 常见现象 | 处理 |
|------|------|------|------|
| 并发(concurrency) | 同时在跑的请求数量上限 | 多个终端/脚本一起跑时排队或失败 | 降低并发,等前面的流结束 |
| RPM | 每分钟请求数上限;分组级优先,用户级兜底 | 短时间大量小请求返回 429 | 降低频率、合并请求 |
| 金额限速 | API Key 的 5h/1d/7d 美元窗口 | `/v1/usage` 返回 `rate_limits` 和 `reset_at` | 等窗口重置或调整 Key 限额 |

流式长任务在结束前会占用并发;图片/视频单次 `actual_cost` 可能高于普通文本,更容易撞到金额限速。Videos 端点当前只支持 Grok/xAI 路径,如果用错 Claude/Codex/OpenAI 分组,会先表现为路由/账号能力错误,不是余额计算问题。

### 常见计费报错与排查路径

| 报错 | 常见原因 | 排查路径 |
|---|---|---|
| `INSUFFICIENT_BALANCE` / `insufficient balance` | 余额小于等于 0 或低于 minimum reserve | 查用户余额、最小保留额、当前是否余额模式 |
| `BILLING_SERVICE_ERROR` | 余额/订阅缓存或计费服务检查失败，熔断中也可能返回 | 查 Redis、billing cache、计费服务日志 |
| `SUBSCRIPTION_INVALID` | 订阅非 active 或已过期 | 查订阅状态、到期时间、分组是否订阅型 |
| `DAILY_LIMIT_EXCEEDED` / `WEEKLY_LIMIT_EXCEEDED` / `MONTHLY_LIMIT_EXCEEDED` | 订阅日/周/月额度用尽 | 查订阅进度和分组额度 |
| `USER_PLATFORM_*_QUOTA_EXHAUSTED` | 用户级平台日/周/月额度用尽 | 查 `/user/platform-quotas`;注意订阅模式通常豁免 |
| `GROUP_RPM_EXCEEDED` / `USER_RPM_EXCEEDED` | 分组或用户 RPM 超限，专属 override 可能参与 | 查 group RPM、user RPM、user-group override |
| `pricing not found` / `no pricing available for model` | 动态/兜底价格都找不到 | 查渠道定价、模型映射后的 billing model |
| `rate_multiplier must be > 0` | 当前分组倍率配置异常 | 提交工单并附错误文本和 request_id |
| `image_rate_multiplier must be >= 0` | 图片独立倍率非法 | 修正图片计费配置 |

---

## 在哪看明细

控制台的「使用记录」能看到**每一次调用**的输入/输出 token、命中缓存、所用模型与扣费;错误请求页能看到面向用户脱敏后的失败详情。建议:

- 给不同项目/用途**建不同密钥**,账单更容易按 key 区分(见 [创建 API 密钥](#/api-key))
- 发现某次扣费异常,对照使用记录里的 token 数、`request_id`、`requested_model`、`upstream_model`、`billing_mode` 和 `actual_cost` 核查
- 图片排账重点看 `image_count`、`image_size`、`image_input_size`、`image_output_size`、`image_size_source`、`image_size_breakdown`、`image_output_tokens`、`image_output_cost`；文本 token 为 0 不代表一定免费
- 需要程序化查询时,用 `GET /v1/usage` 看当前 Key 的 `mode`、`quota`、`rate_limits[]`、`usage.today/total`、`model_stats`、`balance`、`subscription` 和 `usage.*.actual_cost`;控制台页面则通过 `/usage`、`/usage/stats`、`/usage/dashboard/*` 查询明细、趋势、模型统计和 Key 日用量

示例:

```bash
curl 'https://api.clomio.ai/v1/usage?start_date=2026-06-01&end_date=2026-06-29' \
  -H "Authorization: Bearer 你的密钥"
```

`mode: "quota_limited"` 表示 Key 自己配置了额度/限速;`mode: "unrestricted"` 表示这个 Key 没有独立限制,主要看账户余额或订阅额度。

---

## 省钱技巧

- **及时压缩上下文**:对话变长时用 `/compact` 压缩,能显著省 token(见 [Claude Code 使用手册](#/claude-usage))。
- **挑对模型**:简单任务用轻量/便宜的模型,复杂任务再上强模型,别一律用最贵的。见 [模型选择指南](#/models)。
- **善用缓存**:连续多轮同一上下文会命中缓存,比频繁开新对话更省。
- **别让它无谓地长篇输出**:需要简洁时,直接要求"简明回答"。

---

## 充值建议

- **先小额测试**:首次先充小额,验证速度、模型表现都满意,再按需追加。
- **按需充值**:用多少充多少,不必一次囤太多。
- 充值入口在控制台,支付后余额自动到账。开发票相关见 [常见问题](#/faq)。

---

> 想理解每个术语?[常见问题](#/faq) 里有倍率、扣费的通俗解释;选模型看 [模型选择指南](#/models)。