# 用量明细

想知道钱花在哪、每次调用扣了多少，就看用量明细（使用记录）。这里能看到请求模型、上游模型、缓存、错误、扣费和 CSV 导出。

---

## 在哪看

控制台 [api.clomio.ai](https://api.clomio.ai) →「**用量明细**」/「**使用记录**」。仪表盘首页也有用量概览和**模型用量统计**。这些数据来自 `/usage/dashboard/stats`、`/usage/dashboard/trend`、`/usage/dashboard/models` 和批量 Key 统计接口。

---

## 每条记录有什么

成功计费请求通常会留用量记录；部分鉴权、路由或早期失败可能只有错误记录。每条用量记录通常包含：

| 字段 | 含义 |
|------|------|
| 时间 / Request ID | 调用发生的时刻和排障用 `request_id` |
| 请求模型 | 你在请求里传入的模型名（`requested_model`） |
| 实际/上游模型 | 模型映射后真正发给上游的模型（`upstream_model`），详情中可能展示映射链 |
| 密钥 / 分组 | 哪个 Key、哪个分组发起的 |
| 输入 token | 你发出去的内容（含历史、文件） |
| 输出 token | 模型返回的内容 |
| 缓存写入 / 命中缓存 | 写入缓存与复用缓存的 token，命中缓存通常更省钱 |
| `cost` / `total_cost` | 标准费用口径：按模型基础价格算出的费用 |
| `actual_cost` | 用户实际扣费口径：标准费用乘分组/用户倍率后的结果 |
| 耗时 | `duration_ms`、首 token 时间 `first_token_ms`，流式/慢请求排查很有用 |
| 端点 | `inbound_endpoint` 与 `upstream_endpoint`，用于确认客户端 Base URL/端点是否写错 |
| 错误信息 | 失败请求的状态码、错误类型或失败原因（若有） |

> 对用户对账，优先看 `actual_cost`；`cost` / `total_cost` 更适合理解基础模型成本或平台内部口径。

---

## 扣费口径：cost / total_cost vs actual_cost

- **`cost` / `total_cost`**：标准费用。通常等于输入、输出、缓存写入、缓存读取等分项费用相加，不含用户分组倍率。
- **`actual_cost`**：实际扣费。会应用 Key 所在分组倍率、用户专属倍率等用户侧规则，是余额/订阅额度实际减少的金额。

如果你看到 `total_cost` 和 `actual_cost` 不同，通常是因为分组倍率、用户专属倍率或订阅/余额计费规则不同。

---

## Dashboard、趋势和模型统计

用户首页的仪表盘不是只看余额,还会汇总:

- **总览卡片**:`total_api_keys`、`active_api_keys`、累计/今日请求数、输入/输出/cache token、`total_actual_cost`、`today_actual_cost`、平均响应耗时、近 5 分钟 `rpm`/`tpm`。
- **平台拆分**:`by_platform` 会按平台展示总请求、总 token、累计/今日实际扣费。
- **趋势图**:`/usage/dashboard/trend` 支持 `start_date`、`end_date` 和 `granularity=day|hour`,每个点包含 requests、各类 token、`cost`、`actual_cost`。
- **模型统计**:`/usage/dashboard/models` 按模型聚合 requests、token、cache、`cost`、`actual_cost`。
- **Key 日用量**:API Key 列表/详情可调用 `/user/api-keys/{id}/usage/daily`,按天返回某个 Key 的 requests、token、cache、`cost`、`actual_cost`;批量卡片使用 `/usage/dashboard/api-keys-usage` 返回每个 Key 的今日/累计 `actual_cost`。

趋势和模型统计默认查最近 7 天,`end_date` 按包含当天处理；dashboard 日期解析失败时会回退默认范围,不一定直接报 400。Key 日用量的 `days` 默认 30,允许 1-90；访问不属于自己的 Key 会返回无权限。

---

## 缓存、模型映射与错误请求

- **缓存**：`cache_read_tokens` 表示命中的缓存 token，`cache_creation_tokens` 表示本次写入缓存的 token。命中缓存时输入上下文可能很长，但实际费用会低于全量重算。
- **模型映射**：列表里可能同时展示「请求模型」和「上游模型」。例如你请求一个兼容别名，网关根据渠道/平台/分组规则映射到上游真实模型；排查模型表现时要看上游模型。
- **错误请求**：失败请求也可能出现在用量明细里。一般不会产生输出 token；是否有费用取决于请求是否已到达上游并产生可计费用量。排障时请提供 Request ID。

错误请求页来自 `/usage/errors` 与 `/usage/errors/{id}`。它是面向用户的脱敏视图；如果站点未开放该视图会返回 `Error requests view is disabled`，服务暂不可用时会返回 `Ops service not available`。列表 `page_size` 最大 100。接口支持按 `start_date`、`end_date`、`timezone`、`model`、`status_code`、`category`、`api_key_id` 过滤；当前页面 UI 的筛选项以实际版本为准，例如 status code 可能只在接口层可用。

| 字段 | 排查价值 |
|------|----------|
| `id` / `created_at` | 错误记录编号和发生时间;提交工单时可附这个 `id` |
| `model` / `inbound_endpoint` | 判断模型名或 Claude/Codex/Grok 端点是否写错 |
| `status_code` | 区分 400 参数错误、401/403 鉴权/额度、429 限速、5xx 上游/平台异常 |
| `category` | 稳定分类码: `auth`、`quota`、`rate_limit`、`invalid_request`、`upstream`、`service_unavailable`、`internal`、`cyber`、`other` |
| `platform` / `key_name` / `key_deleted` | 判断 Key 所属平台、是否已删除或用错 Key |
| `message` / `error_body` / `upstream_status_code` | 详情页会展示标准化错误描述、上游错误体和上游状态码（如有） |

注意:用户侧错误请求详情不会暴露 `client_ip`、`user_agent`、账号、Key 前缀、上游端点、用户邮箱等内部字段。要追完整链路,仍优先提供用量记录里的 `request_id`;若只有错误请求页,提供错误 `id`、时间、模型、Key 名称即可。

如果是流式请求,HTTP 状态码可能已经是 200,但 SSE 里随后出现 `response.failed` 或 `response.cancelled`;这类问题要看错误详情里的事件文本和 Request ID,不能只看 HTTP 200。

### 用量记录与错误详情的区别

排障时经常同时看到「用量记录」和「错误记录」。两者用途不同：

| 页面口径 | 主要回答 | 常见字段 |
|---|---|---|
| 用量明细 | 这次请求是否计费、按哪个模型/Key/分组、用了多少 token 或媒体量、扣了多少 | `request_id`、`requested_model`、`upstream_model`、token、cache、`billing_type`、`billing_mode`、`request_type`、`actual_cost`、WS/image/video 字段 |
| 错误请求 | 失败发生在哪个阶段、错误来源、上游返回了什么、是否有关联错误 | 错误分类、状态码、上游状态、错误描述和脱敏后的错误体 |

用量明细是计费/用量事实；错误请求是诊断视图。成功请求也可能伴随一条 `Recovered upstream error ...` 类型的上游容灾记录：它说明中间某次上游调用失败过，但最终请求可能已经恢复成功，不一定代表用户最终失败。

用户侧错误详情是脱敏视图，主要展示错误体、上游状态和标准化摘要；不要期待它能还原完整原始请求体、全部请求头、账号、Key 前缀或内部上游 URL。要闭环排查，优先提供 `request_id`，其次才是错误记录 `id` 与发生时间。

---

### request_id / usage errors / 工单闭环

1. **先找 `request_id`**:优先从客户端响应头、错误体、控制台用量详情里复制 `request_id` 或 `x-request-id`;它能把网关日志、用量记录和上游响应串起来。
2. **再看错误请求页**:如果本次失败没有完整用量记录,切到错误请求页,用时间范围、模型、状态码、分类、Key 过滤,打开详情复制错误 `id`、`message`、`error_body`、`upstream_status_code`。
3. **最后提工单**:在工单中写明 `request_id`/错误 `id`、发生时间和时区、Base URL、端点、模型、Key 名称/分组、是否流式、是否换过线路;把终端 `curl -i` 输出、工具报错截图、用量/错误详情截图作为私有附件上传。

如果没有 `request_id`,不要只发“失败了”:至少提供精确时间范围、Key 名称、模型、端点、完整错误文本和截图。

---

## 渠道监控和公告如何辅助排查

如果“同一个 Key 突然变慢/失败”,先不要只看余额。控制台如果开放了渠道监控,`/channel-monitors` 会列出可见线路的 `primary_status`、`primary_latency_ms`、`primary_ping_latency_ms`、`availability_7d`、`extra_models` 和近期 `timeline`;点详情后 `/channel-monitors/{id}/status` 会显示各模型 7/15/30 天可用率与平均延迟。

渠道监控功能关闭时,列表会返回空 `items: []`,详情可能返回 `CHANNEL_MONITOR_NOT_FOUND`;这不等于某个模型必然故障,只是当前用户不可见或功能未开放。维护、模型切换或价格变动通常会通过 `/announcements` 公告发布并可标记已读。公告列表支持 `read_status=all|read|unread`,也兼容 `unread_only=true|1|yes|y|on`;公告 ID 错误会返回 `Invalid announcement ID`。

---

## 筛选与 CSV

- **按密钥/模型/时间筛选**：快速定位某段时间、某个项目的消耗。用户列表接口支持 `api_key_id`、`model`、`request_type`、`stream`、`billing_type`、`start_date`、`end_date`、`timezone`、`sort_by`、`sort_order` 等参数。
- **按请求状态筛选**：区分成功、失败、取消或超时请求；布尔值和日期格式错误会返回明确错误,如 `Invalid stream value, use true or false`、`Invalid start_date format, use YYYY-MM-DD`。
- **导出 CSV**：在页面使用导出功能，把当前筛选条件下的明细下载到本地，适合团队报销、项目分摊或二次分析。CSV 字段包括 Time、API Key Name、Model、Reasoning Effort、Inbound Endpoint、Type、Billing Mode、Token、Rate Multiplier、Billed Cost、Original Cost、First Token、Duration,并会做防公式注入处理。
- **给不同项目建不同密钥**：账单天然按 Key 区分，便于分摊成本（建密钥见 [创建 API 密钥](#/api-key)）。

导出前建议先固定时间范围和 Key 过滤条件。当前 CSV 没有单独的服务端导出任务；前端会按当前筛选条件循环调用 `/usage`（通常每页 100 条）,在浏览器本地生成 Blob 下载。如果数据量太大导致失败,缩短时间范围或增加 Key/模型筛选后重试。

`request_type` 是比旧 `stream=true/false` 更稳定的分类。当前前端识别这些值:

| request_type | 含义 |
|---|---|
| `sync` | 普通非流式文本请求 |
| `stream` | SSE 流式文本请求 |
| `ws_v2` | Responses WebSocket v2 / Codex WS 请求 |
| `image` | 原生 Images API 请求 |
| `image_web_bridge` | Web/Responses 图片桥接请求 |
| `video` | Grok Videos 请求 |
| `cyber` | 上游/网关安全策略相关记录,可能与原始 `stream` 维度正交 |
| `unknown` | 旧数据或无法归类的请求 |

筛选视频或图片用 `request_type=video|image|image_web_bridge` 更准确；旧 `stream=false` 不能区分普通同步文本、图片和视频。若同时传 `request_type` 和旧 `stream` 参数，后端以 `request_type` 为准；只有没传 `request_type` 时才用 `stream=true|false` 作为兼容筛选。非法 `request_type` 会返回 `invalid request_type, allowed values: unknown, sync, stream, ws_v2, image, image_web_bridge, cyber, video`。

`billing_type` 用来区分扣费来源：`0` 表示钱包余额扣费，`1` 表示订阅/套餐扣费。`billing_mode` 是更细的计费模式；空值通常按 token 计费理解。

| billing_mode | 含义 | 对账重点 |
|---|---|---|
| `token` | 常规 token 区间计费 | 输入、输出、cache token 与模型价格 |
| `per_request` | 按次/按上下文窗口分层 | 请求次数、`billing_tier`、模型/渠道定价 |
| `image` | 图片计费 | `image_count`、`image_size`、输入/输出尺寸、图片输出 token/成本 |
| `video` | Grok Videos 计费 | 分辨率 tier、duration/seconds、视频数量 |
| `search` | 搜索/工具调用计费 | 通常按每 1k calls 的价格折算 |
| `audio` | 音频计费 | realtime 分钟、TTS 字符数、STT 小时等模式 |

注意：展示/理解成本时，空 `billing_mode` 通常可按 token 口径理解；筛选历史数据时以页面实际结果为准。

图片/视频排账时优先看 `request_type`、`billing_mode`、`image_count`、`image_size`、`image_input_size`、`image_output_size`、`image_size_source`、`image_size_breakdown`、`image_output_tokens`、`image_output_cost` 等字段。`media_type` 可能作为兼容输出字段出现，但当前不是可靠持久化排账字段，通常不要把它作为唯一筛选或对账依据。Codex/Responses WS 排障时重点看 `openai_ws_mode`、`openai_ws_profile`、`openai_ws_conn_reused`、`service_tier`、`reasoning_effort` 和 `billed_by_higher_priced_upstream`。

---

## 用 API 自助对账

除了网页，也可以用 `GET /v1/usage` 拉取当前密钥的用量数据，接进自己的脚本/看板：

```bash
curl https://api.clomio.ai/v1/usage \
  -H "Authorization: Bearer 你的密钥"
```

`GET /v1/usage` 有两种返回模式：

| 模式 | 何时出现 | 你会看到什么 |
|------|----------|--------------|
| `quota_limited` | 当前 API Key 设置了 `quota`、有效期或 5h/1d/7d 限速 | Key 总额度、剩余额度、过期时间、各窗口用量和重置时间 |
| `unrestricted` | Key 本身未设置额度/限速 | 账户余额或订阅信息、今日/累计用量、模型统计、每日用量 |

两种模式都会尽量返回 token、缓存和 `actual_cost` 口径，便于和控制台页面对账。

---

> 想省钱？见 [计费与额度 · 省钱技巧](#/billing)；余额/充值见 [订阅与余额](#/console-billing)。