DeepSeek V4 context caching: how the discount actually works.

Quick answer: automatic, prefix-based, best-effort.

DeepSeek's context caching requires no code changes: the docs state the disk-based cache is enabled by default for all users. When a new request arrives, the system checks whether its prompt begins with a prefix it has already processed; matched tokens bill at the cache-hit rate and skip recomputation, unmatched tokens bill at the standard rate. Every response reports the split in two usage fields, prompt_cache_hit_tokens and prompt_cache_miss_tokens, so the discount is observable per request rather than taken on faith. The vendor is explicit about the limits: matching is against complete cache prefix units, partial overlaps do not count, unused cache entries are cleared automatically within hours to days, and the whole system is best-effort with no guaranteed hit rate. Caching changes what repeated context costs; it does not change what to send.

The mechanics, as DeepSeek documents them.

The design is why prompt ordering matters so much on this family: everything stable belongs at the front of the prompt, everything volatile at the back, because the first difference between two requests ends the matched prefix.

• Cache units are created at specific points: the docs describe each request producing cache prefix units at the end of the user input and the end of the model output, with additional units carved at fixed token intervals on long inputs and outputs.
• Hits require full matching: a later request hits only where it fully matches a stored prefix unit from the start of the prompt. A single changed byte early in the prompt invalidates everything after it.
• Storage is temporary: entries no longer in use are cleared automatically, usually within a few hours to a few days per the docs, so caching rewards active workloads rather than archival ones.
• Accounting is explicit: prompt_cache_hit_tokens and prompt_cache_miss_tokens in the usage block sum to your prompt tokens, making hit rate a metric you can log and alert on.
• No guarantees: the docs describe the system as best-effort. Correct behavior does not depend on hits; only the bill does.

The published rates, and what they mean at workload scale.

As published in DeepSeek's API docs in July 2026: V4 Flash bills $0.14 per million input tokens on a cache miss and $0.0028 on a hit, a 50x reduction; V4 Pro bills $0.435 on a miss and $0.003625 on a hit, roughly 120x. Output pricing is unaffected by caching. Worked example at those rates: an agent run of 50 steps, each resending a stable 20K-token prefix (system prompt, tools, accumulated plan). Without caching, that is 1M input tokens at the miss rate, about $0.14 on Flash. With a 90% hit rate on the prefix, 100K tokens bill as misses and 900K as hits: roughly $0.0165, an 8.5x reduction on the input side of the run. On Pro the same shape falls from about $0.435 to $0.047. Long-running chats, document-QA sessions, and few-shot-heavy batch jobs follow the same curve, because all of them resend a large unchanged prefix every request.

What carries through a gateway, honestly.

Context caching is upstream behavior: it lives on DeepSeek's serving infrastructure, not in your SDK or in any middle layer. Three consequences follow for gateway traffic, and they are worth stating plainly. First, billing: through APIsRouter, the DeepSeek ids bill at the flat catalog input and output rates shown in the table further down; the catalog does not list a separate cache-hit rate for these ids. Price your plans at the flat rates. Second, behavior: whether upstream cache hits occur for forwarded traffic, and whether they show up in the usage fields your client sees, depends on routing details that are not observable from the outside, so treat any latency benefit from repeated prefixes as possible rather than promised. Third, portability: the prompt-structure discipline below costs nothing and pays everywhere, on DeepSeek direct where it sets your hit rate and your bill, and on any well-designed serving stack where stable prefixes are generally the fast path. If your workload is exactly the caching-friendly shape, a huge stable prefix resent thousands of times, and the cache discount dominates your economics, calling DeepSeek's platform directly for that workload is the honest recommendation; the gateway earns its place on multi-model routing, one-key convenience, and the free start, not on reselling upstream cache rates it does not meter.

Prompt structure that maximizes hits.

None of these tips trade quality for cost; they are ordering discipline. The same layout that caches well is also easier to debug, since every request differs from the last only at the tail.

• Put stable content first: system prompt, tool definitions, few-shot examples, style guides, in that fixed order, byte-identical across requests. This block is your cacheable prefix.
• Keep volatile content last: the user's new message, retrieved documents, timestamps. Anything that changes belongs after everything that does not.
• Never interpolate volatility into the prefix: a timestamp, request id, or user name templated into the system prompt invalidates the entire cache line from that byte onward, every request.
• Append, do not rewrite: chat histories that only grow at the end re-hit their whole previous length; histories that get summarized, reordered, or trimmed at the top miss from the first changed token.
• Batch same-prefix jobs together in time: cache entries expire within hours to days when unused, so a nightly batch that reuses one prefix consecutively hits far more than the same jobs scattered across a week.
• Measure before optimizing further: on DeepSeek direct, log prompt_cache_hit_tokens per request; a low hit rate on a workload that should cache almost always traces to hidden volatility at the top of the prompt.

Pay-as-you-go · transparent per-model pricing

Selected models are priced below official list prices. Exact input, output, cache, and per-request prices are shown for each model.

Reading the numbers: a checklist for cache-aware cost review.

Once a workload runs, three checks turn caching from folklore into accounting. Check the split: on direct DeepSeek traffic, prompt_cache_hit_tokens over total prompt tokens is your hit rate, and for a stable-prefix workload it should sit high; if it does not, diff two consecutive requests byte by byte from the top and the invalidating change will be in the first difference. Check the shape: input-heavy workloads (agents, long chats, document QA) are where caching moves bills, while output-heavy workloads (generation, long-form writing) barely notice it, since output never caches. Check the counterfactual: multiply your monthly input tokens by hit and miss rates before deciding a workload's routing, direct for cache-dominated shapes, gateway for multi-model convenience, because the right answer genuinely differs by shape. However the routing lands, the per-request usage data, from DeepSeek's fields on direct traffic or the APIsRouter console on gateway traffic, is the source of truth that keeps the decision honest month over month.

FAQ