Prompt Caching 使用与计费

在 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 个缓存断点。

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

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

最小可缓存长度

以下来自 Anthropic 官方文档（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 的固定文本：

第一次：写入缓存
第二次：命中缓存

{
  "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
}

{
  "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
}

第二次 cache_read_input_tokens 大于 0 就说明缓存在被读取。每一笔的缓存写入和读取 token 也会出现在调用日志的 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 倍。完整算例见价格与计费。

1 小时缓存

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

1
"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 会自动给系统提示、工具定义和对话历史打缓存断点，官方说明在这里。想让它命中得更好：

一个会话里连续干活，别中途长时间停下。缓存 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 都是：

1
{"prompt_tokens": 3167, "completion_tokens": 4, "total_tokens": 3171}

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

常见问题

为什么一直只有 cache_creation，没有 cache_read？

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

缓存命中率能看吗？

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