Claude API 提示词缓存：工作原理与实际节省

提示词缓存对 Claude API 账单的影响

提示词缓存让 Anthropic 存储请求中可复用的前缀——也就是你设置的断点之前的所有内容——之后携带相同前缀的请求直接从缓存读取，不再重新处理。缓存读取的价格只有全新输入 token 的一个零头，而缓存写入比输入价略高一点。如果你的应用反复发送同一段大上下文（系统提示词、代码库快照、文档集），缓存能把每次调用中最贵的部分变成最便宜的部分。

缓存写入和缓存读取在 API 响应和账单中作为独立的 token 桶分别计量，所以缓存到底省了多少一目了然。响应本身没有任何变化——同样的模型、同样的质量、同样的流式行为。

另见： 如何节省 Claude API token

在请求中放置 cache_control 断点

当 cache_control 缺失或全部为 null 时，Claude 请求会自动获得五分钟的提示词缓存。只有需要精确控制原生 Messages 断点时，才需要在内容块上添加 cache_control。标记之前的所有内容——系统提示词、工具定义、更早的消息——都会成为可缓存的前缀。下面是一个发往 apiToken.sale 的真实请求，缓存了系统提示词：

curl https://router.apitoken.sale/v1/messages \
  -H "x-api-key: sk-pool-•••" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are a senior reviewer... (long stable instructions)",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [{"role": "user", "content": "Review this diff: ..."}]
  }'

• 每个请求最多可以设置四个 cache_control 断点——常见的布局是工具之后一个、系统提示词之后一个、大参考文档之后一个。
• 缓存从第一个 token 开始做精确的前缀匹配。系统提示词里改动一个字符，其后的内容就全部 miss。
• 只有达到最小可缓存尺寸的块才会被存储——Sonnet 和 Opus 模型约为 1,024 token，Haiku 更高。太短的提示词会静默跳过缓存。
• 易变内容（时间戳、用户特定数据）要放在最后一个断点之后，绝不要放进前缀里。

在 OpenAI 兼容客户端中使用 Claude 缓存

Claude 模型在原生 Messages、Chat Completions 和 Responses 中使用同一条提示词缓存路径。在 OpenAI 兼容接口上，请把 cache_control 作为请求顶层的自定义扩展传入。不要把 Anthropic 断点放进 OpenAI message 或 input part，因为这些部分会被转换。未传此扩展时，apiToken.sale 会在转换后自动添加五分钟缓存。

• 一小时 TTL：传入 cache_control: {type: "ephemeral", ttl: "1h"}，并发送 anthropic-beta: extended-cache-ttl-2025-04-11 请求头。
• 在 OpenAI SDK 中，通过 extra_body 传扩展，通过 extra_headers 传 beta 请求头。
• Chat Completions 的命中量位于 usage.prompt_tokens_details.cached_tokens。
• Responses 的命中量位于 usage.input_tokens_details.cached_tokens。
• 该扩展仅适用于 anthropic/* catalog plane 的模型。OpenAI 和 Gemini 模型保持各自原生的缓存行为。

缓存写入与缓存读取的定价

Anthropic 按模型输入 token 单价的倍数为缓存操作定价。写入是每个缓存块一次性的小幅溢价；读取才是真正把钱省回来的环节。在 apiToken.sale 上，固定的 50% B2C 折扣会按官方消费金额计算后作用于每一条用量，缓存用量也不例外。

缓存条目默认存活五分钟，每次命中都会重置计时器，所以活跃会话可以无限期保持缓存热度。对于突发型负载，可以以更高的写入成本选择一小时 TTL。缓存读取的价格是全新输入的十分之一——叠加折扣后是二十分之一——所以一个前缀在 TTL 内被读取三次，就已经比全新发送两次更便宜。

缓存条目不跨账户共享，也绝不会在 apiToken.sale 的客户之间泄漏。你的缓存前缀只能被同一上游账户上下文下鉴权的请求复用。

哪些负载能命中缓存——哪些永远命中不了

• 每轮都重发相同代码库上下文、CLAUDE.md 和工具 schema 的编程代理和 IDE 助手。
• 针对固定文档集做查询的 RAG 流水线——缓存整个语料库，只变化问题。
• 带长而稳定的系统提示词和 few-shot 示例库的聊天机器人。
• 针对一个大指令块对大量短条目做分类或抽取的批处理任务。

一次性问题、每次都变的提示词、低于最小尺寸的前缀，缓存都帮不上忙。如果每个请求确实都是独一无二的，你只会白付写入溢价而永远收不到读取——全量开启之前先实测。

在 usage 对象中确认缓存命中

每个 Messages API 响应都会在 usage 块里直接报告缓存用量。缓存命中时看起来是这样的：

"usage": {
  "input_tokens": 38,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 14802,
  "output_tokens": 412
}

持续观察各请求中的 cache_read_input_tokens：健康的集成在首次调用之后，大部分上下文都会落在这个字段里，而 cache_creation_input_tokens 在 TTL 到期前都接近零。在 apiToken.sale 上，同样的用量明细会出现在你的控制台中——每个请求都列出模型、提供商和 token 级拆分，每一条缓存行都能在用量详情里看到，节省是可审计的，而不是靠推测。

缓存与预付费折扣的叠加

缓存降低你按全价支付的 token 数量；apiToken.sale 的折扣降低每个 token 的单价。两者是相乘关系。以 Claude Sonnet 5 为例（官方输入价 $2 / 1M token）：全新重发 100,000 token 的上下文，每次调用花 $0.20。走缓存读取只要 $0.02，再叠加固定的 50% B2C 折扣，这次调用的上下文部分只需 $0.01——相比过去占账单大头的部分，降了 20 倍。

计费保持预付费、简单透明：一个余额覆盖支持的 Claude、GPT、Gemini 和 Kimi 模型，每个模型先按官方价格表计量，再应用折扣。充值一次，用好缓存的负载能让同样的余额跑得远比无缓存流量更久。

各模型的输入、输出与缓存费率 →

在 Claude API 成本计算器中模拟缓存负载 →

常见问题

相关指南