---
title: Prompt Caching 使用与计费
description: 在 1折AI 上使用 Claude Prompt Caching：怎么开、最小长度、怎么确认命中、命中后怎么计费，以及 Claude Code 的缓存行为。
---

Prompt Caching 让重复发送的长前缀（系统提示、工具定义、长文档、对话历史）只在第一次按写入计费，之后按读取计费。缓存读取的官方单价通常只有输入价的十分之一，我们在此基础上再乘 1.9 折。

## 先说结论

- **Claude Code 默认就开着缓存**，接上就生效。
- 自己写代码调用时，在要缓存的内容块上加 `cache_control`，用原生 `/v1/messages`。OpenAI 兼容接口目前不缓存。
- 判断有没有命中，只看回包 `usage.cache_read_input_tokens` 是不是大于 0。
- 缓存默认活 5 分钟，每次命中会重新计时。也可以用 `"ttl": "1h"` 写入 1 小时缓存，写入价更高。

## 怎么开

在 system、tools 或 messages 的内容块上加 `"cache_control": {"type": "ephemeral"}`，这个块及它之前的内容会被缓存。一次请求最多 4 个缓存断点。

```bash
curl https://1zheai.com/v1/messages \
  -H "x-api-key: $ONEZHE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 256,
    "system": [
      {
        "type": "text",
        "text": "这里放一段很长、每次都一样的内容：项目说明、代码规范、参考文档……",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [{"role": "user", "content": "根据上面的规范，审查这段代码：..."}]
  }'
```

<Note>

被缓存的前缀太短时，请求照常处理，只是不缓存，也不会报错。最小长度因模型而异，见下表。

</Note>

## 最小可缓存长度

以下来自 [Anthropic 官方文档](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)（2026-10-14）：

| 最小 token 数 | 模型 |
|---|---|
| 512 | Fable 5.1、Fable 5、Opus 5.5、Opus 5、Sonnet 5.5、Haiku 5.5 |
| 1,024 | Opus 4.8、Sonnet 5、Sonnet 4.6、Sonnet 4.5 |
| 2,048 | Opus 4.7 |
| 4,096 | Opus 4.6、Opus 4.5、Haiku 4.5 |

## 确认命中

同样的请求连发两次（间隔不超过 5 分钟），对比两次的 `usage`。下面是 2026-10-15 用 `claude-sonnet-5-5` 实测的结果，system 里放了约 1.8 万 token 的固定文本：

<CodeGroup>
```json title="第一次：写入缓存"
{
  "input_tokens": 23,
  "cache_creation_input_tokens": 17920,
  "cache_read_input_tokens": 0,
  "cache_creation": {"ephemeral_5m_input_tokens": 17920, "ephemeral_1h_input_tokens": 0},
  "output_tokens": 4
}
```
```json title="第二次：命中缓存"
{
  "input_tokens": 23,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 17920,
  "cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0},
  "output_tokens": 4
}
```
</CodeGroup>

第二次 `cache_read_input_tokens` 大于 0 就说明缓存在被读取。每一笔的缓存写入和读取 token 也会出现在[调用日志](/docs/usage-logs/)的 Token 列里，读取记为「缓存↓」，写入记为「↑」。

## 怎么计费

| 类型 | 官方单价 | 1折AI 单价 |
|---|---|---|
| 缓存写入（5 分钟） | 输入价 × 1.25 | 官方价 × 1.9 折 |
| 缓存写入（1 小时） | 输入价 × 2 | 官方价 × 1.9 折 |
| 缓存读取 | 输入价 × 0.1（Opus 5.5、Sonnet 5.5 为 0.05，Fable 5.1 为 0.025） | 官方价 × 1.9 折 |

写入比普通输入贵 25%，所以只缓存会被重复用到的内容。一段前缀只要被读到一次就已经划算：写一次加读一次是 1.25 + 0.1 = 1.35 倍输入价，不缓存发两次是 2 倍。完整算例见[价格与计费](/docs/pricing-explained/)。

### 1 小时缓存

在 `cache_control` 里加 `"ttl": "1h"`，缓存会保留 1 小时，适合间隔超过 5 分钟、但仍会反复用到的前缀：

```json
"cache_control": {"type": "ephemeral", "ttl": "1h"}
```

写入按输入价的 2 倍计，读取和 5 分钟缓存一样。回包里写入的 token 出现在 `cache_creation.ephemeral_1h_input_tokens`。2026-10-15 用同一段 3,144 token 的前缀各写入一次，按调用日志里的费用复算，写入部分分别正好是输入价的 1.25 倍和 2 倍。只有间隔经常超过 5 分钟时，1 小时缓存才划算。

## Claude Code 的缓存

Claude Code 会自动给系统提示、工具定义和对话历史打缓存断点，[官方说明在这里](https://code.claude.com/docs/zh-CN/prompt-caching)。想让它命中得更好：

- 一个会话里连续干活，别中途长时间停下。缓存 5 分钟没被用到就过期了。
- 同一个会话里的后续请求会读缓存。2026-10-15 实测，一次两轮的 Claude Code 任务，第二轮缓存读取 31,440 token、写入 115 token。新开一个会话时，第一轮可能要重新写入整段前缀（实测约 3 万 token），这一笔会比后面的贵。
- 少在会话中途改 `CLAUDE.md`、切换 MCP 服务器或换模型，这些都会让前缀变化。
- 不要设置 `DISABLE_PROMPT_CACHING=1`，这个环境变量会关掉所有模型的缓存。

## OpenAI 兼容接口能用缓存吗

目前不能。2026-10-15 实测，在 `/v1/chat/completions` 的 system 消息里放约 3,100 token 的固定文本，连发两次，不管内容块上加不加 `cache_control`，两次的 `usage` 都是：

```json
{"prompt_tokens": 3167, "completion_tokens": 4, "total_tokens": 3171}
```

没有 `prompt_tokens_details.cached_tokens`，调用日志里的缓存读取和写入也都是 0，整段按输入价计费。需要缓存的场景请用 `/v1/messages`（Anthropic SDK 或 Claude Code）。

## 常见问题

<AccordionGroup>
<Accordion title="为什么一直只有 cache_creation，没有 cache_read？">

缓存写进去了，但下一次没读到。按顺序排查：两次请求是否超过 5 分钟；断点前的内容是否一字不差（时间戳、随机 ID 放进 system 会让每次都不同）；是否换了模型；前缀是否达到上面的最小长度。

</Accordion>
<Accordion title="缓存命中率能看吗？">

每一笔的缓存读取、缓存写入 token 都在调用日志里，可以自己算：缓存读取 ÷（输入 + 缓存写入 + 缓存读取）。

</Accordion>
</AccordionGroup>