---
title: "Prompt Caching Usage and Billing"
description: "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."
headingIds: {"Bottom line first":"section-1","How to enable it":"section-2","Minimum cacheable length":"section-3","Confirming a hit":"section-4","How it is billed":"section-5","1-hour cache":"section-6","Claude Code’s caching":"section-7","Can the OpenAI-compatible interface use caching?":"section-8","FAQ":"section-9"}
---

<aside className="docs-publication" data-pagefind-ignore>

Documentation maintained by [1ZheAI](https://1zheai.com/en/editorial/#publisher). [Sources and corrections](https://1zheai.com/en/editorial/).

Found an error? [Contact support](mailto:support@1zheai.com) with the page address and a description. Do not send API keys or account credentials.

</aside>
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](https://1zheai.com/en/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.

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

<Note>

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.

</Note>

## Minimum cacheable length

The following comes from [Anthropic's official documentation](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) (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:

<CodeGroup>
```json title="第一次：写入缓存"
{
  "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
}
```
```json title="第二次：命中缓存"
{
  "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
}
```
</CodeGroup>

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](/en/docs/usage-logs/), 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](/en/docs/pricing-explained/).

### 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:

```json
"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](https://code.claude.com/docs/zh-CN/prompt-caching). 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:

```json
{"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

<AccordionGroup>
<Accordion title="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.

</Accordion>
<Accordion title="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).

</Accordion>
</AccordionGroup>