端点 GET /v1/billing/requests/{request_id}
根据请求 ID 查询一次模型调用产生的 Token 用量和最终费用。
请求
鉴权使用 Authorization: Bearer sk-xxxxxx。
参数
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
request_id | 路径 | UUID | 是 | 调用模型时响应头 x-request-id 的值 |
每次模型调用的响应头都带 x-request-id（另有 x-trace-id，仅用于排查问题，不能用于查询账单）。
响应
json
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"created_at": 1784081234,
"model": "gpt-5.4",
"usage": {
"input_tokens": 1000,
"output_tokens": 500,
"cached_write_tokens": 800,
"cached_read_tokens": 200,
"total_tokens": 2500
},
"amount": { "value": "0.012680", "currency": "USD" }
}| 字段 | 说明 |
|---|---|
request_id | 请求 ID |
created_at | 请求时间（Unix 秒） |
model | 调用的模型 ID |
usage.input_tokens | 未命中缓存的输入 Token 数 |
usage.output_tokens | 模型生成的输出 Token 数 |
usage.cached_write_tokens | 写入提示词缓存的 Token 数 |
usage.cached_read_tokens | 从提示词缓存读取的 Token 数 |
usage.total_tokens | 上述 Token 数量之和 |
amount | 本次请求最终费用，value 为字符串金额，currency 为币种 |
不适用或上游未提供的 Token 类型返回 0。
示例
bash
curl "https://caapi.top/v1/billing/requests/550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer sk-xxxxxx"错误
账单类接口的错误结构为 error.code + error.message：
| HTTP 状态 | error.code | 触发条件 |
|---|---|---|
| 400 | invalid_request | request_id 不是合法的 UUID |
| 404 | not_found | 请求记录不存在，或当前 API Key 无权访问该记录 |