Claude Prompt Caching Guide

If you’re using Claude Code, Cline, Cursor, or hand-rolling your own Claude API calls, Prompt Cache is the single biggest knob for lowering your bill — cached input tokens are billed at just 0.1×, a 90% discount. This page is based on Anthropic’s official documentation (platform.claude.com/docs/en/build-with-claude/prompt-caching) and adapted to APIYI’s setup with copy-paste-ready examples.

In one sentence

Mark a long, reused prompt prefix (system instructions / a long document / few-shot examples) with cache_control. The server stores it; on the next request with the same prefix, it skips reprocessing — roughly 10× cheaper and faster. It expires after a period of inactivity.

Why bother — read the multipliers

Relative to the model’s base input token price (1×):

Type	Price	Notes
Plain input	1×	Whatever isn’t cached, full price
Cache write (5-min TTL)	1.25×	First-time write costs 25% more
Cache write (1-hour TTL)	2×	Pay more to store longer
Cache read (hit)	0.1×	The whole point. 90% off thereafter

Break-even points:

5-min TTL: only 2 reuses of the same prefix to break even (1.25 + 0.1 = 1.35, cheaper than 2.0 for two uncached requests).
1-hour TTL: 3 reuses to break even (2 + 0.2 = 2.2, cheaper than 3.0).

TTL is a sliding window: every cache hit resets the expiration timer, so active conversations don’t expire from under you. Only true idleness beyond the TTL causes eviction.

Good fit

The same long system prompt called many times (agents, chatbots)
Multi-turn conversations (every prior turn becomes reusable prefix)
Batch processing of one document (asking 50 questions about one contract)
RAG, where stable retrieved chunks form the prefix

Bad fit

Every prompt differs from the first character onward
The whole thing is short and never crosses the per-model minimum (below)
Chat clients that re-assemble uploaded attachments on every turn (see “Images and files cache too” below)

The three hard requirements

All three are mandatory.

1. Explicit `cache_control` marker

content cannot be a plain string. It must be a content block array, with cache_control attached to the block you want cached:

# ❌ Wrong: plain string is never cached
"content": "a long passage..."

# ✅ Right: content block + cache_control
"content": [
    {
        "type": "text",
        "text": "a long passage...",
        "cache_control": {"type": "ephemeral"},
    },
    {"type": "text", "text": "the question"},
]

2. Length must clear the per-model minimum

If the content is shorter than the model’s minimum, it won’t be cached even with the marker (no error, just silently skipped). Verified against Anthropic’s official docs:

Minimum tokens	Models
512	Opus 5, Fable 5 / 5.1, Mythos 5
1,024	Opus 4.8, Sonnet 5, Sonnet 4.6, Sonnet 4.5, Sonnet 4, Opus 4.1, Opus 4
2,048	Opus 4.7, Haiku 3.5
4,096	Opus 4.6, Opus 4.5, Haiku 4.5

This threshold does not decrease monotonically with version number — don’t guess it. The most counterintuitive pairs: Opus 5 needs only 512, while the older Opus 4.6 / 4.5 need 4,096 — an 8× difference. Haiku 4.5 is also 4,096, which is higher than the older Haiku 3.5 (2,048). So neither “newer models have lower thresholds” nor “smaller models have lower thresholds” holds. Check the table whenever you switch models.

English text averages roughly 0.75 words per token. In practice: Opus 5 caches from about 380+ words of stable content, Sonnet 5 / Sonnet 4.6 need around 770 words, and Opus 4.6 / Haiku 4.5 need roughly 3,000 words before caching does anything. Always refer to Anthropic’s official docs for the latest thresholds — they can change between model versions.

Measured on APIYI (2026-07-29). We probed the write threshold with a fixed prefix stepped up in size: claude-opus-5 produced no cache write at 301 tokens but did at 614, bracketing the official 512; claude-sonnet-5 produced none at 612 but did at 1,250, bracketing the official 1,024. Both match the table above.

3. Prefix must match byte-for-byte

Caching is prefix-based: from the start of the request up to the cache_control marker, the byte stream must be identical to the previous request. Any single character change — whitespace, JSON key ordering, a timestamp — counts as a new prefix and triggers a fresh write instead of a hit. Practical rule: stable stuff up front, volatile stuff at the back.

# ❌ Wrong: question first means the prefix changes every turn; never hits
content = [
    {"type": "text", "text": "Please answer this question: " + question},  # volatile
    {"type": "text", "text": long_doc, "cache_control": {"type": "ephemeral"}},
]

# ✅ Right: long stable content first with marker, question after
content = [
    {"type": "text", "text": long_doc, "cache_control": {"type": "ephemeral"}},  # stable
    {"type": "text", "text": question},                                            # volatile
]

Minimal runnable example

Send two requests using the same long document but different questions. The first writes, the second hits:

import json, os, requests

URL = "https://api.apiyi.com/v1/messages"
KEY = os.environ["APIYI_API_KEY"]
HEADERS = {
    "content-type": "application/json",
    "x-api-key": KEY,
    "anthropic-version": "2023-06-01",
}

# Must be long enough. Sonnet 4.6 needs >= 1,024 tokens (~770+ English words).
LONG_TEXT = open("long_document.txt").read()


def ask(question: str, label: str):
    payload = {
        "model": "claude-sonnet-4-6",
        "max_tokens": 256,
        "messages": [{
            "role": "user",
            "content": [
                {"type": "text", "text": LONG_TEXT, "cache_control": {"type": "ephemeral"}},
                {"type": "text", "text": question},
            ],
        }],
    }
    r = requests.post(URL, headers=HEADERS, data=json.dumps(payload), timeout=120)
    u = r.json().get("usage", {})
    print(f"[{label}] input={u.get('input_tokens')} "
          f"write={u.get('cache_creation_input_tokens')} "
          f"read={u.get('cache_read_input_tokens')}")


ask("Summarize the main idea", "1st")  # expect write>0, read=0
ask("Give 3 keywords",        "2nd")    # expect write=0, read>0

Expected output:

[1st] input=35 write=6512 read=0
[2nd] input=22 write=0    read=6512

The second call’s read ≈ the first call’s write — the same prefix is being reused.

How to tell whether you hit — three usage fields

In every response, usage reports:

Field	Meaning	Billing multiplier
`input_tokens`	Uncached input tokens	1×
`cache_creation_input_tokens`	Tokens written to cache this call	1.25× or 2×
`cache_read_input_tokens`	Tokens read from cache this call	0.1×

Total input tokens = sum of all three. As long as cache_read_input_tokens > 0, you’re saving money.

A very useful self-check: on a real hit, this turn’s cache_read_input_tokens is exactly equal to the previous turn’s cache_creation_input_tokens — whatever went in last turn comes back as one block, and only this turn’s new content counts toward this turn’s write.So: read ≈ previous write means the whole prefix hit; read clearly smaller than the previous write means only an earlier portion hit — something in between changed, and that gap tells you where to look.

Most common pitfalls

Symptom	Cause
`write` always `0` or field missing	No `cache_control` marker / below the minimum threshold / used OpenAI-compatible format
2nd request still has `write > 0` and `read = 0`	Prefix changed. Common culprits: `datetime.now()`, UUIDs, rotating user IDs in the prompt; non-deterministic JSON serialization; timestamped system prompts
It worked, then a while later writes again	Idle beyond TTL. Use `{"type": "ephemeral", "ttl": "1h"}` for longer retention
Same prompt, different model — no hit	Caches are isolated per model. Switching models = new cache key
On Fable 5 / 5.1, one turn suddenly shows `read = 0` and the response `model` is `claude-opus-4-8` (or `claude-opus-5`), or `stop_reason` is `refusal`	Content-safety fallback / refusal fired. A fallback switches the model and therefore the cache key, so that turn cannot read the earlier cache; a cache written by a refused turn is not read back later. See the note below
Recent turns in a long conversation don’t hit	Max 4 `cache_control` breakpoints per request; each breakpoint only looks back 20 content blocks for prior cache entries
Conversation carries uploaded files or large images, hit rate swings wildly	Not a problem with Claude’s image/file caching — the client re-assembles attachments each turn and the prefix changes. See “Images and files cache too” below

Safety fallback on the Fable family breaks the cache. claude-fable-5 / claude-fable-5-1 ship with built-in safety classifiers. When a request hits high-risk content, the model either refuses (HTTP 200 with stop_reason: "refusal") or falls back to the Opus family, and the top-level model in the response faithfully echoes the model that actually answered. This is normal model-side behavior, not a gateway issue.Effect on caching: a fallback switches the model and therefore the cache key, so that turn cannot read what earlier turns wrote; hits resume once the next turn lands back on Fable. A refused turn may still report cache_creation_input_tokens, but that write is never read back later. In multi-turn agent sessions this shows up as isolated turns where read drops to 0 and write jumps back up.What to do: check the response model and stop_reason before judging a miss from usage alone; adjust a refused input before resending instead of retrying it verbatim; keeping the conversation content within policy is what minimizes these misses. Details on refusals, fallback and billing are in the Fable 5.1 launch notes.

Prompt Cache only works on the Anthropic native format (/v1/messages). When you call Claude through the OpenAI-compatible format (/v1/chat/completions), no cache fields will come back regardless of what you send. For Claude Code, Cline, Cursor and similar high-frequency clients, the native format is mandatory if you care about your bill.

Images and files cache too — but attachment scenarios hit less reliably

First, a common misconception: it is not that Claude’s caching of images/files is “unreliable.” Anthropic documents explicitly that text, images and documents can all enter the Prompt Cache, on equal terms. The real reason is the hard requirement above: caching matches the complete prefix of the request, and the bytes of an image or file are part of that prefix. Any change in how the client assembles attachments between turns breaks it. Anthropic also calls out one case specifically: changing whether a prompt contains an image invalidates the corresponding cache.

How the two scenarios differ

	Coding / plain text	Chat client + attachments
Typical shape	Fixed system prompt + code context + history appended at the end	Attachments (PDF / large images) possibly re-assembled each turn
How the prefix changes	Append-only; everything before stays byte-identical	Attachments re-uploaded / re-encoded, content block order or structure changes
Hit behavior	Stable — exactly what prefix caching is built for	Swings wildly

Coding clients like Claude Code, Cline and Cursor fall in the first column, which is why their hit rates are usually steady. GUI clients like Chatbox and Cherry Studio are equally steady for plain-text conversations — the hit rate only degrades when the conversation carries uploaded files or large image attachments.

Recovering the hit rate in attachment scenarios

Put attachments first, in a fixed order — they are the largest and most stable content, so the prefix is where they belong
Encode each attachment once and reuse that same base64; don’t re-read and re-encode the file every turn (re-encoding is not guaranteed to produce identical bytes)
Don’t reorder content blocks between turns, especially not “image first this turn, image last the next”
Put cache_control after the attachments so they land inside the cached prefix
Avoid adding or removing attachments mid-conversation — adding or dropping one image invalidates the entire prefix after it

When explaining this to a non-technical colleague or customer:Claude’s caching supports text, images and files alike. However, in clients like Chatbox, when a conversation includes uploaded files or larger image attachments, the way the client organizes those attachments and the surrounding context can change from turn to turn, so the effective cache hit rate is relatively unstable. In Coding scenarios, which are dominated by plain text and code context, the request context is typically stable, so cache hits are normal and fairly consistent.The value of putting it this way: it places the cause on how the client assembles the request, rather than leaving the impression that “Claude’s official image/file caching has a bug.”

Advanced: multi-turn conversations

Place cache_control on the last content block of the most recent user message. Each new turn auto-extends the cached read range up to the end of the previous turn:

# When constructing the Nth turn's request
messages[-1]["content"][-1]["cache_control"] = {"type": "ephemeral"}

Two hard limits to keep in mind:

At most 4 cache_control breakpoints per request.
Each breakpoint’s prefix lookup window is at most 20 content blocks back — anything older than that won’t be considered for a hit. In other words, in very long conversations, marking only the latest turn won’t cover the entire prior history.

A common pattern: place one breakpoint each on tool definitions, system prompt, long documents, and the latest conversation turn — using all 4 slots so that sections changing at different rates don’t invalidate each other’s cache.

On APIYI and caching

APIYI forwards cache fields end-to-end. The cache_control you send is passed through to upstream Claude (AWS Claude or Claude Official) as-is, and the returned cache_creation_input_tokens / cache_read_input_tokens are passed straight back to you — no special adaptation needed in your code.

How to self-verify:

On the first request, usage.cache_creation_input_tokens > 0 (write succeeded).
Within seconds, send the same prefix again — you should see usage.cache_read_input_tokens > 0 (hit).
Your billing dashboard will itemize cache writes and cache reads separately, at the same official multipliers (1.25× / 2× / 0.1×).

Recap

1. Mark it

cache_control: {"type": "ephemeral"} on a content block — plain-string content is never cached.

2. Long enough

Opus 5 ≥ 512; Sonnet 5 / Sonnet 4.6 ≥ 1,024; Opus 4.7 ≥ 2,048; Opus 4.6 / Haiku 4.5 ≥ 4,096 tokens, otherwise silently skipped.

3. Stable prefix

Stable up front, volatile in the back; one character of drift kills the hit.

4. Check usage

Only cache_read_input_tokens > 0 proves you actually saved money; it should roughly equal the previous turn’s cache_creation_input_tokens.

5. Keep attachments fixed

Images and files cache too, but re-assembling attachments each turn kills the prefix — put them first, keep the order, encode once.

Parent page: Claude API Basics
Client setup guides: Claude Code integration · Cherry Studio integration
Get / manage tokens: https://api.apiyi.com/token
Anthropic official docs: platform.claude.com/docs/en/build-with-claude/prompt-caching

Basics

Basic API

Image API (Official)

Video API (Official)

Multimodal Understanding API

Text Generation

Audio API (Official)

Retrieval & Safety

In one sentence

Why bother — read the multipliers

Good fit

Bad fit

The three hard requirements

1. Explicit `cache_control` marker

2. Length must clear the per-model minimum

3. Prefix must match byte-for-byte

Minimal runnable example

How to tell whether you hit — three usage fields

Most common pitfalls

Images and files cache too — but attachment scenarios hit less reliably

How the two scenarios differ

Recovering the hit rate in attachment scenarios

Advanced: multi-turn conversations

On APIYI and caching

Recap

1. Mark it

2. Long enough

3. Stable prefix

4. Check usage

5. Keep attachments fixed

​In one sentence

​Why bother — read the multipliers

​Good fit

​Bad fit

​The three hard requirements

​1. Explicit cache_control marker

​2. Length must clear the per-model minimum

​3. Prefix must match byte-for-byte

​Minimal runnable example

​How to tell whether you hit — three usage fields

​Most common pitfalls

​Images and files cache too — but attachment scenarios hit less reliably

​How the two scenarios differ

​Recovering the hit rate in attachment scenarios

​Advanced: multi-turn conversations

​On APIYI and caching

​Recap

1. Mark it

2. Long enough

3. Stable prefix

4. Check usage

5. Keep attachments fixed

​Related links

In one sentence

Why bother — read the multipliers

Good fit

Bad fit

The three hard requirements

1. Explicit `cache_control` marker

2. Length must clear the per-model minimum

3. Prefix must match byte-for-byte

Minimal runnable example

How to tell whether you hit — three usage fields

Most common pitfalls

Images and files cache too — but attachment scenarios hit less reliably

How the two scenarios differ

Recovering the hit rate in attachment scenarios

Advanced: multi-turn conversations

On APIYI and caching

Recap

Related links