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
- OpenAI models cache automatically on the provider's side. TopxAI does not forward a cache TTL (
prompt_cache_optionsor aprompt_cache_breakpointininput), so every write is the default kind and bills at the listed cache-write price. - Grok 4.7 caches automatically and bills cached tokens at its cache-read price; it has no cache-write lane.
- The GLM, Kimi and DeepSeek models on private deployments cache automatically and bill cached tokens at the cache-read price, with no cache-write lane on their main deployment. The Abliterated models' requests start with TopxAI's fixed deployment note, so that part of the prompt is usually a cache hit (how requests are billed).
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
- How requests are billed
- Claude Code with TopxAI: ANTHROPIC_BASE_URL and the key
- Reading your usage log
- Claude Fable 5.2 API pricing
- Claude Sonnet 5.5 API pricing
- Claude Opus 5.5 API pricing
Previous: Web search: which models search and what a search costs · Next: Jev (TypeSafe System One)
Other languages: 简体中文