# 用量与调用日志

在控制台查看 Token 汇总、单次请求详情、调用状态和费用相关账本记录。

## 控制台入口 [#控制台入口]

登录后从侧边栏进入：

- **使用 → 用量**：按日查看输入 Token、输出 Token 和金额汇总，可选择近 7、30 或 90 天。
- **使用 → 调用日志**：查看单次调用的时间、模型、状态、输入/输出 Token 和耗时。前端当前默认加载第一页 50 条记录。
- **财务 → 收支明细**：查看 元交易类型、余额变化和备注。

用量、调用日志和账本流水用途不同。用量页按时间聚合，日志按请求记录，流水反映实际收支结算。出现差异时用时间、模型和状态定位具体请求，再核对流水，不要用一个汇总字段替代最终账单。

## 可用的业务查询接口 [#可用的业务查询接口]

这些是同源业务接口，不是模型调用的 `/v1` API。需要已登录控制台会话；不要在模型 SDK 中使用控制台令牌。

| 请求 | 用途 | 关键参数 |
| --- | --- | --- |
| `GET /api/v1/usage/daily` | 日用量汇总 | `days`，默认 30，接受 1–365 |
| `GET /api/v1/usage/monthly` | 月用量汇总 | `days`，默认 30 |
| `GET /api/v1/usage/detail` | 分页用量明细 | `start_date`、`end_date`、`api_key_id`、`page`、`page_size` |
| `GET /api/v1/gcoin/balance` | 元余额和汇总 | 无 |
| `GET /api/v1/gcoin/transactions` | 元交易流水 | `page`、`page_size`，默认 1 / 20 |

用量明细的 `page_size` 范围为 1–100。当前明细 handler 不使用 `model_code` 作为服务端筛选条件；即使传入也会被忽略。需要核对模型时，先按日期/API Key 分页读取，再按响应 `records`（或明细数组）中的模型字段筛选或核对。日汇总超出合法 `days` 范围时服务端使用默认值；月汇总参数不要超出所需查询范围。

使用控制台已认证会话查询某用户的明细时，示例结构如下。`<控制台登录会话>` 是说明用占位符，不要将真实凭据粘贴进文档或 shell 历史：

```bash
curl -sS "https://api.gfw.net/api/v1/usage/detail?page=1&page_size=50" \
  -H "Authorization: Bearer <控制台登录会话>"
```

控制台业务响应为业务 JSON 包装，分页数据通过 `data` 中的分页结构返回；具体字段以当前响应为准。上面未伪造实际日志或余额数据。

## 用量字段的解释 [#用量字段的解释]

调用日志可能提供 `model`、`status`、`prompt_tokens`、`completion_tokens` 和 `latency_ms`。日汇总可能提供日期、模型、输入/输出 Token 和金额字段。字段是否存在取决于记录类型和接口版本。

对话模型的 Token 费用受输入/输出价格、缓存定价、阶梯价格和账户用户组折扣影响；媒体模型可能采用模型对应的其他计量规则。响应中的 Token 统计有助于解释请求用量，但最终 元扣费或退款应以账户流水为准。

## 核对单次请求 [#核对单次请求]

1. 在 **调用日志** 按时间和模型找到对应请求，记下状态、输入/输出 Token 和耗时。
2. 在 **用量** 选择覆盖该调用日期的范围，核对模型维度的汇总。
3. 在 **财务 → 收支明细** 查找相邻时间的 API 调用、预扣费或退款记录。
4. 如果有差额，保留请求时间、模型代码、状态和账单流水备注，联系支持；共享前删除 API Key、提示词和个人数据。

请求失败不代表所有情况都会立即出现相同的退款表现。判断是否扣费时应检查实际结算和退款流水，而不是只依据 HTTP 状态或 SDK 异常。

## 常见查询问题 [#常见查询问题]

- **没有记录**：确认页面账户、日期范围和 API Key 是否正确，并留意请求是否发往模型 API 域名。
- **HTTP 成功但费用未显示**：汇总和账本记录可能不同步或采用不同粒度；稍后重查，再以实际流水为准。
- **失败请求有扣费疑问**：使用请求时间和模型定位调用，检查是否有预扣费及后续退款流水。
- **找不到模型**：按返回明细记录中的模型字段核对对外 `model_code`，不要把供应商上游模型标识当作服务端筛选参数。

## 相关链接 [#相关链接]

- [计费与充值](/docs/billing)
- [认证与 API Key](/docs/authentication)
- [模型目录](/models)
- [错误处理](/docs/errors)