Source: https://wiki.niceai.dev/guide/tech/token-usage-explained

# 一次 API 调用到底用了多少 token？

看返回里的 `usage` 字段就知道：它会分别列出**输入 token**（你发过去的所有内容）、**输出 token**（模型生成的内容），有的还会列出**缓存命中的输入**和**推理过程消耗的 token**。按量计费的服务基本都按这几个数字分别计价。

## OpenAI 兼容格式

```json
"usage": {
  "prompt_tokens": 1200,
  "completion_tokens": 300,
  "total_tokens": 1500,
  "prompt_tokens_details": {"cached_tokens": 1024},
  "completion_tokens_details": {"reasoning_tokens": 128}
}
```

| 字段 | 含义 |
| --- | --- |
| `prompt_tokens` | 输入 token，包括系统提示、历史消息、工具定义、图片等 |
| `completion_tokens` | 输出 token，推理模型的思考过程也算在里面 |
| `cached_tokens` | 输入中命中缓存的部分 |
| `reasoning_tokens` | 输出中用于“思考”的部分，通常不会显示给你，但会计费 |

## Anthropic 格式

```json
"usage": {
  "input_tokens": 50,
  "cache_creation_input_tokens": 2000,
  "cache_read_input_tokens": 8000,
  "output_tokens": 300
}
```

| 字段 | 含义 |
| --- | --- |
| `input_tokens` | 没有命中缓存、也没有写入缓存的输入 |
| `cache_creation_input_tokens` | 本次写入缓存的输入 |
| `cache_read_input_tokens` | 本次从缓存读取的输入 |
| `output_tokens` | 输出 token |

注意 Anthropic 的 `input_tokens` **不包含**缓存部分，总输入要把三项加起来。上面两段 JSON 里的数字只是示意。

## 为什么 token 会越用越多

- **多轮对话**：接口不记忆上下文，每一轮都要把历史全部重发，第 10 轮的输入包含前 9 轮的所有内容。
- **Agent 工具**：Claude Code、Cursor Agent 这类工具每次请求都带上很长的系统提示和工具定义，还会把读过的文件、命令输出塞进上下文。详见 [Claude Code 为什么输入 token 多](https://wiki.niceai.dev/guide/tech/claude-code-input-tokens)。
- **推理模型**：思考过程会产生大量输出 token，问题越难思考越长。
- **图片**：图片按尺寸折算成 token，大图并不便宜。

## 降低消耗的办法

1. **利用提示词缓存**：把固定不变的内容放在最前面，让后续请求命中缓存，见 [提示词缓存是怎么省钱的](https://wiki.niceai.dev/guide/tech/prompt-caching)。
2. **控制历史长度**：长对话定期总结或截断旧消息；Agent 工具里适时开新会话或压缩上下文。
3. **按任务选模型**：翻译、分类这类简单任务用轻量模型，复杂推理再用大模型。
4. **限制输出**：设置合理的 `max_tokens`，要求简洁回答。
5. **压缩图片**：识别截图文字时把图片缩小到够看清即可。

## 延伸阅读

- [提示词缓存是怎么省钱的](https://wiki.niceai.dev/guide/tech/prompt-caching)
- [Claude Code 为什么输入 token 多](https://wiki.niceai.dev/guide/tech/claude-code-input-tokens)
- [Chat Completions 接口](https://wiki.niceai.dev/guide/api/chat-completions)
