DeepSeek V4 Migration Guide: Life After V3 and R1

On July 24, 2026 — five days after DeepSeek V4 went GA — DeepSeek deprecated V3 and R1 on its first-party API. No long sunset, no year of dual-running: the models that reset the industry’s price expectations in 2024 and 2025 left the endpoint inside a week of their successor’s general availability.

If you had DeepSeek wired into real pipelines, you got one of two July 24ths. Pipelines pinned to retired IDs — deepseek-reasoner, dated V3 snapshots — started throwing errors mid-run. Pipelines riding the rolling deepseek-chat alias kept working and got something sneakier: a different model answering under the same name, with nobody re-running the evals. Both groups have migration work; only one of them knows it.

This is the practical guide to DeepSeek V4 migration, in the order that avoids regret: figure out which failure mode you’re in, pick your lane between V4 Pro and V4 Flash, re-baseline your evals before flipping traffic, make the config swaps (real snippets below for the SDK, Claude Code, Aider, and a router), re-model your costs at the new $0.14 floor, and keep a rollback lane warm. Where V4 sits against the rest of the open field is a different article — the mid-2026 open-weight scorecard — this one is about getting off the dead models cleanly.

What broke on July 24 — and whether it hit you

The deprecation killed endpoints, not models — the open-weights asterisk matters and we’ll use it for rollback later. But on the first-party API, four things broke at once:

What you had	What happened July 24	Severity
Pinned IDs: deepseek-reasoner, V3-era snapshots	Hard errors on every call	Loud — you already know
Rolling alias: deepseek-chat	Silently began serving the V4 line	Quiet — the dangerous one
Eval baselines scored against V3/R1	Invalidated; comparisons now cross-model	Quiet
Cost models built on V3-era pricing	Stale — in your favor, but stale	Quiet

The loud failure is annoying and easy: something in your stack names a dead model, and the fix is a config change you’ll make today. The quiet failures are the reason this guide exists. A model swap under a stable alias means your agent’s behavior changed without a deploy, your baseline numbers describe a model you can no longer reach, and any regression you notice next month has a three-week-old cause. R1 users have a third quiet change: V4 folds reasoning into the main line rather than splitting it into a separate reasoner model, so prompts and parsers built around R1’s separate reasoning channel behave differently now.

Who was not hit: anyone running distills or full weights locally, and anyone consuming V3/R1 through third-party hosts. Deprecation is an API event. The MIT-licensed weights remain downloadable from Hugging Face, and Western providers still serve them under their own terms. If that’s you, your only real task is deciding whether V4’s economics justify moving at all — skip to the cost section.

First move regardless of group — inventory every place a DeepSeek model is named:

# Find every DeepSeek reference across dotfiles, repos, and CI
grep -rn --include="*" -i -E "deepseek(-reasoner|-chat|-v3|_v3)?" \
  ~/.config ~/.aider.conf.yml ~/.claude* .env* \
  .github/workflows/ docker-compose*.yml 2>/dev/null

Expect hits you forgot about. CI jobs and cron-driven agents are where dead model IDs hide longest.

Pick your lane: DeepSeek V4 Pro or V4 Flash

DeepSeek split the V4 line deliberately — both lanes shipped April 24, 2026 and reached GA July 19 — and the split is the first real decision of the migration.

	DeepSeek V4 Pro	DeepSeek V4 Flash
Architecture	1.6T total / 49B active (MoE)	284B total / 13B active (MoE)
Context	1M	1M
SWE-bench Verified	~80.6% — vendor-run	not the point
Price per M tokens	above Flash	$0.14 in / $0.28 out
License	MIT	MIT
Built for	planning, architecture, long-horizon work	the agent grind: tests, fixes, mechanical edits

Per the mid-2026 open-model figures compiled by Morph, V4 Pro’s ~80.6% Verified is a vendor-run number — treat it as directionally strong rather than gospel. Flash’s claim needs no benchmark: $0.14 per million input tokens is the credible price floor for agentic coding as of August 2026.

The decision rules that hold up in practice:

• Came from V3 on cost grounds? Flash is your default. It is the spiritual successor: the cheap, fast line for high-volume agent work, at prices below what you were paying.
• Came from R1 for reasoning-heavy work? V4 Pro replaces the reasoner. Planning, gnarly debugging, multi-file architecture — the tasks you routed to R1 go here.
• Running an agent loop with mixed steps? Route, don’t choose: Flash for the mechanical bulk, Pro for planning and escalation on failure. Two-tier routing is where the V4 split pays best, and most harnesses make it a config stanza rather than an engineering project.
• Genuinely unsure? Run both through the eval sequence below and let your own tasks vote. Never let a pricing page make a capability decision for you.

The migration decision tree. Most teams land on Flash-first with Pro escalation; distill users may not need to move at all.

Evals before endpoints: re-baseline first

The instinct is to swap the config and see if anything feels off. Resist it. “Feels off” surfaces in weeks; an eval run surfaces it in an afternoon, and evals are how you measure software that acts rather than guess about it. The sequence:

1. Reconstruct your V3/R1 baseline while you still can. If you never wrote down baseline scores, run your task set against V3 or R1 on a third-party host that still serves the weights. This number anchors every claim you’ll make about the migration — including to whoever approves it.
2. Build a golden set of 20–50 tasks from your own recent work. Real tickets, real repos, known-good outcomes. Public benchmark scores — including the ones in this article — describe distributions that are not your backlog.
3. Run the set through your actual harness against V4 Pro and V4 Flash separately. Harness effects are large; a raw API comparison tells you about the model, not about your setup.
4. Score four metrics per model: solve rate, cost per solved task (a cheap model that needs three attempts isn’t cheap), wall-clock per task, and diff quality on human review.
5. Set acceptance thresholds before you look at results. A useful default: flip traffic when a V4 lane matches the old baseline’s solve rate within a couple of points at materially lower cost per solved task — and route around any task category where it clearly regresses.

Expect a mixed scorecard, not a coronation. The common pattern in our testing: Flash matches or beats V3 on mechanical tasks at a fraction of the cost, Pro beats R1 on planning-heavy tasks, and each has a category or two of regressions that routing — not agonizing — should absorb.

The order that avoids regret: baseline and golden set before any config touches production.

The config swaps, harness by harness

With a lane chosen and evals green, the swaps themselves are small. Four snippets cover most stacks; endpoints and model IDs churn, so check the vendor’s current model list before trusting a long run to any of them. DeepSeek’s API surfaces the V4 line through the rolling deepseek-chat alias plus explicit V4 Pro and Flash IDs — pin the explicit IDs and stop riding aliases; July 24 is what riding the alias costs.

1. Direct API via the OpenAI-compatible SDK — the pattern most custom pipelines use, per DeepSeek’s API docs:

from openai import OpenAI

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

# Before July 24:  model="deepseek-reasoner"  (R1 — now returns an error)
# After:           pin the explicit V4 lane
resp = client.chat.completions.create(
    model="deepseek-v4-flash",   # or "deepseek-v4" for Pro-tier work
    messages=messages,
)

2. Claude Code against DeepSeek’s Anthropic-compatible endpoint — the cheapest way to drive an Anthropic-native harness, same shape as the recipes in our Chinese CLI wiring guide:

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="$DEEPSEEK_API_KEY"
export ANTHROPIC_MODEL="deepseek-v4-flash"
claude

3. Aider — one flag or one line in .aider.conf.yml, per Aider’s model docs:

# was: aider --model deepseek/deepseek-reasoner
aider --model deepseek/deepseek-v4-flash

# or persist it in .aider.conf.yml:
#   model: deepseek/deepseek-v4-flash

4. A LiteLLM-style router — the config that encodes the whole strategy: Flash first, Pro on escalation, and a rollback lane pointing at re-hosted V3 weights:

model_list:
  - model_name: agent-grind # default lane
    litellm_params:
      model: deepseek/deepseek-v4-flash
      api_base: https://api.deepseek.com
  - model_name: agent-planning # escalation lane
    litellm_params:
      model: deepseek/deepseek-v4
      api_base: https://api.deepseek.com
  - model_name: rollback-v3 # insurance: V3 weights, third-party host
    litellm_params:
      model: openrouter/deepseek/deepseek-v3
      api_base: https://openrouter.ai/api/v1

router_settings:
  fallbacks:
    - agent-grind: ['agent-planning', 'rollback-v3']

Whichever harness you drive — and the 2026 field map says you probably drive more than one — the principle is identical: model choice belongs in config or an env var, never in code. Teams that learned that on July 24 will do the next deprecation in an afternoon.

If you run distills, nothing was deprecated

The R1 distill family — the small models fine-tuned from R1’s outputs that half the local-AI world runs — was never on DeepSeek’s API in the first place. Your local distill served through Ollama or vLLM worked on July 23, worked on July 25, and will work in 2027. Deprecation reaches endpoints, not your disk.

The real question for distill users is softer: whether V4-era alternatives now beat your distill on merit. The honest answer is often yes — the one-box class moved fast in 2026, and an R1-era 32B distill now competes with purpose-built agent models like Qwen3-Coder-Next running in similar memory. Re-run your golden set against the current local field before sentimentality wins; our guide to open-weight models that can drive a harness covers what’s worth testing at each memory budget. Expect V4 distills to appear from the community in time , but nothing about the deprecation forces your hand.

Re-model the costs: what the $0.14 floor changes

V3’s deprecation deleted the cheapest line item in most token budgets — and replaced it with a cheaper one. That is unusual enough to re-model rather than assume.

Work one honest example. A daily-driver agent workload that burns 8M input and 400K output tokens a day — a busy but not extreme loop, with context re-sent each step — prices out like this on V4 Flash:

input:   8.0M × $0.14/M  =  $1.12
output:  0.4M × $0.28/M  =  $0.11
daily total:                $1.23   →  ~$27/month at 22 workdays

That is subscription money for API-metered usage — the arithmetic that made the collapsing cost of running agents a structural story rather than a news cycle. Three second-order effects worth catching while you re-model:

• Workloads that were marginal at V3 prices are now trivially viable. Re-examine the automation ideas you shelved on cost grounds — bulk refactors, always-on test triage, doc sweeps. The floor moved; your list should too.
• Routing ratios change. If Pro-tier escalation costs several times Flash, an 80/20 Flash/Pro split behaves very differently from 50/50. Instrument which steps actually need Pro; most loops need it less than their authors assume.
• Flat plans deserve a re-read. At $27/month metered, some subscription lanes stop making sense and others become the bargain. Re-run the comparison in our token-plan teardown with your own numbers rather than assuming last quarter’s answer.

Product note: A migration pitched on savings should end with a receipt. Automater Lite meters token usage locally across every provider you run — capture two weeks of pre-migration burn, flip to V4, and read the before/after off your own dashboard instead of a pricing page. When someone asks what the migration saved, you’ll have a number instead of an estimate. Free on automater.ai.

Rollback insurance: how to flip back without drama

Every migration guide ends with “monitor closely.” Here is what that actually means, structured so a bad week costs you a config flip instead of a rewrite.

Keep the old lane warm. Because the weights are open, V3 and R1 didn’t die — they moved. Keep a third-party-hosted V3 configured as a named fallback (the rollback-v3 lane in the router config above) for 30 days. You’ll pay a re-host premium if you ever use it; that premium is the insurance price.

Make rollback a flag, not a deploy. If flipping models requires a code change, you don’t have a rollback plan, you have a rollback project. Env var or router config only.

Define triggers before you flip. Write down the numbers that mean “go back”: solve rate more than a few points under baseline for a week, cost per solved task above the old lane’s, latency breaking your interactive loops, or a spike in malformed tool calls. Vague unease is not a trigger; drift against your golden set is.

Run two weeks in parallel where it’s cheap. Shadow a slice of traffic — even 10% of tasks re-run against the old lane — and diff outcomes. Transcripts are the evidence layer here: archive both sides’ sessions so regressions can be diagnosed instead of debated. If you run several assistants side by side, this is the same discipline as running a multi-agent fleet without the chaos — named lanes, visible status, receipts for every claim.

Then actually decommission. Rollback lanes left configured forever become the next incident’s mystery. When the 30 days pass and the triggers stayed quiet, delete the V3 references, note the eval scores as the new baseline, and close the ticket.

The one-week migration runbook

The whole guide, compressed to a schedule a busy team can actually run:

1. Monday — inventory. Run the grep. List every config, CI job, router, and script naming a DeepSeek model. Tag each as pinned (erroring) or alias (silently migrated).
2. Tuesday — baseline. Assemble the 20–50-task golden set; reconstruct V3/R1 baseline scores via a third-party host if you never recorded them.
3. Wednesday — eval. Run the set through your harness against V4 Flash and V4 Pro. Score solve rate, cost per solved task, wall-clock, diff quality.
4. Thursday — decide and stage. Pick Flash, Pro, or the routed split. Make the config swaps in staging with explicit pinned IDs. Wire the rollback lane and write down the triggers.
5. Friday — flip. Move production traffic behind the flag. Start the parallel shadow slice and the metering capture.
6. The next two weeks — watch. Weekly golden-set re-runs, transcript diffs on anything odd, cost dashboard against the old burn.
7. Day 30 — decommission. Kill the rollback lane, record the new baseline, write the two-paragraph postmortem your future self will want at the next deprecation.

That last clause is the real lesson of July 24. Model deprecations are no longer rare events at the frontier’s pace — and nothing about that pace suggests V4 will be the last line to replace its predecessors inside a week. Teams that treat model choice as configuration, keep evals current, and archive their sessions migrate in a week. Everyone else finds out from their error logs.

FAQ: DeepSeek V4 migration

Why did DeepSeek deprecate V3 and R1?

DeepSeek consolidated its API behind the V4 line after V4 reached general availability on July 19, 2026, deprecating V3 and R1 five days later on July 24. Running one current model family simplifies serving and pricing. The open-weight asterisk: deprecation closed the endpoints, but the MIT-licensed weights remain downloadable and third parties still serve them.

What replaces deepseek-reasoner after the R1 deprecation?

V4 Pro. The V4 line folds reasoning into the main models instead of splitting it into a separate reasoner, so R1-era workloads route to V4 Pro (or V4 Flash for lighter tasks). Pipelines that parsed R1’s separate reasoning output need adjustment — verify V4’s output format against the current API docs before flipping traffic.

Should I migrate to DeepSeek V4 Pro or V4 Flash?

Default to Flash if you used V3 for cost: at $0.14/$0.28 per million tokens it is cheaper than what it replaced. Choose Pro for R1-style planning and hard debugging. Most agent teams land on both — Flash for the mechanical bulk, Pro for escalation — and let a router split the traffic.

Can I still use DeepSeek V3 or R1 anywhere?

Yes, just not on DeepSeek’s first-party API. The weights are MIT-licensed, so Western hosts still serve V3 and R1, distills keep working locally through Ollama or vLLM, and self-hosters are unaffected. That is also your rollback lane: keep a re-hosted V3 configured as a named fallback for the first month.

How much does DeepSeek V4 cost?

V4 Flash costs $0.14 per million input tokens and $0.28 per million output on the first-party API — the credible price floor for agentic coding as of August 2026. V4 Pro costs more per token; check DeepSeek’s current pricing page, since the line’s prices have only moved downward.

Sources

• DeepSeek — models and API
• DeepSeek API documentation
• Best open-source coding models of 2026 — Morph
• Hugging Face — open-weight model hosting
• Ollama — local model runtime
• vLLM documentation
• Aider — model configuration docs