Skip to contentOceanToken

7 min read

Claude Prompt Caching in Python: A Guide

Claude prompt caching in Python with the Anthropic SDK: where cache_control goes, model minimums, reading usage fields, and the mistakes that cause misses.

By OceanToken Team

Claude Prompt Caching in Python: A Guide

Editor's note: Prompt caching is the biggest cost lever most Claude apps leave off. Any app that resends a long, stable prefix within a few minutes should use it, and should prove it works by reading the usage fields, not by assuming. We'd also put it ahead of shopping for a cheaper route: caching depends on how you lay out the request, and no rate card does that part for you.

Short answer: For Claude prompt caching in Python, use the Anthropic SDK, put cache_control: {"type": "ephemeral"} on the last block of the stable part of your prompt (tools, system, long documents), keep that prefix byte-identical between calls, and check cache_read_input_tokens in response.usage. The OpenAI-compatible route doesn't support caching, per Anthropic.

Article map: What this article covers, step by step

How the mechanism works

Anthropic's prompt caching docs  say a cache covers the whole prompt in a fixed order, tools, then system, then messages, up to and including the block you mark with cache_control. On the next request the API looks for a matching prefix, checking at most 20 positions back from each breakpoint. You can set up to four breakpoints, which helps when sections change at different rates, for example tools that never change and a document that changes daily.

The default lifetime is five minutes, refreshed at no extra cost each time the entry is read. You can ask for one hour with "ttl": "1h". Writes cost more than plain input and reads cost much less: Anthropic lists a 5-minute write at 1.25 times the base input price, a 1-hour write at 2 times, and a read at 0.1 times, with reads at 0.05 times on Claude Opus 5.5 and Sonnet 5.5.

Minimum sizes matter more than people expect. Anthropic's table, checked November 8, 2026:

Minimum cacheable prompt Models
512 tokens Opus 5.5, Sonnet 5.5, Haiku 5.5, Opus 5, Fable 5.1, Fable 5
1,024 tokens Opus 4.8, Sonnet 5, Sonnet 4.6, Sonnet 4.5
2,048 tokens Opus 4.7
4,096 tokens Opus 4.6, Opus 4.5, Haiku 4.5

A shorter prefix is processed without caching, and no error is returned. That silence is the most common reason someone turns caching on and sees nothing change.

Step by step

Use the Anthropic SDK, not the OpenAI one. Anthropic's OpenAI SDK compatibility page  says prompt caching is not supported there and points to the Anthropic SDKs instead.

import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.oceantoken.ai",       # Anthropic SDK: no /v1
    api_key=os.environ["OCEANTOKEN_API_KEY"],
)

POLICY = open("support_policy.md").read()      # several thousand tokens, rarely changes

def ask(question: str) -> str:
    resp = client.messages.create(
        model="anthropic/claude-opus-5.5",
        max_tokens=400,
        system=[{
            "type": "text",
            "text": POLICY,
            "cache_control": {"type": "ephemeral"},   # breakpoint after the stable part
        }],
        messages=[{"role": "user", "content": question}],
    )
    u = resp.usage
    print(u.input_tokens, u.cache_creation_input_tokens, u.cache_read_input_tokens)
    return resp.content[0].text

ask("How do refunds work?")        # expect cache_creation_input_tokens > 0
ask("What about subscriptions?")   # expect cache_read_input_tokens > 0

The question goes after the breakpoint because it changes every call. If you're calling Anthropic directly, drop base_url and use Anthropic's id, claude-opus-5-5.

Reading the usage fields

Field Meaning
input_tokens Tokens after the last breakpoint, neither read from nor written to cache
cache_creation_input_tokens Tokens written to the cache on this call
cache_read_input_tokens Tokens served from the cache

Anthropic gives the total input as the sum of all three. People often read input_tokens alone, see a small number, and think the request shrank, when it only counts the uncached tail. If cache_read_input_tokens stays at zero on the second call, caching isn't happening. Print the fields; don't guess.

Claude prompt caching in Python with automatic caching

For multi-turn chat there is a simpler option. Anthropic documents automatic caching: put one cache_control at the top level of the request and the system places the breakpoint on the last cacheable block and moves it forward as the conversation grows.

resp = client.messages.create(
    model="anthropic/claude-opus-5.5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a support assistant.",
    messages=history,
)

It uses one of the four breakpoint slots. We'd still mark long, stable blocks explicitly, such as tool definitions or a reference document, because you then know exactly what is cached and can see it in the usage fields.

Worked example: when it pays

Take a 10,000-token prefix used 50 times within five minutes on Opus 5.5. You pay one write at 1.25 and 49 reads at 0.05, which is 3.7 prefix-equivalents instead of 50. Even two uses come out ahead: 1.25 plus 0.05 is 1.3 against 2. The 1-hour cache costs 2 to write, so it needs a third use within the hour to beat sending the prefix uncached. These are ratios from Anthropic's published multipliers, not prices; check the multiplier for your model before you plan around them.

Diagram: Is caching this prefix worth it?

Common mistakes

A timestamp or user name before the breakpoint. One changed character in the prefix breaks the match. Move anything per-request after the breakpoint.

Changing tool definitions. Anthropic's invalidation table says modifying tool names, descriptions or parameters invalidates the entire cache, since tools come first. Serialise tools in a stable order, and don't rebuild the list with a different key order on each request. Changes to tool_choice, images or thinking settings also invalidate the message-level cache.

A prefix under the minimum. 400 tokens never caches on any current model. Check the table above before debugging anything else.

Parallel first calls. Anthropic says a cache entry only becomes available after the first response starts. Fifty requests fired at once all pay the write. Send one warm-up call, wait for it to start returning, then fan out.

Traffic gaps longer than the TTL. If calls arrive more than five minutes apart, every call is a fresh write. Use the 1-hour TTL, or batch the work closer together.

Assuming the route passes it through. Confirm that the route you use, OceanToken included, forwards cache_control and returns the cache fields; no OceanToken doc we checked confirms it either way, so treat it as something to test. The two-call script above is that test. For the wider trade-offs between calling Anthropic directly and using a multi-model endpoint, see Claude API: Anthropic direct vs gateway.

Monitoring in production

Track three numbers per endpoint. Cache read ratio, which is read tokens over total input tokens, tells you how much of your prompt is actually reused. Write amplification, creation tokens over read tokens, tells you whether you keep paying write premiums for prefixes nobody reads again; if it is high, shrink the cached region to what is truly shared or lengthen the TTL. Cold-start share, the fraction of calls with zero cache reads, tells you whether traffic gaps are expiring your cache. Anthropic also notes that cache hits are not deducted against your rate limit, so a good read ratio buys throughput as well as savings.

How to test this on your workload

We haven't published measurements for this guide. Run these against your own prompts:

  1. Run the two-call script and record all three usage fields on each call.
  2. Shorten the cached block below your model's minimum and confirm cache_creation_input_tokens drops to zero with no error.
  3. Add a timestamp before the breakpoint and watch reads stop.
  4. Fire five parallel first calls, then repeat with one warm-up call first, and compare write tokens.

Our take: Cache first, compare routes second. Put stable content first and mark its last block, keep per-request text after it, and log the three usage fields from day one. A cache you haven't seen in usage doesn't exist.

Running it on OceanToken

Use the Anthropic SDK with base URL https://api.oceantoken.ai (no /v1) and model anthropic/claude-opus-5.5; the /claude-api page says Claude models answer on the Anthropic Messages API there, and the Claude Opus 5.5 model page lists prompt caching, billed at the official price. One API key and one prepaid balance also reach the other model families through the OpenAI-compatible base URL https://api.oceantoken.ai/v1, with no subscription, and each key can have its own spending limit, which is useful for keeping a caching experiment bounded. Run the two-call test first and confirm the cache fields come back on your route. See the current rate on /claude-api.

FAQ

Do I need a beta header for prompt caching? The current docs show cache_control with type ephemeral and an optional ttl with no beta header; check the caching page if you use an older SDK.

Can I cache tool definitions and images? Yes. Blocks in tools, system and messages can carry a breakpoint, but changing tools invalidates the whole cache.

How do I know a cache hit happened? cache_read_input_tokens is greater than zero in response.usage.

Why is nothing cached even with cache_control set? Usually the prefix is under the model's minimum, which fails silently, or something before the breakpoint changes between calls.

Does caching work with the OpenAI SDK? Anthropic says prompt caching is not supported on its OpenAI compatibility layer. Use the Anthropic SDK.

Sources

  1. Anthropic: prompt caching  (checked 2026-11-08)
  2. Anthropic: OpenAI SDK compatibility  (checked 2026-11-08)
  3. Anthropic: models overview  (checked 2026-11-08)
  4. OceanToken Claude API page (checked 2026-11-08)
  5. OceanToken Claude Opus 5.5 model page (checked 2026-11-08)
  6. OceanToken docs: text generation  (checked 2026-11-08)

Get your OceanToken API key

  1. Create an OceanToken account and an API key.
  2. Copy the snippet below, paste your key, and run it.
  3. Check the current rate on /claude-api.
curl https://api.oceantoken.ai/v1/messages \
  -H "Authorization: Bearer $OCEANTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "anthropic/claude-opus-5.5", "max_tokens": 400, "system": [{"type": "text", "text": "Long stable instructions go here.", "cache_control": {"type": "ephemeral"}}], "messages": [{"role": "user", "content": "Hello"}]}'

Get API Key 

  • Claude
  • Tutorial
  1. 7 min read

    A Unified API for Chat, Image and Video

    Building on a unified API for chat, image and video: sync vs async calls, billing units, retries, timeouts and storage, with three calls and a launch checklist.

    • AI video
    • LLM API
    • Tutorial
  2. 7 min read

    Kimi K3 API International Access Guide

    Use the Kimi K3 API internationally: sign up with email, pay by card, create one key and call moonshotai/kimi-k3 with an OpenAI SDK. Steps, code and checks.

    • Kimi
    • LLM API
    • Tutorial
  3. 6 min read

    Call Tencent Hy3 With the OpenAI SDK

    Call Tencent Hy3 with the OpenAI SDK outside China: base URL, model id, streaming, tool calls, reasoning_effort values, Hy3 vs Hy3 preview, and token billing.

    • Hunyuan
    • LLM API
    • Tutorial