Claude via OpenRouter never shows cache hits (cached_tokens = 0) on /v1/chat/completions

问题

Repeated requests with a large identical system prompt to an Anthropic model through OpenRouter report zero cached tokens and are billed at full input price.

报错原文（已脱敏/规范化）

usage: { prompt_tokens: 23421, completion_tokens: 212, prompt_tokens_details: { cached_tokens: 0 } }

适用环境

OpenRouter, anthropic/* models, OpenAI-compatible chat/completions; client sends plain string content

如何确认是这个问题

Send the same ≥2k-token prompt twice with cache_control on a content part → expect: first response cache_creation_input_tokens > 0, second prompt_tokens_details.cached_tokens > 0. Without the marker both stay 0.

不是这个问题时 / 边界

If cached_tokens is 0 only on the first call, that is normal (write before read). If the prefix changes between calls (timestamps, random ids) caching cannot hit regardless of markers.

根因

Anthropic prompt caching is opt-in per content block. OpenRouter forwards cache_control only when it is attached to a content part; a top-level cache_control or plain string content is ignored.

修复步骤

1. Send system/user content as an array of parts and attach {"type":"text","text":"...","cache_control":{"type":"ephemeral"}} to the large stable part.
2. Keep the cached prefix byte-identical between calls; minimum cacheable size is ~1024-2048 tokens depending on model.
3. First call shows cache_creation_input_tokens (write), second shows cached_tokens (read).

如何验证

Second identical request shows prompt_tokens_details.cached_tokens ≈ size of the marked block and cost drops ~90% on that portion.

试过没用的办法

Top-level cache_control in the request body; /v1/messages through some relays which strip cache_control during conversion.

风险提示

Cache writes cost 1.25x input on the first call.

验证范围

OpenRouter + anthropic/* models, 2026-10

何时失效

OpenRouter enables automatic caching for Anthropic (as some providers do).