How DeepSeek API Context Caching Cuts Cached-Input Costs by up to 98%

DeepSeek API context caching bills cached input at 2% of the miss rate on deepseek-flash and about 3.3% on deepseek-v4-pro. Hit rules, rates, code and tips.

API·April 25, 2026·By DS Guide Editorial
DeepSeek API context caching title card: eyebrow 'API · Context caching', title 'Context Caching', tagline 'Repeated prefixes bill at the cache-hit rate, no setup.', and four stats: 2% Flash hit/miss, 3.3% Pro hit/miss, Auto on by default, and Half off-peak rates, beside an open-manual illustration.

If you run an agent with a 20,000-token system prompt and call it a thousand times an hour, the input bill adds up fast. DeepSeek API context caching is the feature that quietly addresses that — repeated prompt prefixes are served from a hard-disk cache and billed at the cache-hit rate, which on deepseek-flash is one-fiftieth of the cache-miss rate ($0.006 vs $0.30 per 1M input tokens at peak, $0.003 vs $0.15 off-peak, as of October 2026). There is nothing to configure: no cache_control breakpoints, no TTL knobs, no extra SDK calls.

This guide walks through how the cache works on the two current models, deepseek-flash (DeepSeek-V4.1-Flash-1017) and deepseek-v4-pro (DeepSeek-V4-Pro-0813), following DeepSeek’s Context Caching guide: when a prefix counts as a hit, what the usage fields tell you, two worked cost examples at peak and off-peak rates, and the prompt-structure habits that move your hit rate from accidental to deliberate.

What DeepSeek API context caching actually does

DeepSeek cache-hit vs cache-miss pricing title card: eyebrow 'Pricing · per 1M input tokens', title 'Hit vs Miss Pricing', tagline 'USD per 1M input tokens at peak; off-peak is half.', and four stats: 0.006 Flash hit, peak; 0.30 Flash miss, peak; 0.044 Pro hit, peak; and 1.32 Pro miss, peak, beside a balance-scale illustration.

According to DeepSeek’s Context Caching guide, Context Caching on Disk is enabled by default for all users, with no code changes. Each request triggers the construction of a hard-disk cache; if a later request has an overlapping prefix with an earlier one, the overlapping part is fetched from the cache and counts as a “cache hit”.

The model still generates the response from scratch — caching only affects the input side. In the guide’s words, the hard disk cache only matches the prefix part of the user’s input; the output is still generated through computation and inference and is influenced by parameters such as temperature.

The hit rules are stricter than “any shared prefix”. Because of the Sliding Window Attention mechanism, cached prefixes are stored as independent cache prefix units, and a request only hits the cache if it fully matches a unit that has already been persisted. Units are persisted in three ways:

  • At request boundaries. Each request produces two units: one at the end of the user input and one at the end of the model output.
  • By common-prefix detection. When the system detects a common prefix across several requests, it persists that prefix as its own unit.
  • At fixed token intervals. For long inputs or outputs, units are carved out at fixed intervals so that long prefixes do not stay uncacheable just because they never reach an end position. DeepSeek does not publish the interval.

The guide’s two examples show what this means in practice. A first request A + B followed by A + B + C hits the cache for A + B — the normal multi-turn case. But A + B followed by A + C does not hit, because A + C does not fully match the unit A + B; the system then detects the common prefix A and persists it, so a third request A + D hits for A. Other operational details from the guide:

  • The cache works on a “best-effort” basis and does not guarantee a 100% hit rate.
  • Cache construction takes seconds.
  • Once a cache is no longer used, it is cleared automatically, usually within a few hours to a few days.

To check your own requests, the DeepSeek API tester guide includes a cache-billing checklist for the usage fields described below.

Pricing — deepseek-flash and deepseek-v4-pro side by side

Both current models get the cache automatically. The cache-hit price is the headline saving; the cache-miss rate is what you pay for the variable tail of each request. Prices are USD per 1M tokens, as of October 2026; off-peak rates are half of peak.

Model Input — cache hit (peak / off-peak) Input — cache miss (peak / off-peak) Output (peak / off-peak) Hit price as share of miss
deepseek-flash $0.006 / $0.003 $0.30 / $0.15 $1.20 / $0.60 2% (98% less)
deepseek-v4-pro $0.044 / $0.022 $1.32 / $0.66 $3.96 / $1.98 about 3.3% (about 96.7% less)

Peak hours are 01:00–04:00 and 06:00–10:00 UTC, Monday through Friday, excluding Chinese public holidays; all other hours — including weekends — are off-peak. The legacy names deepseek-v4-flash and deepseek-v4-flash-vision-exp are still accepted and billed at the deepseek-flash price; deepseek-chat and deepseek-reasoner were scheduled for retirement on 2026-07-24 at 15:59 UTC and are no longer listed. Prices can change — verify on DeepSeek’s official pricing page, and see our DeepSeek API pricing reference for the full breakdown.

Quickstart: requests that will hit the cache

The API is OpenAI-compatible and stateless — your client must resend the conversation history on every call; DeepSeek does not store turns for you. Chat requests hit POST /chat/completions at https://api.deepseek.com. The script below follows the guide’s long-text example: three questions about the same document. The first two requests share the system prompt and document but end differently, so neither fully matches a persisted unit; after them, the common prefix is persisted, and the third request should report it as cache hits (best-effort).

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com",
)

SYSTEM = "You are an experienced financial report analyst."
REPORT = open("q1_report.txt").read()  # long, stable document

def ask(question: str):
    resp = client.chat.completions.create(
        model="deepseek-flash",
        messages=[
            {"role": "system", "content": SYSTEM},
            {"role": "user", "content": REPORT + "\n\n" + question},
        ],
        max_tokens=1024,
        extra_body={"thinking": {"type": "disabled"}},
    )
    u = resp.usage
    print("hit:", u.prompt_cache_hit_tokens, "miss:", u.prompt_cache_miss_tokens)
    return resp.choices[0].message.content

ask("Please summarize the key information of this report.")
ask("Please analyze the profitability of this report.")
ask("Please analyze the ratio of revenue to expenses.")  # expect hits on SYSTEM + REPORT

For a multi-turn chat the hit comes sooner: the second turn resends the first turn’s messages plus the reply, which fully matches the unit persisted at the end of the first turn’s output. The same code works against deepseek-v4-pro with no other change. Thinking mode is the default on both models; the example switches it off to keep the output short, and removing the extra_body line turns it back on (the response then carries reasoning_content alongside the final content). DeepSeek also exposes an Anthropic-compatible surface at a separate base URL, https://api.deepseek.com/anthropic, if your stack already uses the Anthropic SDK. Full setup walk-through: DeepSeek API getting started.

Reading the usage object

Every response includes a usage object with two fields you should log on every call:

  • prompt_cache_hit_tokens — the number of input tokens in this request that resulted in a cache hit, billed at the hit rate.
  • prompt_cache_miss_tokens — the number of input tokens that did not, billed at the miss rate.

The two add up to prompt_tokens. DeepSeek’s Chat Completions reference also returns the OpenAI-style prompt_tokens_details.cached_tokens, which it defines as the same number as prompt_cache_hit_tokens, so tools that read the OpenAI field work unchanged. On streamed requests, the usage arrives on the last chunk. The first request with a new prefix reports zero hit tokens — that is expected. A repeat of an identical request can hit the unit persisted at the end of the earlier request’s input; a request that only shares part of its prefix hits once that shared part has been persisted as a unit, as in the examples above.

Worked cost example A — deepseek-flash agent

One million calls, each with a 2,000-token system prompt that stays constant, a 200-token user message that changes every time, and a 300-token reply. Model: deepseek-flash. The example assumes the system prompt has been persisted and hits on every call — the cache is best-effort, so treat this as the best case.

  • Cached input: 2,000 × 1,000,000 = 2,000,000,000 tokens × $0.006 / M = $12.00 at peak; × $0.003 / M = $6.00 off-peak
  • Uncached input: 200 × 1,000,000 = 200,000,000 tokens × $0.30 / M = $60.00 at peak; × $0.15 / M = $30.00 off-peak
  • Output: 300 × 1,000,000 = 300,000,000 tokens × $1.20 / M = $360.00 at peak; × $0.60 / M = $180.00 off-peak
  • Total: $432.00 if run entirely at peak; $216.00 if run entirely off-peak

Without caching — every input token billed at the miss rate — the input alone would be 2,200,000,000 × $0.30 / M = $660.00 at peak ($330.00 off-peak), taking the total to $1,020.00 ($510.00 off-peak). Caching saves $588.00 at peak and $294.00 off-peak, about 57.6% of the whole bill in both periods; the cached tokens themselves cost 98% less than at the miss rate.

Worked cost example B — deepseek-v4-pro agent

Same workload on deepseek-v4-pro.

  • Cached input: 2,000,000,000 × $0.044 / M = $88.00 at peak; × $0.022 / M = $44.00 off-peak
  • Uncached input: 200,000,000 × $1.32 / M = $264.00 at peak; × $0.66 / M = $132.00 off-peak
  • Output: 300,000,000 × $3.96 / M = $1,188.00 at peak; × $1.98 / M = $594.00 off-peak
  • Total: $1,540.00 if run entirely at peak; $770.00 if run entirely off-peak

Without caching the input would cost 2,200,000,000 × $1.32 / M = $2,904.00 at peak ($1,452.00 off-peak), for totals of $4,092.00 and $2,046.00; caching saves $2,552.00 at peak and $1,276.00 off-peak, about 62.4% in both periods.

The Pro example shows two things. First, caching is worth more in absolute dollars on deepseek-v4-pro: the gap between miss and hit is $1.276 per million tokens at peak ($0.638 off-peak) on Pro versus $0.294 ($0.147) on Flash. Second, output dominates the bill on both models. The same workload costs about 3.6× as much on deepseek-v4-pro as on deepseek-flash ($1,540.00 vs $432.00 at peak), so reach for Pro only when your workload needs it. For a quick check on your own numbers, the DeepSeek pricing calculator lets you plug in your hit rate and message profile.

Five prompt patterns that maximise cache hits

A request only hits when it fully matches a persisted prefix unit that starts at the beginning of the input. That single rule drives every optimisation below.

  1. Put stable content first. System prompt → tool schemas → retrieved documents → finally the user’s question. Anything that changes per call must sit at the end.
  2. Pin the system prompt byte-for-byte. Even rewording “You are a helpful assistant.” to “You are a helpful AI assistant.” changes the prefix for every downstream call. Hash your system prompt and alert if it changes.
  3. Freeze few-shot example order. Re-shuffling examples between calls changes the prefix and breaks the match. Keep the same examples in the same order; only the trailing user task changes.
  4. Move volatile metadata to the end. Timestamps, request IDs, A/B flags — none of these belong before the cacheable prefix. Append them to the final user message.
  5. Pre-chunk long documents. If you swap a 500K-token document on every call, the document is not a cacheable prefix. Decide on a small set of canonical chunks, reference them by ID, and keep that ordering stable across requests.

For a deeper treatment of prompt structure, see DeepSeek prompt engineering. If you are wiring this into a retrieval pipeline, the DeepSeek RAG tutorial shows where to put the retrieved chunks for cache-friendliness.

How DeepSeek caching compares to OpenAI and Anthropic

All three providers cache prompt prefixes; the differences are in what you pay, who manages it, and what minimum size the cache accepts. The OpenAI and Anthropic columns come from their own prompt-caching documentation, checked on 25 October 2026 (OpenAI, Anthropic); both vary by model, so check the page for the model you use.

Provider How it’s enabled Min prefix Cache-hit price Cache-write charge
DeepSeek (deepseek-flash, deepseek-v4-pro) On by default for all users; no code changes Not stated in the current guide (the August 2024 launch announcement gave a 64-token storage unit) 2% of the miss rate (Flash), about 3.3% (Pro) None on the pricing page
OpenAI Enabled by default for supported models; explicit breakpoints on GPT-5.6 and later 1,024 visible input tokens on GPT-5.6 and later; varies for earlier models 0.1× uncached input on GPT-5.6 and later (0.05× for GPT-6.1 Sol); model-dependent on earlier models 1.25× input for the default 30-minute lifetime on GPT-5.6 and later; none on earlier models
Anthropic cache_control: one top-level field (automatic caching) or explicit breakpoints Model- and platform-dependent 0.1× base input (0.05× on Claude Opus 5.5 and Sonnet 5.5; 0.025× on Claude Fable 5.1 and Mythos 5.1) 1.25× base input (5-minute) or 2× (1-hour)

The “automatic + no write charge” combination is what makes DeepSeek caching painless: you don’t pay to populate the cache and you don’t manage cache keys. The trade-off is less control — DeepSeek documents no equivalent to OpenAI’s prompt_cache_key or Anthropic’s breakpoints and TTL choices. If a hit rate looks low, the fix is restructuring your prompt. For a broader head-to-head on the API surfaces, see DeepSeek vs Claude and the DeepSeek API docs and guides.

Common reasons your hit rate looks lower than expected

  • The prefix changed. A timestamp injected into the system prompt, a regenerated tool-schema JSON with reordered keys, a different model version pinned in metadata — any of these break the prefix.
  • The shared prefix has not been persisted yet. Requests that share a prefix but end differently do not hit each other’s request-boundary units. The common prefix is persisted only once the system detects it across requests, so the first requests with a new shared prefix miss.
  • The cache was cleared. Unused caches are cleared, usually within a few hours to a few days; a low-traffic prompt will go cold.
  • Different user_id values. DeepSeek’s Rate Limit & Isolation page says user_id isolates the KV cache between the users on your side for privacy, so requests with different user_id values should not be expected to share cached prefixes.
  • Best effort. The cache does not guarantee a 100% hit rate, even for an identical prompt.

When caching changes the architectural choice

DeepSeek context caching title card: eyebrow 'Cache · Prefix units', title 'When Caches Hit', tagline 'A hit needs a full match of a persisted prefix unit.', and four stats: 2 units per request, full match required, 3rd call hits prefix, and 0 code changes, beside a punch-card illustration.

Once you internalise that cached prefixes cost a fiftieth of fresh ones on deepseek-flash (and about a thirtieth on deepseek-v4-pro), several patterns become viable that previously weren’t:

  • Long system prompts. A 20K-token instruction set used to be wasteful. With caching, you pay the miss rate until the prefix is persisted and the hit rate after that, amortised across thousands of calls. Useful for compliance-heavy assistants, agents with large tool catalogues, and domain-specific style guides.
  • Few-shot at scale. Twenty in-context examples become economically reasonable for high-volume classification or extraction.
  • Repository-wide code review. Feed the codebase as a stable prefix and change only the question. Both current models have a 1M-token context window and up to 384K output tokens, so a large codebase can fit, and only the trailing question bills at the miss rate once the prefix hits.
  • RAG with stable corpora. If your retrieved chunks come from a small, slow-moving knowledge base, ordering them deterministically lets the cache absorb most of the input cost.

For role-specific applications of these patterns, see DeepSeek for developers and the broader DeepSeek for coding use case.

Limitations and honest caveats

Three things to keep in mind before architecting around the cache:

  1. Best-effort, not guaranteed. Even an identical prompt may miss occasionally. Budget for the worst case (everything bills at the miss rate) and treat the cache as upside.
  2. Isolation is a trade-off. Passing user_id isolates the KV cache per end user for privacy; requests under different user_id values then should not be expected to share cached prefixes. DeepSeek’s August 2024 launch announcement also said each user’s cache is isolated and logically invisible to others.
  3. Output is not cached. Same prompt, same settings ≠ same response. If you need response-level caching, do it in your own application layer.

For background, DeepSeek’s August 2024 announcement explains the original rationale for caching on disk; its prices and matching rules have since been superseded by the current pricing page and Context Caching guide, which no longer mentions the 64-token storage unit.

How does DeepSeek API context caching work?

DeepSeek persists “cache prefix units” — at the end of each request’s input and output, at common prefixes it detects across requests, and at fixed intervals in long inputs — and a later request that fully matches a persisted unit gets those tokens from a hard-disk cache, billed at the cache-hit rate ($0.006 vs $0.30 per 1M on deepseek-flash at peak, $0.003 vs $0.15 off-peak). It runs automatically — no code changes, no cache keys, no TTL configuration. See the DeepSeek API documentation for the response schema.

What is the minimum prompt length for a cache hit?

DeepSeek’s current Context Caching guide does not state a minimum length. What it requires is a full match of a persisted cache prefix unit. DeepSeek’s August 2024 launch announcement said the cache used 64 tokens as a storage unit and that content under 64 tokens would not be cached; the current guide no longer repeats that figure. The DeepSeek token counter helps you measure prefix length.

Does caching work on deepseek-chat and deepseek-reasoner?

Those legacy IDs were scheduled for retirement on 2026-07-24 at 15:59 UTC and are no longer listed in DeepSeek’s documentation; before that, they were served by deepseek-v4-flash. Caching applies automatically to the current models, deepseek-flash and deepseek-v4-pro. Migration is a change to the model field; the base_url stays the same. See DeepSeek OpenAI SDK compatibility for the full migration pattern.

Is the cache shared between users or accounts?

DeepSeek’s August 2024 launch announcement said each user’s cache is isolated and logically invisible to others. Within your own account, the user_id parameter isolates the KV cache between the users on your side for privacy, according to the Rate Limit & Isolation page. Unused caches are cleared automatically, usually within a few hours to a few days, so a rarely used prompt may go cold and pay the full miss rate again. More on data handling in the DeepSeek privacy guide.

Why is my cache hit rate so low?

The most common cause is something changing at the front of the prompt — a timestamp, a regenerated JSON tool schema with reordered keys, a different system message, or shuffled few-shot examples. Another is the hit rule itself: requests that share a prefix but end differently only hit once the shared prefix has been persisted as a unit. Other culprits are different user_id values and low-traffic prompts whose caches were cleared. Log prompt_cache_hit_tokens on every call and alert when the ratio drops. See DeepSeek API best practices for monitoring patterns.

Sources & Methodology

Last source check: October 25, 2026

Primary sources

  • OfficialDeepSeek API documentationEndpoints, request/response shape, model IDsLast checked: October 25, 2026
  • Official documentationDeepSeek API — Context Caching guideDefault-on disk cache; cache prefix units (request boundaries, common-prefix detection, fixed intervals); examples A+B / A+C / A+D; usage fields; best-effort; seconds to build; cleared within hours to days (fetched 25 Oct 2026)Last checked: October 25, 2026
  • Official documentationDeepSeek pricing pageCache-hit / cache-miss / output rates, peak and off-peak, peak hours, legacy-name billingLast checked: October 25, 2026
  • Official documentationDeepSeek API — Chat Completions API referenceusage fields: prompt_tokens = hit + miss; prompt_tokens_details.cached_tokens same as prompt_cache_hit_tokensLast checked: October 25, 2026
  • Official documentationDeepSeek API — Rate Limit & Isolationuser_id KVCache isolationLast checked: October 25, 2026

Context sources

Methodology

Pricing figures were checked against the official DeepSeek pricing page and normalised into estimated monthly costs using sample token usage scenarios. Actual costs may vary depending on caching, input/output ratio, regional availability, and provider updates.

Data confidence

High — figures checked directly against the official pricing page on the review date.

Editorial note

The site's pricing dataset is fetched daily from DeepSeek's official pricing page; this article reflects the prices on the date shown above.

Leave a Reply

Your email address will not be published. Required fields are marked *