Prompt Caching Usage and Billing

Using Claude Prompt Caching on 1折AI: how to enable it, minimum length, how to confirm a hit, how hits are billed, and Claude Code's caching behavior.

Prompt Caching lets the long prefix you send repeatedly (system prompt, tool definitions, long documents, conversation history) be billed as a write only the first time, and as a read thereafter. On this site, cache reads and cache writes are billed at official list prices, without the input/output discount applied. Per-model cache unit prices are listed in Models and Pricing.

Bottom line first

Claude Code has caching enabled by default; it takes effect as soon as you connect.
When calling from your own code, add cache_control to the content block you want cached, using the native /v1/messages. The OpenAI-compatible interface currently does not cache.
To determine whether a hit occurred, check only whether the response’s usage.cache_read_input_tokens is greater than 0.
The cache lives for 5 minutes by default, and each hit resets the timer. You can also use "ttl": "1h" to write a 1-hour cache, at a higher write price.

How to enable it

Add "cache_control": {"type": "ephemeral"} to a content block in system, tools, or messages; that block and everything before it will be cached. A single request can have at most 4 cache breakpoints.

1
curl https://1zheai.com/v1/messages \
2
  -H "x-api-key: $ONEZHE_API_KEY" \
3
  -H "anthropic-version: 2023-06-01" \
4
  -H "content-type: application/json" \
5
  -d '{
6
    "model": "claude-sonnet-5-5",
7
    "max_tokens": 256,
8
    "system": [
9
      {
10
        "type": "text",
11
        "text": "这里放一段很长、每次都一样的内容：项目说明、代码规范、参考文档……",
12
        "cache_control": {"type": "ephemeral"}
13
      }
14
    ],
15
    "messages": [{"role": "user", "content": "根据上面的规范，审查这段代码：..."}]
16
  }'

If the prefix to be cached is too short, the request is processed normally but simply not cached, and no error is raised. The minimum length varies by model; see the table below.

Minimum cacheable length

The following comes from Anthropic’s official documentation (2026-10-14):

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

Confirming a hit

Send the same request twice (no more than 5 minutes apart) and compare the usage of both. Below are actual results measured on 2026-10-15 with claude-sonnet-5-5, with about 18,000 tokens of fixed text in the system:

第一次：写入缓存
第二次：命中缓存

{
  "input_tokens": 23,
  "cache_creation_input_tokens": 17920,
  "cache_read_input_tokens": 0,
  "cache_creation": {"ephemeral_5m_input_tokens": 17920, "ephemeral_1h_input_tokens": 0},
  "output_tokens": 4
}

{
  "input_tokens": 23,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 17920,
  "cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0},
  "output_tokens": 4
}

If the second cache_read_input_tokens is greater than 0, the cache is being read. The cache write and read tokens for each call also appear in the Token column of the call log, with reads recorded as “cache↓” and writes as ”↑”.

How it is billed

Type	Official unit price	1折AI unit price
Cache write (5 minutes)	Input price × 1.25	Official list price, no discount
Cache write (1 hour)	Input price × 2	Official list price, no discount
Cache read	Input price × 0.1 (0.05 for Opus 5.5 and Sonnet 5.5, 0.025 for Fable 5.1)	Official list price, no discount

The official price for a 5-minute cache write is typically 1.25 times the official input price. On this site, input has a discount but caching does not, so you cannot use the official multiplier to conclude that a single cache read pays for itself; you need to compare the model discount, write cost, and number of repeated reads. Full worked examples are in Pricing and Billing.

1-hour cache

Add "ttl": "1h" to cache_control, and the cache will be retained for 1 hour — suitable for prefixes with intervals over 5 minutes that are still used repeatedly:

1
"cache_control": {"type": "ephemeral", "ttl": "1h"}

Writes are billed at 2 times the official input price, not the discounted input price; reads are the same as the 5-minute cache. The written tokens appear in cache_creation.ephemeral_1h_input_tokens of the response. Whether to choose the 1-hour cache should be judged based on the interval between the two requests, the write cost, and the number of repeated reads.

Claude Code’s caching

Claude Code automatically places cache breakpoints on the system prompt, tool definitions, and conversation history; the official explanation is here. To make it hit better:

Keep working continuously within one session; don’t stop for long in the middle. The cache expires if unused for 5 minutes.
Subsequent requests in the same session will read the cache. Measured on 2026-10-15, for a two-round Claude Code task, the second round read 31,440 cache tokens and wrote 115 tokens. When starting a new session, the first round may need to rewrite the entire prefix (measured at about 30,000 tokens), and that call will be more expensive than later ones.
Avoid changing CLAUDE.md, switching MCP servers, or changing models mid-session; all of these change the prefix.
Do not set DISABLE_PROMPT_CACHING=1; this environment variable turns off caching for all models.

Can the OpenAI-compatible interface use caching?

Currently, no. Measured on 2026-10-15, with about 3,100 tokens of fixed text in the system message of /v1/chat/completions, sent twice in a row, whether or not cache_control was added to the content block, both responses’ usage were:

1
{"prompt_tokens": 3167, "completion_tokens": 4, "total_tokens": 3171}

There is no prompt_tokens_details.cached_tokens, and the cache reads and writes in the call log are both 0; the entire request is billed at the input price. For scenarios that need caching, please use /v1/messages (Anthropic SDK or Claude Code).

FAQ

Why do I only ever see cache_creation and never cache_read?

The cache was written, but the next request did not read it. Troubleshoot in order: were the two requests more than 5 minutes apart; is the content before the breakpoint byte-for-byte identical (timestamps and random IDs in the system make it different every time); was the model changed; did the prefix reach the minimum length above.

Can I see the cache hit rate?

The cache read and cache write tokens for each call are in the call log, so you can calculate it yourself: cache reads ÷ (input + cache writes + cache reads).