OpenRouter 响应缓存（Beta）对完全相同的 API 请求返回缓存结果，缓存命中时完全免费（usage 全部为 0）。通过 X-OpenRouter-Cache: true 请求头或 Preset 的 cache_enabled 字段启用，默认 TTL 300 秒，最长 24 小时。缓存按 API key 隔离，缓存命中时流式请求也会重放流式响应。

OpenRouter 响应缓存（Beta）

Beta 阶段：缓存 API 和行为可能发生变更。

响应缓存让完全相同的请求直接从缓存返回，缓存命中时完全免费，所有 usage 计数归零。

启用缓存

方式一：请求头

在请求头中添加 X-OpenRouter-Cache: true：

bash

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": "What is the meaning of life?"}]
  }'

首次请求（MISS）：正常计费，响应被缓存：

X-OpenRouter-Cache-Status: MISS
X-OpenRouter-Cache-TTL: 300

再次请求（HIT）：免费，usage 全部为 0：

X-OpenRouter-Cache-Status: HIT
X-OpenRouter-Cache-Age: 12
X-OpenRouter-Cache-TTL: 288
X-Generation-Id: gen-def456

json

{
  "id": "gen-def456",
  "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0 }
}

方式二：通过 Preset

在 Preset 中配置 cache_enabled: true，该 Preset 的所有请求自动启用缓存：

json

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

缓存键规则

两个请求被视为"相同"需满足：

相同 API key
相同模型
相同端点类型
相同 streaming 模式（stream: true/false 分开缓存）
相同请求体（SHA-256 哈希，属性顺序敏感）

注意：

JSON 属性顺序不同会产生不同缓存键
同一请求显式传默认值（如 temperature: 1.0）与省略该字段也会产生不同键
HTTP-Referer、X-Title 等 attribution 头不影响缓存键

请求头参考

请求头	值	说明
`X-OpenRouter-Cache`	`true`	启用缓存
`X-OpenRouter-Cache`	`false`	禁用缓存（可覆盖 preset）
`X-OpenRouter-Cache-TTL`	`<秒>`	自定义 TTL（1-86400 秒，默认 300）
`X-OpenRouter-Cache-Clear`	`true`	强制刷新：删除旧缓存并重新请求

响应头	说明
`X-OpenRouter-Cache-Status`	`HIT` 或 `MISS`
`X-OpenRouter-Cache-Age`	已缓存的秒数（仅 HIT）
`X-OpenRouter-Cache-TTL`	剩余有效期（HIT）/ 完整 TTL（MISS）

TTL 配置

默认：300 秒（5 分钟）
范围：1 秒 ~ 86400 秒（24 小时）
通过 X-OpenRouter-Cache-TTL 头按请求设置，或在 Preset 的 cache_ttl_seconds 字段设置默认值

优先级规则

Preset 显式设置 cache_enabled: false → 缓存强制禁用，头无法覆盖
X-OpenRouter-Cache: false → 禁用（可覆盖 preset 的 true）
X-OpenRouter-Cache: true → 启用（当 preset 未配置时）
X-OpenRouter-Cache-TTL 头 → 覆盖 preset 的 cache_ttl_seconds
两者都没有设置 → 缓存关闭

支持的端点

端点	说明
`/api/v1/chat/completions`	OpenAI Chat Completions
`/api/v1/responses`	OpenAI Responses
`/api/v1/messages`	Anthropic Messages
`/api/v1/embeddings`	OpenAI Embeddings

限制

ZDR 账户不可用：账户级零数据保留会禁用缓存
并发相同请求：同时到达的相同请求都会 MISS，不合并处理
可能被提前驱逐：内存压力下缓存可能在 TTL 到期前被清除
不保证确定性：如果需要每次相同输出，结合 temperature: 0 或固定 seed 使用

典型使用场景

Agent 工作流：工作流中途失败后重试，已执行的步骤直接从缓存返回，不重复计费。

单元测试：首次运行后填充缓存，后续测试运行使用缓存响应，零费用且可重复。

重复请求：应用程序多次发送相同请求时（如相同系统 prompt + 相同用户问题），只有第一次计费。

常见问题

Q: 与提供商自己的 Prompt Cache 有什么区别？

A: OpenRouter 响应缓存在请求到达提供商之前就完整缓存整个响应。提供商 Prompt Cache（如 Anthropic、OpenAI 的）是在提供商内部缓存 KV 计算中间状态，两者可以同时使用，互不影响。

Q: 流式传输命中缓存时是什么体验？

A: 与正常流式传输相同——缓存的响应会通过相同的 SSE 管道重放，客户端收到相同的内容块序列。id、created 等字段反映的是新生成记录，不是原始记录。

Q: 缓存会影响不同 API key 之间吗？

A: 不会。缓存严格按 API key 隔离，即使是同一账号下的不同 key 也不共享缓存。

OpenRouter 响应缓存（Beta） ​

启用缓存 ​

方式一：请求头 ​

方式二：通过 Preset ​

缓存键规则 ​

请求头参考 ​

TTL 配置 ​

优先级规则 ​

支持的端点 ​

限制 ​

典型使用场景 ​

常见问题 ​