Marking a prefix on Claude models
The gateway accepts the Anthropic-style marker in OpenAI-compatible format: write the messagecontent as an array of parts and put
"cache_control": {"type": "ephemeral"} on the content block where the
cacheable prefix ends — everything up to and including that block is cached. The gateway
forwards the marker to Anthropic (or AWS Bedrock for -bedrock variants)
unchanged. A message may carry the marker on its last content block only,
and a request may contain at most four markers.
- Minimum size. Each model has a minimum cacheable prefix (see the table below); shorter prefixes are processed normally with no error and no cache entry — the marker is silently ignored.
- Lifetime. Cache entries live for 5 minutes by default, refreshed on each hit — steady traffic keeps the prefix warm.
- Exact-prefix match. Reuse requires a byte-identical prefix up to the marker; put stable content (system prompt, documents) first and variable content after it.
Minimum cacheable prefix per model
Minimums differ by model and by route. In particular, AWS Bedrock enforces a higher 4,096-token minimum for Opus and Haiku than Anthropic’s direct API does — a prefix between 1,024 and 4,095 tokens that caches fine onclaude-opus-4-6 will get zero cache activity on
claude-opus-4-6-bedrock. This is an AWS-side constraint (verified against
Bedrock directly), not gateway behavior.
Placeholder Bedrock variants.
claude-fable-5-bedrock,
claude-opus-4-8-bedrock, and claude-opus-4-7-bedrock temporarily
serve via Anthropic’s direct API (see Bedrock-routed models),
so today their effective caching minimum is the direct-API 1,024 tokens.
Treat 4,096 as the stable planning number — it becomes exact when those IDs are re-pointed
to Bedrock, with no client change.Using the typed SDKs (cachePoint)
As of SDK v0.2.0, all five SDKs support prompt caching natively via a
Bedrock-style cachePoint content block. Place a cache point after the stable
prefix you want cached — in the system list, in message content,
or both. The SDK translates each cache point into the cache_control wire
marker on the preceding content part; the block itself is never sent. The same limits
apply: at most four cache points per request, and a cache point with nothing before it in
the same message is silently ignored.
Verifying and billing
Cache activity is reported in the responseusage object. On the wire the
fields are cache_creation_input_tokens (tokens written to the cache) and
cache_read_input_tokens (tokens served from it); the SDKs surface them under
the Bedrock names cacheWriteInputTokens and cacheReadInputTokens.
Both are metered per request in your usage reporting and billed at the premium write /
discounted read rates — a non-zero cache-read count confirms the cache is doing its job.
SDK note. Typed
cachePoint support requires
SDK v0.2.0 or later in every language. On OpenAI and Gemini models
caching is automatic — the marker is ignored there, so the same code runs unchanged
across providers.