Skip to main content
When you send the same long prefix — a big system prompt, a document, a tool catalog — on call after call, prompt caching lets the provider store that prefix and skip re-processing it next time. On Anthropic (Claude) models this is a real, billable feature: a cache read costs 0.1× the normal input price, so a reused prefix gets ~90% cheaper and comes back faster. It isn’t free, though. Writing the cache costs 1.25× input, and Anthropic’s cache entries expire after 5 minutes (extendable to 1 hour). So caching only pays off when the same prefix comes back within the cache lifetime. If your calls are minutes apart with no reuse, you’d pay the 1.25× write premium every time and never collect the discount. Because of that trade-off, Opper leaves prompt caching off by default and lets you turn it on per request. You decide, because only you know whether your prefix repeats.
This page is about Anthropic prompt caching. OpenAI and Gemini cache automatically, server-side, at no extra cost and with no flag — there’s nothing to enable. The cache_control field below is a no-op on those providers, so the same request stays portable across models.

​
Enable it: top-level cache_control

Add a top-level cache_control to the request body. Opper places a single moving breakpoint on the largest cacheable prefix and advances it as the conversation grows — the “automatic” mode, best for multi-turn chats and agent loops. 
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.opper.ai/v3/compat",
    api_key=os.environ["OPPER_API_KEY"],
)

resp = client.chat.completions.create(
    model="anthropic/claude-sonnet-4-6",
    messages=[
        {"role": "system", "content": LONG_STABLE_SYSTEM_PROMPT},
        {"role": "user", "content": "What changed in the latest revision?"},
    ],
    extra_body={"cache_control": {"type": "ephemeral"}},
)
The top-level field works on every Anthropic-routable compat endpoint: chat/completions, v1/messages, responses, openresponses, and the Google-shape interactions / generateContent.

​
Extend the lifetime to 1 hour

Add a ttl. Useful when your prefix is reused over minutes rather than seconds (a long research session, a slow agent). 
{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }

​
Precise placement: per-block cache_control

For fine control over exactly where the cached prefix ends, put cache_control directly on a content block instead of the top level. Anthropic allows up to four such breakpoints. This is the same syntax the Anthropic API uses natively, so existing code works unchanged. Per-block placement is supported on chat/completions (OpenAI shape) and v1/messages (Anthropic shape): 
resp = client.chat.completions.create(
    model="anthropic/claude-sonnet-4-6",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": BIG_DOCUMENT,               # cache everything up to here
                    "cache_control": {"type": "ephemeral"},
                },
                {"type": "text", "text": "Summarize the section on billing."},
            ],
        }
    ],
)
If you set both a top-level cache_control and explicit per-block breakpoints, the per-block breakpoints win — Opper won’t add its automatic one on top.

​
When it’s worth it

Turn it on

A large, stable prefix (system prompt, document, tool catalog) reused across back-to-back calls — agent loops, multi-turn chat, batch jobs over one context.

Leave it off

One-shot calls, or calls spaced further apart than the cache lifetime. You’d pay the 1.25× write premium with no read to recoup it.
Every response reports what actually happened via its usage: cache_creation_input_tokens (written at 1.25×) and cache_read_input_tokens (read at 0.1×). Watch those to confirm caching is paying off — reads should dominate writes once your prefix starts repeating.

​
Reference

  • Field: cache_control — top-level (automatic) or on a content block (explicit).
  • Value: { "type": "ephemeral" }, optionally "ttl": "1h" (default is 5 minutes).
  • Activates on: Anthropic-family models. No-op on OpenAI / Gemini (they cache automatically).
  • Pricing: cache write 1.25× input, cache read 0.1× input.
  • Breakpoints: up to 4 explicit per-block; or 1 automatic top-level.