时段用量 — Markdown 源文

以下为可直接复制或提供给 AI Agent 的 Markdown 原文。
> **AI Agents**: 索引 `/api/llms.txt` | 英文全文 `/api/llms-full-en.txt` | 中文全文 `/api/llms-full-zh.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`

# 时段用量

按时间窗汇总当前 API Key 的 token 用量（**不含金额**；金额见余额差或单请求对账）。

```
GET <BASE_URL>/v1/usage?start_time=<unix_sec>&end_time=<unix_sec>
```

## 认证

必需：`Authorization: Bearer <API_KEY>`。

## Query（必填）

| 参数 | 说明 |
|------|------|
| `start_time` | Unix **秒**（闭区间起点） |
| `end_time` | Unix **秒**（开区间终点，须大于 `start_time`） |

缺参或非法时返回 **400**，例如：`start_time must be a Unix timestamp in seconds`。

## 响应（200）

```json
{
  "start_time": 1730700000,
  "end_time": 1730786400,
  "requests": 12,
  "usage": {
    "input_tokens": 1000,
    "cached_write_tokens": 200,
    "cached_write_short_tokens": 150,
    "cached_write_long_tokens": 50,
    "cached_read_tokens": 80,
    "output_tokens": 300,
    "total_tokens": 1580
  }
}
```

| 字段 | 说明 |
|------|------|
| `requests` | 区间内请求次数 |
| `usage.input_tokens` | 纯输入（不含缓存读） |
| `usage.cached_read_tokens` | 缓存读取合计 |
| `usage.cached_write_tokens` | 缓存写入合计 |
| `usage.cached_write_short_tokens` / `cached_write_long_tokens` | 短/长 TTL 写缓存（x6 扩展） |
| `usage.output_tokens` / `total_tokens` | 输出 / 合计 |

范围仅含**当前 Key** 的明细。

## 相关

- [账户余额](./billing-balance.md)
- [单请求对账](./billing-requests.md)
- [模型定价](./model-pricing.md)