Claude 缓存计费

与 GPT/Gemini 的自动缓存不同,Claude 原生接口的提示词缓存是显式声明的: 用 cache_control 标记要缓存的内容块。命中后该部分按缓存倍率计费。

用法

在 system 或消息内容块上加 cache_control:

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<几千字的规则文档或知识库>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "根据规则回答:……" }]
}

确认命中

响应 usage 中:

{
  "usage": {
    "input_tokens": 42,
    "cache_creation_input_tokens": 4810,
    "cache_read_input_tokens": 0,
    "output_tokens": 213
  }
}

• 首次调用:cache_creation_input_tokens 计入建缓存(略高于标准价);
• 后续命中:cache_read_input_tokens 按缓存倍率计费(远低于标准价);
• 缓存有效期为分钟级,持续调用会自动续期。

实践建议

• 缓存点放在长而稳定的内容后面:系统提示词、工具定义、参考文档;
• 被缓存内容必须逐字节一致,模板里不要混入时间戳等易变字段;
• 低频调用(间隔超过缓存存活期)不会命中,反复建缓存反而更贵—— 低频场景直接不加 cache_control;
• 经 OpenAI 兼容接口调用 Claude 时缓存由上游自动处理,无需该参数, 见缓存计费。