OpenRouter 平台功能

OpenRouter 平台功能

响应缓存

4 分钟阅读

响应缓存

为相同的 API 请求缓存响应，以节省时间和费用

响应缓存允许你为相同的 API 请求缓存响应。当有可用的缓存响应时，OpenRouter 会立即从缓存返回，不计费（所有计费用量计数器都报告为 0），从而同时降低延迟和成本。

响应缓存与模型无关，适用于 OpenRouter 上所有 支持的端点 中的每个模型，无论模型服务提供商是谁。缓存在请求到达任何提供商之前于 OpenRouter 层运行，因此不需要提供商侧支持。

流式和非流式请求都符合缓存条件。只有成功（200 OK）的响应会被缓存。错误响应、速率限制响应和部分结果永远不会被缓存。包含工具调用的响应会正常缓存，因为它们属于成功补全。对于流式请求，缓存响应会通过同一流式管道重放，因此客户端在缓存命中时会收到相同的内容块。每个块中的 id 字段、created 时间戳以及 X-Generation-Id 响应头反映的是新的缓存命中生成记录，而不是原始记录。

启用缓存

有两种方式启用响应缓存：

1. 通过请求头按请求启用

添加 X-OpenRouter-Cache 请求头，可为单个请求启用缓存：

curl -i https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer <OPENROUTER_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "X-OpenRouter-Cache: true" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "messages":
    [
        {
            "role": "user",
            "content": "人生的意义是什么？"
        }
    ]
  }'

第一次请求结果为缓存 MISS。响应会被存储，并按正常方式计费：

响应头（MISS）
HTTP/2 200
X-OpenRouter-Cache-Status: MISS
X-OpenRouter-Cache-TTL: 300
响应体（MISS）
{
  "id": "gen-abc123",
  "model": "google/gemini-2.5-flash",
  "choices": ["..."],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 120,
    "total_tokens": 135
  }
}

再次发送相同请求会返回缓存 HIT，用量归零且不计费。每次缓存命中都会获得自己唯一的生成 ID（注意下面的 gen-def456 与原始的 gen-abc123 不同）：

响应头（HIT）
HTTP/2 200
X-OpenRouter-Cache-Status: HIT
X-OpenRouter-Cache-Age: 12
X-OpenRouter-Cache-TTL: 288
X-Generation-Id: gen-def456
响应体（HIT）
{
  "id": "gen-def456",
  "created": 1746000012,
  "model": "google/gemini-2.5-flash",
  "choices": ["..."],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

2. 通过预设

你可以通过在 预设 中配置以下字段，为使用该预设的所有请求启用缓存：

字段类型说明
cache_enabledboolean为使用此预设的所有请求启用缓存
cache_ttl_secondsnumber缓存响应的默认 TTL（1–86400 秒，默认 300）

当预设上设置了 cache_enabled 时，引用该预设的每个请求都会自动应用缓存。不需要 X-OpenRouter-Cache 请求头。

示例预设配置：

{
  "name": "cached-tests",
  "cache_enabled": true,
  "cache_ttl_seconds": 600
}

工作原理

当两个请求共享相同的 API 密钥、模型、端点类型、流式模式和请求体（包括所有参数）时，它们被视为相同。启用缓存后，OpenRouter 会根据这些输入生成缓存键。如果之前发出过相同请求且缓存响应尚未过期，会立即返回缓存响应。更改其中任何一项——包括模型、端点，或在流式与非流式之间切换——都会产生不同的缓存键并导致缓存未命中。

由于缓存在请求转发之前于 OpenRouter 层运行，它适用于 支持的端点类型 中的每个模型和模型服务提供商。

缓存以你的 API 密钥为作用域。不同 API 密钥即使属于同一账户或组织，也不会共享缓存。轮换 API 密钥后，新密钥的缓存为空。

非确定性：无论 temperature 等随机参数如何，缓存响应都会原样返回。如果需要全新响应，请使用 X-OpenRouter-Cache-Clear: true 或较短的 TTL。

缓存键细节

缓存键由你的 API 密钥、模型、端点类型、流式模式 以及 请求体的 SHA-256 哈希 派生。流式和非流式请求分开缓存，因此 stream: true 的请求不会返回缓存的非流式响应，反之亦然。请求体在哈希前会规范化，因此多余空白不影响缓存键。但是，JSON 请求体的属性顺序是有意义的：

  • 逻辑相同但属性顺序不同的 JSON（例如 {"model":"x","messages":[]} 与 {"messages":[],"model":"x"}）会产生不同的缓存键
  • 省略可选字段与显式发送默认值（例如 temperature: 1.0）会产生不同的键
  • 归因请求头（例如 HTTP-Referer、X-Title）和 提供商特定请求头 不是缓存键的一部分
  • 多模态请求（图像、音频、视频、文件附件）符合缓存条件。完整请求体（包括 base64 编码内容）都会纳入哈希

优先级

请求头与 预设 配置的交互如下：

  1. 如果预设显式设置 cache_enabled: false，无论请求头如何，缓存都会被禁用——请求头不能覆盖预设的退出选择
  2. X-OpenRouter-Cache: false 请求头会禁用缓存，即使预设启用了缓存
  3. 当预设未配置缓存（即不存在 cache_enabled）时，X-OpenRouter-Cache: true 会启用缓存——但不能覆盖显式设置了 cache_enabled: false 的预设（规则 1 优先）
  4. X-OpenRouter-Cache-TTL 请求头会覆盖预设的 cache_ttl_seconds（默认：300 秒）
  5. 如果既未设置请求头也未设置预设，缓存为关闭

并发请求

如果两个相同请求在第一个响应写入缓存之前同时到达，二者都会得到缓存 MISS，并分别计费。没有请求合并。

支持的端点

端点API 格式
/api/v1/chat/completionsOpenAI Chat Completions
/api/v1/responsesOpenAI Responses
/api/v1/messagesAnthropic Messages
/api/v1/embeddingsOpenAI Embeddings

缓存键包含端点类型区分符，因此发往不同端点、即使请求体相同的请求也不会冲突。

提供商缓存：部分模型服务提供商提供自己的提示词缓存（例如 Anthropic 提示词缓存、OpenAI 缓存上下文）。提供商缓存与 OpenRouter 响应缓存相互独立，二者可以一起使用。OpenRouter 缓存在调用到达提供商之前按请求级别运行，而提供商缓存在提供商基础设施内部运行。

请求头

请求头值说明
X-OpenRouter-Cachetrue为此请求启用缓存
X-OpenRouter-Cachefalse为此请求禁用缓存（覆盖预设）
X-OpenRouter-Cache-TTL<seconds>自定义 TTL（1–86400 秒，默认 300）
X-OpenRouter-Cache-Cleartrue强制刷新此请求的缓存

无法解析为整数的 TTL 值（即不以数字开头）会被忽略，并回退到预设或默认 TTL。以数字开头的值即使包含尾随非数字字符也会被接受（例如 60abc 视为 60）；小数值会被截断（例如 1.5 视为 1）。超出有效范围的数值会被钳制到 [1, 86400]。

响应头

响应头值说明
X-OpenRouter-Cache-StatusHIT 或 MISS响应是否来自缓存
X-OpenRouter-Cache-Age<seconds>响应已缓存多久（仅在 HIT 时）
X-OpenRouter-Cache-TTL<seconds>HIT 时为剩余 TTL；MISS 时为完整 TTL

X-Generation-Id 响应头也会出现在每个响应上（无论是否缓存），并非缓存专用。在缓存命中时，生成 ID 对该次命中是唯一的——不会复用原始响应中的 ID。

TTL（生存时间）

TTL 控制缓存响应保持有效的时长。

  • 默认：300 秒（5 分钟）
  • 范围：1 秒到 86400 秒（24 小时）

你可以使用 X-OpenRouter-Cache-TTL 请求头按请求自定义 TTL，或在 预设 配置中设置默认 TTL。

清除缓存

要为特定请求强制获取全新响应，请在发送 X-OpenRouter-Cache: true 的同时发送 X-OpenRouter-Cache-Clear: true 请求头（或配合设置了 cache_enabled: true 的预设）。这会删除该缓存键的现有缓存条目，向模型服务提供商发出新请求，并存储新响应。除非该请求已启用缓存，否则 X-OpenRouter-Cache-Clear 不会生效。这不会清除所有缓存条目——只清除与当前请求匹配的那一条。

新的缓存条目使用当前请求的 X-OpenRouter-Cache-TTL 请求头、预设的 cache_ttl_seconds 或默认值（300 秒）作为 TTL，遵循标准 优先级规则。

计费

缓存命中免费。不会消耗 Token，所有计费用量计数器都报告为 0。对于 chat completions 和 Responses 端点，usage.prompt_tokens、usage.completion_tokens 和 usage.total_tokens 会归零。对于 Embeddings 端点，usage.prompt_tokens 和 usage.total_tokens 会归零（embeddings 响应中不存在 completion_tokens）。对于 Anthropic Messages 端点，usage.input_tokens 和 usage.output_tokens 会归零。你只为填充缓存的原始请求（缓存 MISS）付费。

缓存命中不计入模型服务提供商的速率限制，因为请求从未到达提供商。

限制

  • 账户级零数据保留（ZDR）下禁用：当强制执行账户级 ZDR 时，响应缓存不可用，因为缓存需要临时存储响应数据。按请求的 provider.zdr 不影响缓存资格。
  • 并发相同请求：如果两个相同请求在第一个响应被缓存之前到达，二者都会得到 MISS。参见 并发请求。
  • 缓存淘汰：在内存压力下，缓存响应可能在 TTL 到期前被淘汰。你可以缓存的条目数量没有限制，但压力下的淘汰意味着条目不保证能存活完整 TTL。

数据保留

缓存响应存储在边缘基础设施中，仅保留 TTL 时长，到期后自动淘汰。缓存数据只能通过触发缓存的 API 密钥访问——其他密钥、账户或组织都无法检索。缓存数据不用于训练，也不会与第三方共享。

使用场景

智能体工作流

当智能体工作流中途失败时，你可以从失败点恢复，而无需重新运行并重新支付前面相同的请求。在工作流开始时启用缓存，重试时所有先前步骤都会立即从缓存返回。

单元测试

为测试套件获得可重复的响应。初始运行填充缓存后，后续相同请求每次都会以零成本返回同一缓存响应。若要让首次运行也确定，请使用 temperature: 0 或固定的 seed。

重复的相同请求

如果你的应用多次发出相同请求（同一模型、同一消息、同一参数），缓存可确保只有第一次调用到达模型服务提供商。后续相同调用会立即从缓存返回，成本为零。

监控缓存效果

缓存命中和未命中状态可在 用量日志 中查看。每个缓存请求都会作为带缓存指示的独立条目出现，你可以筛选日志以仅显示已缓存或未缓存的请求。每次缓存命中都会获得自己唯一的生成 ID，因此你可以独立跟踪各个缓存响应。

上一页自定义分类器下一页 服务层级