Loading...

Docs · Routes and pricing

Prompt caching: the automatic Claude cache and how to turn it off

TopxAI turns on Claude’s five-minute prompt cache when a request sets none. How cache reads and writes are billed, and the header that declines it.

A prompt cache lets a model reuse the start of a prompt it has just seen. The repeated part is billed at the cache-read price, far below the input price; storing it the first time is billed at the cache-write price, a little above it. Every model page lists both lanes.

Claude: on by default

When a Claude request carries no cache setting of its own, TopxAI turns on Claude's automatic five-minute cache before forwarding it. This applies to /v1/messages, /v1/chat/completions and /v1/responses alike, so a client that knows nothing about caching still gets it.

A cache setting you send yourself always wins: a top-level cache_control, or a breakpoint on a system block, a tool or a message block, keeps its position and its TTL, including a one-hour cache. TopxAI then adds nothing.

On Claude a cache read costs 5% of the input price on Opus 5.5 and Sonnet 5.5 and 2.5% on Fable 5.2. A five-minute cache write costs 1.25 times the input price and a one-hour write twice the input price.

A provider sometimes keeps part of a long prompt for an hour on its own and reports those writes as one-hour writes. From the release on 2026-11-19 at 14:40 UTC they bill at the duration your request asked for: at the input price when the request set no cache and declined TopxAI's automatic one, and at the five-minute price when it asked for five minutes, TopxAI's automatic cache included. Only a request that asks for a one-hour cache pays the one-hour price. Later reads of that cache bill at the cache-read price as usual. Before that release these writes were charged at the one-hour price.

Turning it off for one request

A prompt sent only once gains nothing from the cache: it is billed as a cache write that is never read. Send the header below on such requests and TopxAI leaves the default out:

curl https://api.topxai.xyz/v1/messages \
  -H "x-api-key: $TOPXAI_API_KEY" \
  -H "X-TopxAI-Prompt-Cache: off" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-5-5", "max_tokens": 256, "messages": [{"role": "user", "content": "Name this chat in four words."}]}'

The header works on all three endpoints. Only the value off turns the default off; any other value leaves it on. Breakpoints you set in the request are kept either way. TopxAI Desktop sends the header for its one-off prompts, such as chat titles.

Other models

What caching does not promise

A cache hit depends on the provider: the same model, the same leading text and a request inside the cache lifetime. A miss costs nothing extra; the tokens bill as ordinary input. Settlement uses the input, cache-read, cache-write and output tokens the provider reports, so the usage log shows exactly what was cached. The worked example in How requests are billed adds up a run of cached requests.

Models: claude-fable-5-2, claude-sonnet-5-5, claude-opus-5-5 · Models & pricing

Related

Previous: Web search: which models search and what a search costs · Next: Jev (TypeSafe System One)

Other languages: 简体中文