Prompt Caching Parameters Across Providers

TL;DR: The prompt caching API parameter you set is different on every vendor: Anthropic uses cache_control with a 5-minute or 1-hour TTL, OpenAI reports cached_tokens and, on GPT-5.6, now charges for cache writes it used to give away free, and Gemini caches automatically by default with a separate opt-in resource for manual control. All three cut input costs by roughly 90% on a hit, provided your prompt structure actually produces one.

What actually happens when an API "caches" your prompt?

Every major provider now lets you skip reprocessing a prompt prefix you've already sent, but "caching" means three different mechanisms wearing one name. OpenAI's own framing is the cleanest starting point: "Prompt caching reuses work when requests share the same prompt prefix" by preserving the model's intermediate key-value state instead of the raw tokens. Anthropic frames the same idea from the cost side: "Prompt caching optimizes your API usage by allowing resuming from specific prefixes in your prompts. This significantly reduces processing time and costs for repetitive tasks or prompts with consistent elements."

The part that actually matters for your bill and your bug reports isn't the concept: it's the parameter shape, and that shape is not portable between vendors. A parameter name, a default TTL, or a minimum token count that's correct on one API tells you nothing about another's. The rest of this piece verifies each one against its own current documentation rather than treating "prompt caching" as a single interchangeable feature. (If you're after every documented parameter rather than caching specifically, our LLM parameter cheat sheet covers the wider set in one page.)

How does Anthropic's cache_control parameter work, and what does it cost?

Anthropic gives you two ways to opt in, both through the same field. Automatic caching adds a single cache_control object at the top level of a request: "Add a single cache_control field at the top level of your request. The system automatically applies the cache breakpoint to the last cacheable block and moves it forward as conversations grow." Explicit breakpoints do the same thing per content block, letting you cache up to four independent sections, useful when your tools rarely change but your context updates daily.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": "You are a documentation assistant with a large, stable knowledge base.",
  "messages": [{ "role": "user", "content": "Summarize section 4." }]
}

"ephemeral" is currently the only supported cache type, and it carries a default 5-minute lifetime that Anthropic's docs describe with a nuance most teams miss: "The lifetime is measured from the start of the request that writes or reads the cache entry, not from the end of its response. Time spent generating a response counts against the lifetime: if a response takes 4 minutes to stream, a follow-up request that reuses the same cached prefix must start within about 1 minute of that response completing." A slow generation quietly eats into your caching window.

If 5 minutes is genuinely too short for your traffic pattern, add "ttl": "1h" inside the same object for a 1-hour cache at extra cost. Anthropic's pricing page states the multipliers directly: 5-minute cache writes cost 1.25 times the base input price, 1-hour writes cost 2 times base, and cache reads cost 0.1 times base, with one documented exception: "Cache hits and refreshes on Claude Fable 5.1 and Claude Mythos 5.1 are priced at 0.025x the base input price." On Claude Sonnet 5 that 0.1x multiplier works out to $0.20 per million cached-read tokens against a $2 base input rate, per Anthropic's published table.

Minimum cacheable length varies by model in a way that isn't intuitive: Claude Opus 5 needs only 512 tokens to qualify, Claude Sonnet 5 needs 1,024, and Claude Haiku 4.5 needs 4,096. Fall short and nothing errors; the request is simply processed without caching, so check cache_creation_input_tokens and cache_read_input_tokens in the response rather than assuming your cache_control field did anything.

How does OpenAI's cached-token pricing actually work in 2026?

OpenAI enables prompt caching by default with no parameter required for the basic case: "Prompt caching is enabled by default for supported OpenAI models." The savings are advertised plainly: "Cheaper input tokens: Pay the model’s reduced cached-input rate for reused tokens, discounted up to 90%." Where it gets more complicated is that the mechanism itself changed with GPT-5.6.

On GPT-5.6 and later, OpenAI's docs describe an explicit mode alongside the automatic one: set prompt_cache_options.mode to "explicit" and mark a content block with prompt_cache_breakpoint, giving up to four cache writes per request. And the pricing on this generation is new: cache writes are no longer free.

{
  "model": "gpt-5.6",
  "prompt_cache_key": "support-bot-v3",
  "prompt_cache_options": { "mode": "implicit", "ttl": "30m" }
}

OpenAI's own arithmetic spells out the tradeoff: "For GPT-5.6 and later, cache writes cost 1.25× the standard, uncached input-token rate. It is worth incurring this charge when a prefix will be reused, because subsequent reads cost only 0.1× that rate. Writing a prefix once and fully reusing it once costs 1.35× its ordinary input cost, compared with 2× for processing it twice without caching." That's a meaningfully different model from earlier generations, where "No additional cache-write charge" applied and only the read side carried a discount.

Cache lifetime also splits by generation. GPT-5.6 uses prompt_cache_options.ttl, whose "only supported value, 30m, is also the default." Earlier models use a separate prompt_cache_retention parameter: in_memory entries "typically remain active for around 5 to 10 minutes of inactivity, up to one hour", while 24h retention "typically keeps entries available for around 30 minutes and can retain them for up to 24 hours." Which one applies by default depends on your organization's Zero Data Retention setting, not on anything you choose per request. The minimum cacheable prefix is 1,024 visible input tokens on GPT-5.6 and 2,048 on everything older, and hidden system tokens don't count toward that floor on either generation. Check usage.input_tokens_details.cached_tokens in the response to confirm a hit actually happened.

How does Google Gemini's context caching differ from the other two?

Gemini splits caching into two genuinely separate systems rather than one parameter with options. Implicit caching needs nothing from you: "Implicit caching is enabled by default for all Gemini 2.5 and newer models." Google is explicit that no setup step exists: "We automatically pass on cost savings if your request hits caches. There is nothing you need to do in order to enable this." The minimum token count to even qualify differs by model: 4,096 tokens for Gemini 3.8 Flash and every other Gemini 3.x model, 2,048 for Gemini 2.5 Flash and Gemini 2.5 Pro. You confirm a hit by checking usage.total_cached_tokens in the SDK response. (Caching aside, if you're pushing Gemini toward its full million-token window, our Gemini long-context guide covers the actual ceiling, per-modality placement rules, and document limits in depth.)

Explicit caching is a different, opt-in API surface entirely: the cachedContents.create resource, where you supply a model, the contents to persist, and a ttl; Google's own reference examples set that field to values like "300s" and "7200s" (five minutes and two hours), with no single fixed default stated in the API reference itself.

cache = client.caches.create(
    model="gemini-3.7-flash",
    config=types.CreateCachedContentConfig(
        contents=[document],
        system_instruction="You are an expert analyzing transcripts.",
        ttl="3600s",
    ),
)

An explicit cache also bills separately from the per-token discount: Google's current pricing page lists a distinct hourly storage rate on top of the cached-token price: $0.50 per million tokens per hour for Gemini 3.8 Flash, $4.50 per million tokens per hour for Gemini 2.5 Pro, both figures live as of September 2026 and both scheduled to change on January 1, 2027. Once a token is served from cache, the exact per-model pricing tables show roughly a 10x reduction: Gemini 3.8 Flash drops from $0.75 to $0.075 per million tokens, and Gemini 2.5 Pro drops from $1.25 to $0.125. That's a sharper discount than the qualitative figure in Google's own long-context guide, which describes the saving more loosely as "~4x less than the standard input / output cost" for Gemini Flash; the two pages don't reconcile, and the exact per-model pricing table is the more precise number to plan a budget around. When you use explicit caching specifically, the served response reports the count in a differently-named field again: cachedContentTokenCount inside usageMetadata, described in Google's API reference as "Number of tokens in the cached part of the prompt (the cached content)".

Does prompt order actually determine whether you get a cache hit?

Yes, on every provider covered here, and this is where most wasted cache-write charges actually come from. Anthropic's docs walk through the exact failure mode: a system context block followed by a per-request block containing a timestamp, with the breakpoint placed on the timestamped block. "The timestamp differs, so the prefix hash at block 6 differs. The lookback walks through blocks 5, 4, 3, 2, and 1, but the system never wrote an entry at any of those positions. No cache hit. You pay for a fresh cache write on every request and never get a read." The fix, in Anthropic's own words, is structural: "Move cache_control to block 5, the last block that stays the same across requests, and every subsequent request reads the cached prefix." Anthropic's lookback only checks 20 blocks back from a breakpoint, so a conversation that grows by more than 20 blocks per turn needs a second, closer breakpoint or it will miss its own prior cache write.

OpenAI's mechanism works the same way in spirit: a request looks backward through eligible breakpoints for the longest matching prefix, so anything you change ahead of your reusable content (a different tool schema, a different reasoning.effort, a different text.verbosity) can break the match even if the reusable block itself never changed. Gemini's guidance for its automatic caching is the least technical of the three but points at the identical rule: "Try putting large and common contents at the beginning of your prompt" and "Try to send requests with similar prefix in a short amount of time".

The pattern is the same across all three parameter sets even though the mechanics differ: put your large, stable, reused content first (system instructions, tool definitions, reference documents) and put anything that changes per request, including timestamps and the live user message, last. Get that ordering wrong and the caching parameter you set does nothing except add a write charge you never recover.

A caching readiness checklist before you ship

Before assuming a caching parameter is saving you money, confirm each of these against the response your API actually returns, not against the request you sent:

1. Does your prompt meet the model's minimum cacheable length?
   (Anthropic: 512-4,096 tokens by model. OpenAI: 1,024 on GPT-5.6+, 2,048 earlier.
   Gemini: 2,048-4,096 by model, implicit; no stated minimum for explicit caching.)

2. Is the content before your cache breakpoint byte-identical across requests?
   Timestamps, request IDs, and reordered JSON keys all break the match silently.

3. Did you check the actual usage field, not just add the parameter?
   Anthropic: cache_creation_input_tokens / cache_read_input_tokens
   OpenAI: usage.input_tokens_details.cached_tokens
   Gemini: usage.total_cached_tokens (implicit) or cachedContentTokenCount (explicit)

4. Does your TTL match your real request cadence?
   A 5-minute or 30-minute cache that expires between real requests
   pays the write cost every single time and never earns a read.

None of the three vendors returns an error when a cache attempt fails quietly: the request just processes as if caching were never requested. That silence is the actual risk: a cache_control field or a prompt_cache_options block that looks correct in your code can sit there doing nothing for months, and the only way to know is to read the number the API sends back.

If your next question is what to do with the tokens you're not caching (how to structure roles, temperature, or output shape), that's outside what a caching parameter controls. For sampling settings like temperature and top-p, see our guide to temperature, top-p, and top-k; for where system, developer, and user messages go, see system, developer, and user roles. A companion piece covering every provider's sampling settings specifically is in progress.