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

Problem

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.

Error (redacted / normalized)

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

Applies when

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

Confirm it is this problem

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.

Not this when / boundary

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.

Root cause

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.

Fix

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).

How to verify

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

What did not work

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

Risks

Cache writes cost 1.25x input on the first call.

Verified scope

OpenRouter + anthropic/* models, 2026-10

Becomes obsolete when

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