端点 GET /v1/usage
查询当前鉴权 API Key 在指定时间范围内的 Token 用量汇总。
请求
鉴权使用 Authorization: Bearer sk-xxxxxx。
参数
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
start_time | 查询串 | integer | 是 | 开始时间（Unix 秒），包含该时间点 |
end_time | 查询串 | integer | 是 | 结束时间（Unix 秒），不包含该时间点 |
时间范围最长 90 天，超过返回 400 invalid_request。
响应
json
{
"start_time": 1784044800,
"end_time": 1784131200,
"usage": {
"input_tokens": 120000,
"output_tokens": 30000,
"cached_write_tokens": 10000,
"cached_read_tokens": 80000,
"total_tokens": 240000
},
"requests": 86
}| 字段 | 说明 |
|---|---|
usage.input_tokens | 未命中缓存的输入 Token 数 |
usage.output_tokens | 模型生成的输出 Token 数 |
usage.cached_write_tokens | 写入提示词缓存的 Token 数 |
usage.cached_read_tokens | 从提示词缓存读取的 Token 数 |
usage.total_tokens | 上述 Token 数量之和 |
requests | 范围内的请求次数 |
对账时请与 查询账单汇总 使用相同的 start_time 与 end_time，以保证口径一致。
示例
bash
curl "https://caapi.top/v1/usage?start_time=1784044800&end_time=1784131200" \
-H "Authorization: Bearer sk-xxxxxx"错误
| HTTP 状态 | error.code | 触发条件 |
|---|---|---|
| 400 | invalid_request | 参数无效，例如 end_time 不大于 start_time，或范围超过 90 天 |