提示缓存

"Prompt caching"（提示缓存）通过允许从提示中的特定前缀恢复来优化您的 API 使用。这显著减少了重复性任务或具有一致元素的提示的处理时间和成本。

有两种方式可以启用提示缓存：

• 自动缓存：在请求的顶层添加一个 cache_control 字段。系统会自动将缓存断点应用于最后一个可缓存的块，并随着对话的增长向前移动。最适合多轮对话，其中不断增长的消息历史应被自动缓存。
• 显式缓存断点：直接在各个内容块上放置 cache_control，以精细控制具体缓存哪些内容。

最简单的入门方式是使用自动缓存：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
    messages=[
        {
            "role": "user",
            "content": "Analyze the major themes in 'Pride and Prejudice'.",
        }
    ],
)
print(response.usage.model_dump_json())

使用自动缓存时，系统会缓存直到并包括最后一个可缓存块的所有内容。在具有相同前缀的后续请求中，缓存的内容会被自动重用。



提示缓存的工作原理

当您发送启用了提示缓存的请求时：

1. 系统检查提示前缀（直到指定的缓存断点）是否已从最近的查询中缓存。
2. 如果找到，则使用缓存版本，从而减少处理时间和成本。
3. 否则，系统会处理完整的提示，并在响应开始后缓存该前缀。

这在以下情况下特别有用：

• 包含大量示例的提示
• 大量上下文或背景信息
• 具有一致指令的重复性任务
• 长时间的多轮对话

默认情况下，缓存的生命周期为 5 分钟。每次使用缓存内容时，缓存都会免费刷新。



定价

提示缓存引入了新的定价结构。下表显示了每个支持的模型每百万令牌的价格：



支持的模型

所有活跃的 Claude 模型均支持提示缓存（包括自动和显式两种方式）。



自动缓存

自动缓存是启用提示缓存最简单的方式。无需在各个内容块上放置 cache_control，只需在请求正文的顶层添加一个 cache_control 字段。系统会自动将缓存断点应用于最后一个可缓存的块。



自动缓存在多轮对话中的工作原理

使用自动缓存时，缓存点会随着对话的增长自动向前移动。每个新请求都会缓存直到最后一个可缓存块的所有内容，而之前的内容则从缓存中读取。

缓存断点会自动移动到每个请求中的最后一个可缓存块，因此随着对话的增长，您无需更新任何 cache_control 标记。



TTL 支持

默认情况下，自动缓存使用 5 分钟的 TTL。您可以指定 1 小时的 TTL，价格为基础输入令牌价格的 2 倍：

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



与块级缓存结合使用

自动缓存与显式缓存断点兼容。当两者一起使用时，自动缓存断点会占用 4 个可用断点槽位中的一个。

这使您可以结合两种方法。例如，使用显式断点缓存您的系统提示，同时让自动缓存处理对话：

{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What are the key terms?" }]
}



保持不变的部分

自动缓存使用相同的底层缓存基础设施。定价、最小令牌阈值、上下文排序要求以及 20 块回溯窗口的应用方式均与显式断点相同。



边缘情况

• 如果最后一个块已经具有相同 TTL 的显式 cache_control，则自动缓存不执行任何操作。
• 如果最后一个块具有不同 TTL 的显式 cache_control，API 会返回 400 错误。
• 如果已存在 4 个显式块级断点，API 会返回 400 错误（没有剩余槽位用于自动缓存）。
• 如果最后一个块不符合作为自动缓存断点目标的条件，系统会静默地向后查找最近的符合条件的块。如果未找到，则跳过缓存。



显式缓存断点

如需对缓存进行更多控制，您可以直接在各个内容块上放置 cache_control。当您需要缓存以不同频率变化的不同部分，或需要精细控制具体缓存哪些内容时，这非常有用。



构建您的提示

将静态内容（工具定义、系统指令、上下文、示例）放在提示的开头。使用 cache_control 参数标记可重用内容的结尾以进行缓存。

缓存前缀按以下顺序创建：tools、system，然后是 messages。此顺序形成一个层次结构，每个级别都建立在前一个级别之上。



自动前缀检查的工作原理

您可以只在静态内容的末尾使用一个缓存断点，系统会自动查找先前请求已写入缓存的最长前缀。了解其工作原理有助于您优化缓存策略。

三个核心原则：

1. 缓存写入仅发生在您的断点处。 用 cache_control 标记一个块只会写入一个缓存条目：以该块结尾的前缀的哈希值。系统不会为任何更早的位置写入条目。由于哈希是累积的，涵盖直到并包括断点的所有内容，因此更改断点处或之前的任何块都会在下一个请求中产生不同的哈希。

2. 缓存读取会向后查找先前请求写入的条目。 在每个请求中，系统会计算您断点处的前缀哈希，并检查是否有匹配的缓存条目。如果不存在，系统会一次向后移动一个块，检查每个更早位置的前缀哈希是否与缓存中已有的内容匹配。它查找的是先前的写入，而不是稳定的内容。

3. 回溯窗口为 20 个块。 系统每个断点最多检查 20 个位置，将断点本身计为第一个。如果系统在该窗口内未找到匹配的条目，检查将停止（或从下一个显式断点恢复，如果有的话）。

示例：不断增长的对话中的回溯

您每轮追加新块，并在每个请求的最后一个块上设置 cache_control：

• 第 1 轮： 10 个块，断点在块 10。不存在先前的缓存条目。系统在块 10 处写入一个条目。
• 第 2 轮： 15 个块，断点在块 15。块 15 没有条目，因此系统向后回溯到块 10 并找到第 1 轮的条目。在块 10 处缓存命中；系统仅重新处理块 11 到 15，并在块 15 处写入新条目。
• 第 3 轮： 35 个块，断点在块 35。系统检查 20 个位置（块 35 到 16），未找到任何内容。第 2 轮在块 15 处的条目位于窗口外一个位置，因此没有缓存命中。在块 15 处添加第二个断点会在那里启动第二个回溯窗口，从而找到第 2 轮的条目。

常见错误：断点位于每次请求都会变化的内容上

您的提示有一个大型静态系统上下文（块 1 到 5），后面跟着一个包含时间戳和用户消息的每请求块（块 6）。您在块 6 上设置 cache_control：

• 请求 1： 在块 6 处缓存写入。哈希包含时间戳。
• 请求 2： 时间戳不同，因此块 6 处的前缀哈希不同。回溯遍历块 5、4、3、2 和 1，但系统从未在这些位置写入过条目。没有缓存命中。您每次请求都要为新的缓存写入付费，却从未获得读取。

回溯不会找到断点后面的稳定内容并将其缓存。它查找的是先前请求已写入的条目，而写入仅发生在断点处。将 cache_control 移到块 5（跨请求保持不变的最后一个块），后续每个请求都会读取缓存的前缀。自动缓存也会遇到同样的陷阱：它将断点放在最后一个可缓存块上，而在这种结构中，该块正是每次请求都会变化的块，因此请改用块 5 上的显式断点。

关键要点： 将 cache_control 放在您希望共享缓存的请求之间前缀完全相同的最后一个块上。在不断增长的对话中，只要每轮添加的块少于 20 个，最后一个块就可以正常工作：较早的内容从不改变，因此下一个请求的回溯会找到先前的写入。对于具有可变后缀（时间戳、每请求上下文、传入消息）的提示，请将断点放在静态前缀的末尾，而不是可变块上。



何时使用多个断点

如果您希望执行以下操作，可以定义最多 4 个缓存断点：

• 缓存以不同频率变化的不同部分（例如，工具很少变化，但上下文每天更新）
• 对具体缓存哪些内容有更多控制
• 当不断增长的对话将您的断点推到距上次缓存写入 20 个或更多块之外时，确保缓存命中



了解缓存断点成本

缓存断点本身不会增加任何成本。 您只需为以下内容付费：

• 缓存写入：当新内容写入缓存时（5 分钟 TTL 的价格比基础输入令牌高 25%）
• 缓存读取：当使用缓存内容时（基础输入令牌价格的 10%）
• 常规输入令牌：用于任何未缓存的内容

添加更多 cache_control 断点不会增加您的成本——您仍然根据实际缓存和读取的内容支付相同的金额。断点只是让您能够控制哪些部分可以独立缓存。



缓存策略和注意事项



缓存限制

在 Claude API、Claude Platform on AWS、Vertex AI 和 Microsoft Foundry（测试版）上，最小可缓存提示长度为：

• Claude Fable 5 和 Claude Mythos 5 为 512 个令牌
• Claude Mythos Preview 和 Claude Opus 4.7 为 2,048 个令牌
• Claude Opus 4.6 和 Claude Opus 4.5 为 4,096 个令牌
• Claude Opus 4.8、Claude Sonnet 4.6、Claude Sonnet 4.5、Claude Opus 4.1（已弃用）、Claude Opus 4（已弃用）和 Claude Sonnet 4（已弃用）为 1,024 个令牌
• Claude Haiku 4.5 为 4,096 个令牌
• Claude Haiku 3.5（已停用，Vertex AI 除外）为 2,048 个令牌

模型可用性因平台而异，新发布模型的最小值也可能不同：在 Amazon Bedrock 上，Claude Fable 5 和 Claude Mythos 5 的最小可缓存提示长度为 1,024 个令牌。

较短的提示无法缓存，即使标记了 cache_control。任何缓存少于此令牌数的请求都将在不缓存的情况下处理，且不会返回错误。要验证提示是否已缓存，请检查响应的 usage 字段：如果 cache_creation_input_tokens 和 cache_read_input_tokens 均为 0，则提示未被缓存（可能是因为未达到最小长度要求）。

如果您的提示略低于您的模型和平台的最小值，扩展缓存内容以达到阈值通常是值得的。缓存读取的成本远低于未缓存的输入令牌，因此达到最小值可以降低频繁重用的提示的成本。

对于并发请求，请注意缓存条目仅在第一个响应开始后才可用。如果您需要并行请求的缓存命中，请等待第一个响应后再发送后续请求。

目前，"ephemeral" 是唯一支持的缓存类型，默认生命周期为 5 分钟。



可以缓存的内容

请求中的大多数块都可以缓存。这包括：

• 工具：tools 数组中的工具定义
• 系统消息：system 数组中的内容块
• 文本消息：messages.content 数组中的内容块，适用于用户和助手轮次
• 图像和文档：messages.content 数组中的内容块，在用户轮次中
• 工具使用和工具结果：messages.content 数组中的内容块，在用户和助手轮次中

这些元素中的每一个都可以缓存，可以自动缓存，也可以通过用 cache_control 标记它们来缓存。



无法缓存的内容

虽然大多数请求块都可以缓存，但也有一些例外：

• 思考块不能直接用 cache_control 缓存。但是，当思考块出现在先前的助手轮次中时，它们可以与其他内容一起缓存。以这种方式缓存时，从缓存读取时它们确实会计为输入令牌。

• 子内容块（如引用）本身不能直接缓存。请改为缓存顶层块。

  对于引用，作为引用源材料的顶层文档内容块可以被缓存。这使您可以通过缓存引用将引用的文档来有效地将提示缓存与引用结合使用。

• 空文本块无法缓存。



什么会使缓存失效

对缓存内容的修改可能会使部分或全部缓存失效。

如构建您的提示中所述，缓存遵循以下层次结构：tools → system → messages。每个级别的更改都会使该级别及所有后续级别失效。

下表显示了不同类型的更改会使缓存的哪些部分失效。✘ 表示缓存失效，而 ✓ 表示缓存保持有效。



跟踪缓存性能

使用响应中 usage 内的以下 API 响应字段（如果使用流式传输，则为 message_start 事件）来监控缓存性能：

• cache_creation_input_tokens：创建新条目时写入缓存的令牌数。
• cache_read_input_tokens：此请求从缓存中检索的令牌数。
• input_tokens：未从缓存读取或用于创建缓存的输入令牌数（即最后一个缓存断点之后的令牌）。

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens



使用思考块进行缓存

当将扩展思考与提示缓存结合使用时，思考块具有特殊行为：

与其他内容一起自动缓存：虽然思考块不能显式地用 cache_control 标记，但当您使用工具结果进行后续 API 调用时，它们会作为请求内容的一部分被缓存。这通常发生在工具使用期间，当您将思考块传回以继续对话时。

输入令牌计数：当从缓存读取思考块时，它们在您的使用指标中计为输入令牌。这对于成本计算和令牌预算很重要。

缓存失效模式：

• 当仅提供工具结果作为用户消息时，缓存保持有效
• 在 Opus 4.5+ 和 Sonnet 4.6+ 上，即使添加了非工具结果的用户内容，思考块也默认保留，因此缓存保持有效
• 在较早的 Opus/Sonnet 模型和所有 Haiku 模型上，当添加非工具结果的用户内容时，缓存会失效，导致所有先前的思考块从上下文中剥离
• 即使没有显式的 cache_control 标记，也会发生这种缓存行为

有关缓存失效的更多详情，请参阅什么会使缓存失效。

工具使用示例：

Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]

Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1

Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# On earlier Opus/Sonnet and all Haiku models, non-tool-result user block causes prior thinking blocks to be stripped; on Opus 4.5+/Sonnet 4.6+ they are kept

在较早的 Opus/Sonnet 模型和所有 Haiku 模型上，此时所有先前的思考块都会从上下文中删除。在 Opus 4.5+ 和 Sonnet 4.6+ 上，先前的思考块默认保留，并仍然是缓存前缀的一部分。

有关更详细的信息，请参阅扩展思考文档。



缓存存储和共享

• 组织和工作区隔离： 缓存在组织之间是隔离的。不同的组织永远不会共享缓存，即使它们使用相同的提示。自 2026 年 2 月 5 日起，在 Claude API、Claude Platform on AWS 和 Microsoft Foundry（测试版）上，缓存在组织内也按工作区隔离；Bedrock 和 Vertex AI 继续仅使用组织级隔离。

• 精确匹配： 缓存命中需要 100% 相同的提示段，包括直到并包括用 cache control 标记的块的所有文本和图像。

• 输出令牌生成： 提示缓存对输出令牌生成没有影响。您收到的响应与未使用提示缓存时收到的响应完全相同。



有效缓存的最佳实践

要优化提示缓存性能：

• 对于多轮对话，从自动缓存开始。它会自动处理断点管理。
• 当您需要以不同的变化频率缓存不同部分时，使用显式块级断点。
• 缓存稳定、可重用的内容，如系统指令、背景信息、大型上下文或常用工具定义。
• 将缓存内容放在提示的开头以获得最佳性能。
• 策略性地使用缓存断点来分隔不同的可缓存前缀部分。
• 将断点放在跨请求保持完全相同的最后一个块上。对于具有静态前缀和可变后缀（时间戳、每请求上下文、传入消息）的提示，该位置是前缀的末尾，而不是可变块。
• 定期分析缓存命中率并根据需要调整您的策略。



针对不同用例进行优化

根据您的场景定制提示缓存策略：

• 对话代理：降低扩展对话的成本和延迟，特别是那些具有长指令或上传文档的对话。
• 编码助手：通过在提示中保留代码库的相关部分或摘要版本来改进自动完成和代码库问答。
• 大型文档处理：在提示中包含完整的长篇材料（包括图像），而不会增加响应延迟。
• 详细指令集：共享大量指令、程序和示例列表以微调 Claude 的响应。开发人员通常在提示中包含一两个示例，但通过提示缓存，您可以通过包含 20 多个高质量答案的多样化示例来获得更好的性能。
• 代理式工具使用：提高涉及多个工具调用和迭代代码更改的场景的性能，其中每个步骤通常需要新的 API 调用。
• 与书籍、论文、文档、播客转录和其他长篇内容对话：通过将整个文档嵌入提示中并让用户向其提问，使任何知识库变得生动。



常见问题排查

如果遇到意外行为：

• 确保缓存部分在各次调用之间完全相同。对于显式断点，验证 cache_control 标记位于相同位置
• 检查调用是否在缓存生命周期内进行（默认为 5 分钟）
• 验证 tool_choice 和图像使用在各次调用之间保持一致
• 验证您缓存的令牌数至少达到您的模型和平台的最小值（请参阅缓存限制）
• 确认您的断点位于跨请求保持完全相同的块上。缓存写入仅发生在断点处，如果该块发生变化（时间戳、每请求上下文、传入消息），前缀哈希永远不会匹配。回溯不会找到断点后面的稳定内容；它只会找到先前请求在其自己的断点处写入的条目
• 验证您的 tool_use 内容块中的键具有稳定的排序，因为某些语言（例如 Swift、Go）在 JSON 转换期间会随机化键顺序，从而破坏缓存
• 使用缓存诊断让 API 比较连续的请求并报告提示的哪个部分出现了分歧



1 小时缓存持续时间

如果您觉得 5 分钟太短，Anthropic 还提供 1 小时的缓存持续时间，需额外付费。

要使用扩展缓存，请在 cache_control 定义中包含 ttl，如下所示：

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

响应将包含详细的缓存信息，如下所示：

{
  "usage": {
    "input_tokens": 2048,
    "cache_read_input_tokens": 1800,
    "cache_creation_input_tokens": 248,
    "output_tokens": 503,

    "cache_creation": {
      "ephemeral_5m_input_tokens": 148,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

请注意，当前的 cache_creation_input_tokens 字段等于 cache_creation 对象中各值的总和。



何时使用 1 小时缓存

如果您的提示以固定节奏使用（即系统提示的使用频率高于每 5 分钟一次），请继续使用 5 分钟缓存，因为它会继续免费刷新。

1 小时缓存最适合以下场景：

• 当您的提示使用频率可能低于每 5 分钟一次，但高于每小时一次时。例如，当代理式子代理需要超过 5 分钟时，或者当存储与用户的长聊天对话且您通常预期该用户可能不会在接下来的 5 分钟内响应时。
• 当延迟很重要且您的后续提示可能在 5 分钟之后发送时。
• 当您希望提高速率限制利用率时，因为缓存命中不会从您的速率限制中扣除。



混合使用不同的 TTL

您可以在同一请求中同时使用 1 小时和 5 分钟缓存控制，但有一个重要约束：TTL 较长的缓存条目必须出现在 TTL 较短的条目之前（即 1 小时缓存条目必须出现在任何 5 分钟缓存条目之前）。

当混合使用 TTL 时，API 会在您的提示中确定三个计费位置：

1. 位置 A：最高缓存命中处的令牌计数（如果没有命中则为 0）。
2. 位置 B：A 之后最高的 1 小时 cache_control 块处的令牌计数（如果不存在则等于 A）。
3. 位置 C：最后一个 cache_control 块处的令牌计数。

您将被收取以下费用：

1. A 的缓存读取令牌。
2. (B - A) 的 1 小时缓存写入令牌。
3. (C - B) 的 5 分钟缓存写入令牌。

以下是 3 个示例。这描绘了 3 个请求的输入令牌，每个请求都有不同的缓存命中和缓存未命中。因此，每个请求都有不同的计算定价，如彩色框中所示。



预热缓存

缓存预热让您可以在用户触发真实请求之前将系统提示或工具定义加载到提示缓存中。这消除了首次用户交互时的缓存未命中延迟惩罚，减少了对延迟敏感的应用程序的首个令牌时间（TTFT）。



工作原理

在您的请求中设置 max_tokens: 0。API 会将您的提示读入模型，并在任何 cache_control 断点处写入缓存，然后立即返回而不生成任何输出。响应具有空的 content 数组、stop_reason: "max_tokens" 以及完整填充的 usage 块。

将 cache_control 断点放在与后续请求共享的最后一个块上（通常是您的系统提示或工具定义），而不是占位符用户消息上。否则，缓存条目会以占位符为键，后续请求将无法命中它。这意味着使用显式缓存断点而不是自动缓存，因为自动缓存会将断点放在最后一个块上，而在这里该块是占位符。占位符用户消息可以是任何包含非空白内容的字符串（此处的示例使用 "warmup"）；其内容会被读入模型但永远不会被回答。

API 返回一个空的 content 数组：

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [],
  "model": "claude-opus-4-8",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 8,
    "cache_creation_input_tokens": 5120,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 5120,
      "ephemeral_1h_input_tokens": 0
    },
    "iterations": [
      {
        "input_tokens": 8,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 5120,
        "cache_creation": {
          "ephemeral_5m_input_tokens": 5120,
          "ephemeral_1h_input_tokens": 0
        },
        "type": "message"
      }
    ],
    "output_tokens": 0,
    "service_tier": "standard",
    "inference_geo": "global"
  }
}



典型使用模式

在应用程序启动时（或按计划的时间间隔）发出预热请求，然后在预热完成后发送真实的用户请求：

client = anthropic.Anthropic()

SYSTEM_PROMPT = [
    {
        "type": "text",
        "text": "You are an expert software engineer with deep knowledge of distributed systems...",
        "cache_control": {"type": "ephemeral"},
    }
]


def prewarm_cache() -> None:
    """Call this at application startup or on a scheduled interval."""
    client.messages.create(
        model="claude-opus-4-8",
        max_tokens=0,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": "warmup"}],
    )


def respond(user_message: str) -> anthropic.types.Message:
    """The real user request; benefits from a warm cache."""
    return client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


# 在任何用户流量到达之前预热缓存。
prewarm_cache()

# 之后，当用户提交消息时，系统提示前缀已被缓存。
response = respond("How do I implement a binary search tree?")
print(response.content[0].text)

请记住，缓存 TTL 仍然适用。对于默认的 5 分钟缓存，至少每 5 分钟发送一次新的预热请求以保持缓存处于预热状态。对于用户请求之间间隔较长的情况，请改用 1 小时缓存持续时间。



限制

如果设置了以下任何一项，max_tokens: 0 请求将被拒绝并返回 invalid_request_error，因为每一项都意味着需要生成输出，而零令牌预算无法产生输出：

• stream: true
• 扩展思考（thinking.type: "enabled"）
• 结构化输出（output_config.format）
• tool_choice 为 {"type": "tool", ...} 或 {"type": "any"}

在 Message Batches（消息批处理）请求中，max_tokens: 0 同样会被拒绝。预热（pre-warming）针对的是首个令牌的响应时间，这不适用于批处理；而且在批处理期间写入的缓存条目很可能在后续请求运行之前就已过期。



替代 max_tokens=1 的变通方法

在 max_tokens: 0 可用之前，一些应用程序使用 max_tokens: 1 的预热调用来实现相同的效果。推荐使用 max_tokens: 0 方法：不会产生任何输出，因此无需丢弃单令牌回复，不会对输出令牌计费，并且请求的意图明确无歧义。



提示缓存示例

为了帮助您开始使用提示缓存，提示缓存 cookbook 提供了详细的示例和最佳实践。

以下代码片段展示了各种提示缓存模式。这些示例演示了如何在不同场景中实现缓存，帮助您理解此功能的实际应用：



数据保留

提示缓存（包括自动和显式）符合 ZDR（零数据保留）资格。Anthropic 不会存储您的提示或 Claude 响应的原始文本。

KV（键值）缓存表示和缓存内容的加密哈希仅保存在内存中，不会持久化存储。缓存条目的最短生命周期为 5 分钟（标准）或 1 小时（扩展），之后会被及时（但非立即）删除。缓存条目在组织之间是隔离的；在 Claude API、AWS 上的 Claude Platform 以及 Microsoft Foundry（测试版）上，组织内的工作区之间也是隔离的。

有关所有功能的 ZDR 资格，请参阅 API 和数据保留。



常见问题

这对于理解成本和速率限制都很重要，因为在有效使用缓存时，input_tokens 通常会远小于您的总输入。