Migrate deepseek-chat & deepseek-reasoner to V4

To preserve the documented thinking-mode configuration when migrating deepseek-chat, use deepseek-v4-flash with thinking explicitly disabled. For deepseek-reasoner, explicitly enable thinking. This maps the request configuration; it does not guarantee identical answers, latency, or application behavior. Validate the replacement on your workload.

Cutoff status: DeepSeek’s April 24, 2026 V4 release notice announced that deepseek-chat and deepseek-reasoner would be fully retired and inaccessible after July 24, 2026 at 15:59 UTC. That cutoff has passed. The current official hosted catalog lists deepseek-v4-flash, deepseek-v4-pro, and the experimental multimodal deepseek-v4-flash-vision-exp. Neither retired alias is a safe production fallback, and Vision Exp is a separate image-capable model—not a behavior-preserving replacement for either legacy text alias.

Legacy-alias behavior was last tested: July 28, 2026. Chat-Deep.ai’s bounded checks observed both aliases return HTTP 400 on July 25, then return HTTP 200 while identifying V4 Flash on July 28. The July 28 GET /models response exposed Flash and Pro only because it predates the August 21, 2026 Vision Exp launch. Preserve these results solely as dated alias evidence; they do not describe the current complete model catalog or provide a safe rollback path. Replace every deployable use of the old names with a current V4 ID and an explicit thinking-mode setting. See the dated API updates tracker for the payloads, timestamps, and evidence.

Chat-Deep.ai is an independent guide and is not affiliated with DeepSeek. We checked the examples against DeepSeek’s official API documentation and syntax-checked the JavaScript and Python. The alias-status result above comes from a bounded live check of one account, endpoint, payload, and time window; it is not a guarantee of every environment. Run the smoke tests below in your own non-production environment before changing production traffic.

Behavior-preserving migration map

Legacy request	Explicit DeepSeek V4 replacement	Behavior preserved
`model: "deepseek-chat"`	`model: "deepseek-v4-flash"` `thinking: { type: "disabled" }`	Non-thinking chat
`model: "deepseek-reasoner"`	`model: "deepseek-v4-flash"` `thinking: { type: "enabled" }`	Thinking response

Do not treat deepseek-v4-pro as the automatic successor to either alias. Pro is a deliberate model upgrade that should be selected after quality, latency, cost, and concurrency testing. Both V4 Flash and V4 Pro support thinking and non-thinking modes. Do not map either legacy alias automatically to deepseek-v4-flash-vision-exp; introduce Vision Exp only when the application deliberately adds image input and has validated its multimodal request path. Flash remains the behavior-preserving migration target shown here; Pro and Vision are separate product choices. See the DeepSeek V4 model guide before choosing between them.

Archived DeepSeek pre-cutoff alias migration table — This July 22 capture preserves the pre-cutoff alias mappings and announced July 24, 2026 cutoff as historical migration evidence. Current official model documentation lists the V4 IDs directly. Source: DeepSeek V4 release notice; status rechecked July 26, 2026.

What changes—and what does not

Configuration	Migration action
OpenAI-format base URL	Keep `https://api.deepseek.com`
Raw chat operation	Keep `POST /chat/completions`
DeepSeek API key	Keep the existing server-side key; DeepSeek does not document a new key type for V4
`messages`	Keep the supported system, user, assistant, and tool message structure
`model`	Replace the legacy alias with `deepseek-v4-flash` or a deliberately selected `deepseek-v4-pro`; allow `deepseek-v4-flash-vision-exp` only on deliberately validated image routes
`thinking`	Set it explicitly to preserve the old alias’s mode
Response parser	Verify `reasoning_content`, streaming deltas, tool calls, finish reasons, and usage fields

All three current hosted model IDs list a 1M context length and a maximum output of 384K. The output figure is a maximum, not a default, and the combined input plus generated tokens must fit within the model context. The behavior-preserving migration targets in this guide remain Flash or a deliberately selected Pro; introduce Vision Exp only for an intentional image workflow. Keep a realistic max_tokens value and handle finish_reason: "length" rather than assuming every response reaches your requested endpoint.

1. Find every use of the legacy aliases

Search more than application source files. Model names are commonly stored in environment variables, YAML, JSON, deployment manifests, gateway routing rules, observability dashboards, test fixtures, fallback arrays, database configuration, and agent model registries.

rg -n --hidden \ --glob '!node_modules' \ --glob '!.git' \ 'deepseek-chat|deepseek-reasoner' .

Classify every match by intended behavior:

Fast or ordinary chat: map to V4 Flash with thinking disabled.
Reasoning workflow: map to V4 Flash with thinking enabled.
Quality-first workload: evaluate V4 Pro separately; do not assume it is a one-for-one replacement.
Fallback: replace or remove the legacy name. A retired alias is not a safe rollback target.

Store the model and mode together

The legacy names encoded both a model route and a thinking choice. V4 separates those decisions. Do not keep a single environment variable that changes the model while leaving the mode implicit. Define an application-level profile that changes both values atomically:

const DEEPSEEK_PROFILES = { chat: { model: "deepseek-v4-flash", thinking: { type: "disabled" }, }, reasoner: { model: "deepseek-v4-flash", thinking: { type: "enabled" }, }, }; const profileName = process.env.DEEPSEEK_PROFILE ?? "chat"; const profile = DEEPSEEK_PROFILES[profileName]; if (!profile) { throw new Error("DEEPSEEK_PROFILE must be chat or reasoner."); }

This pattern prevents a partial deployment in which the canonical V4 name is updated but the intended thinking mode is lost. If different routes need Flash and Pro, create separate reviewed profiles rather than letting arbitrary model strings pass from user input.

2. Migrate Node.js requests

The examples use the OpenAI JavaScript package with DeepSeek’s unchanged base URL. Keep the API key on the server.

npm install openai

Replace `deepseek-chat`

Before:

const response = await client.chat.completions.create({ model: "deepseek-chat", messages, });

After, preserving non-thinking behavior:

import OpenAI from "openai"; const apiKey = process.env.DEEPSEEK_API_KEY; if (!apiKey) { throw new Error("Set DEEPSEEK_API_KEY before starting the app."); } const client = new OpenAI({ apiKey, baseURL: "https://api.deepseek.com", }); const messages = [ { role: "user", content: "Return a one-sentence deployment summary.", }, ]; const response = await client.chat.completions.create({ model: "deepseek-v4-flash", messages, thinking: { type: "disabled" }, max_tokens: 300, stream: false, }); console.log(response.choices[0].message.content);

The explicit thinking: { type: "disabled" } is essential. DeepSeek documents thinking as enabled by default for explicit V4 model IDs. Changing only the model name can therefore alter response fields, latency, token use, and the effect of sampling parameters.

Replace `deepseek-reasoner`

Before:

const response = await client.chat.completions.create({ model: "deepseek-reasoner", messages, });

After, preserving thinking behavior:

const response = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages,
  thinking: { type: "enabled" },
  max_tokens: 1200,
  stream: false,
});
const choice = response.choices[0];
if (choice?.finish_reason !== "stop") {
  throw new Error("The answer did not complete normally");
}
const message = choice.message;
console.log({
  reasoning_present: typeof message.reasoning_content === "string",
  reasoning_characters: message.reasoning_content?.length ?? null,
});
if (typeof message.content !== "string" || !message.content.trim()) {
  throw new Error("No final answer was returned");
}
console.log("Answer:", message.content);

DeepSeek’s current Thinking Mode documentation lists direct Chat Completions efforts low, high, and max. Compatibility values medium and xhigh both map to high, the default remains high, and the mapping is identical for V4 Flash and V4 Pro. Use the current table below rather than the page’s historical July capture.

For project structure, TypeScript considerations, and error handling, use the dedicated DeepSeek Node.js and TypeScript guide.

3. Migrate Python requests

DeepSeek instructs Python OpenAI SDK users to pass the thinking object through extra_body.

Python replacement for `deepseek-chat`

import os from openai import OpenAI client = OpenAI( api_key=os.environ["DEEPSEEK_API_KEY"], base_url="https://api.deepseek.com", ) response = client.chat.completions.create( model="deepseek-v4-flash", messages=[ { "role": "user", "content": "Return a one-sentence deployment summary.", } ], max_tokens=300, stream=False, extra_body={"thinking": {"type": "disabled"}}, ) print(response.choices[0].message.content)

Python replacement for `deepseek-reasoner`

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{
        "role": "user",
        "content": "Compare two deployment options and explain the tradeoffs.",
    }],
    max_tokens=1200,
    stream=False,
    extra_body={"thinking": {"type": "enabled"}},
)
choice = response.choices[0]
if choice.finish_reason != "stop":
    raise RuntimeError("The answer did not complete normally")
message = choice.message
reasoning = getattr(message, "reasoning_content", None)
print({
    "reasoning_present": isinstance(reasoning, str),
    "reasoning_characters": len(reasoning) if isinstance(reasoning, str) else None,
})
if not isinstance(message.content, str) or not message.content.strip():
    raise RuntimeError("No final answer was returned")
print("Answer:", message.content)

See the DeepSeek Python SDK guide for environment setup and a larger production structure.

4. Verify the migration with cURL

A small non-production request confirms that the new model ID and mode reach the API. This example tests the behavior-preserving replacement for deepseek-chat:

curl https://api.deepseek.com/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \ -d '{ "model": "deepseek-v4-flash", "messages": [ { "role": "user", "content": "Return exactly: V4 migration test passed" } ], "thinking": { "type": "disabled" }, "max_tokens": 30, "stream": false }'

Do not publish the response as proof that every workflow is compatible. A simple request verifies connectivity; it does not validate streaming, JSON Output, tools, multi-turn state, rate limits, or production behavior.

Check canonical model IDs

curl https://api.deepseek.com/models \ -H "Authorization: Bearer ${DEEPSEEK_API_KEY}"

The current official catalog documents deepseek-v4-flash, deepseek-v4-pro, and deepseek-v4-flash-vision-exp. Add a deployment check or configuration allowlist that rejects deepseek-chat and deepseek-reasoner before release. Allow Vision Exp only on routes that safely accept and validate image input.

5. Account for thinking-mode differences

Current documentation check: DeepSeek publishes the same direct Chat Completions effort mapping for V4 Flash and V4 Pro, the two text-model migration targets in this guide. The contract below was rechecked against the official Thinking Mode documentation on August 24, 2026; the earlier model-specific table shown in this page’s July capture remains historical. Do not silently generalize this Flash/Pro mapping table to Vision Exp without an explicit current provider statement.

Area	Non-thinking migration	Thinking migration
Toggle	`thinking.type: "disabled"`	`thinking.type: "enabled"`
Final answer	Read `message.content`	Read `message.content`
Reasoning	Do not require a reasoning field	Handle `message.reasoning_content` separately
Streaming	Handle `delta.content`	Handle `delta.reasoning_content` and `delta.content`
Sampling controls	`temperature` and `top_p` can affect generation	`temperature`, `top_p`, `presence_penalty`, and `frequency_penalty` are accepted but have no effect
Effort	Not applicable	Direct values: `low`, `high`, `max`; compatibility values `medium` and `xhigh` map to `high`; default `high`. The mapping is identical for V4 Flash and V4 Pro.

Current Chat reasoning-effort mapping

Chat Completions request	Actual effort on Flash and Pro
`low`	`low`
`medium` (compatibility)	`high`
`high`	`high`
`xhigh` (compatibility)	`high`
`max`	`max`

Chat Completions mapping verified against DeepSeek’s official Thinking Mode documentation on August 14, 2026.

Use low, high, or max in new Chat Completions configurations. Existing software may still send medium or xhigh; both map to high on Flash and Pro, so they do not create distinct effort levels. This migration guide uses Chat Completions; Responses uses a separate reasoning.effort contract and should be tested independently. For reasoning responses and multi-turn handling, see the site’s DeepSeek Thinking Mode guide.

6. Test streaming, tools, and structured workflows

Streaming

A parser built for deepseek-chat may only collect delta.content. In thinking mode, DeepSeek returns reasoning through delta.reasoning_content separately from final-answer content. Test both streams and confirm your UI, logs, and token accounting do not merge reasoning into the user-facing answer.

Tool-call history

If a thinking-mode request includes tools, DeepSeek requires the complete returned reasoning_content to be passed back in subsequent user-interaction requests—even when the model did not perform a tool call in that turn. Omitting it can return HTTP 400. When a call occurs, append the complete assistant message before the corresponding tool result.

// Preserve content, reasoning_content, and tool_calls together. messages.push(response.choices[0].message); messages.push({ role: "tool", tool_call_id: toolCall.id, content: JSON.stringify(toolResult), });

Test both tool-enabled branches: one where tools is present but no call occurs, and one complete tool-call loop. Replay the returned reasoning_content in the next user-interaction request in both cases. See the DeepSeek Tool Calls guide for validation and execution boundaries.

JSON Output and FIM

DeepSeek lists JSON Output and Tool Calls for all three current model IDs. FIM Completion is supported only by Flash and Pro in non-thinking mode and is not supported by Vision Exp. Regression-test every specialized workflow rather than treating a successful text prompt as complete migration coverage.

Cache and usage fields

DeepSeek context caching is enabled automatically; the model-name migration does not require a cache flag. Log usage.prompt_cache_hit_tokens, usage.prompt_cache_miss_tokens, output tokens, and reasoning tokens during the canary. A cache hit is best effort and should not be assumed from one repeated request.

7. Production migration and validation plan

Inventory both aliases. Search code, environment values, proxies, manifests, agent settings, tests, dashboards, and fallback lists.
Map by behavior. Use Flash plus thinking disabled for deepseek-chat; use Flash plus thinking enabled for deepseek-reasoner.
Validate configuration in CI. Fail the build when either legacy string remains in deployable configuration.
Deploy behind configuration control. Use a model setting or feature flag so the canonical ID can be changed without a code release.
Canary non-production traffic. Compare answer format, latency, token usage, cache fields, finish reasons, and errors.
Test both response paths. Run non-streaming and SSE tests for non-thinking and thinking requests.
Test both tools branches. Replay complete reasoning_content when tools is present, both without a call and through a full call/result loop; verify that neither next user-interaction request returns HTTP 400.
Regression-test specialized features. Include JSON Output, Tool Calls, FIM where used, stop sequences, and realistic context lengths.
Load-test the selected model. Flash and Vision Exp list 2,500 concurrent requests per account; Pro lists 500. Do not replace an alias with Pro or introduce Vision without capacity testing.
Remove the old fallback. Roll back to the previous application build with canonical V4 configuration—not to a retired model alias.

What to monitor during the canary

Signal	Why it matters
Requested model and thinking type	Proves the application sent the intended atomic profile
Returned model field	Detects unexpected routing or configuration
HTTP status and provider request ID	Supports error grouping and escalation without logging prompts
Latency to first token and total duration	Reveals accidental thinking activation or a tier change
`finish_reason`	Detects truncation, tool calls, filtering, or resource interruption
Input, output, reasoning, cache-hit, and cache-miss tokens	Measures the actual cost and cache behavior of the selected profile
Tool-loop HTTP 400 rate	Detects missing `reasoning_content` history
HTTP 429 rate and retry count	Shows whether the selected model exceeds account concurrency

Log metadata needed for operations, but do not place API keys, private prompts, raw customer documents, or unredacted personal data in observability systems. Compare the canary with a dated baseline; do not judge migration success from one hand-picked prompt.

Minimum test matrix

Test	Expected check
Flash, thinking disabled	Final `content` is parsed and the application does not depend on reasoning output
Flash, thinking enabled	`reasoning_content` and final `content` are handled separately
Streaming, both modes	Reasoning and answer deltas are routed correctly; stream completion is detected
Two-turn chat	Conversation history remains valid
Thinking plus `tools`, with and without an actual call	Complete returned reasoning history is replayed in both branches; no HTTP 400
JSON Output	Output parses and satisfies application validation
Context boundary	`finish_reason` and partial output are handled safely
Usage and cache	Token and cache fields are recorded without assuming every retry hits cache
Concurrency	429 retry and backoff behavior works at expected load
Model allowlist	Deployment contains only the explicitly approved subset of Flash, Pro, and Vision Exp; retired aliases are absent

Compare Flash and Pro on your text prompts before changing tiers. Evaluate Vision Exp separately for image workflows and interface-specific payloads. Use the dedicated DeepSeek API pricing page for dated pricing and concurrency values rather than copying a price snapshot into long-lived migration code.

Migration troubleshooting

Symptom	Likely cause	Action
Legacy model ID fails or is absent from the current model list	The retired alias was not replaced	Use a documented V4 ID and explicit thinking mode. Record the provider response; do not assume a guaranteed post-retirement error code.
`deepseek-chat` replacement is slower or returns reasoning	`deepseek-v4-flash` defaulted to thinking enabled	Add `thinking: { type: "disabled" }`
No effect from temperature or top_p	Thinking mode ignores these sampling controls.	If sampling control is required, test the task with thinking explicitly disabled.
No effect from presence_penalty or frequency_penalty	The current Chat Completions reference marks both parameters deprecated and ineffective.	Remove them; disabling thinking does not restore them. Check the current API contract.
HTTP 400 in a tool-enabled thinking conversation	`tools` was present but prior assistant `reasoning_content` was omitted	Replay the complete returned reasoning history, even for turns where no tool call occurred; when a call occurs, append the complete assistant message before its tool result
HTTP 401	Missing or invalid DeepSeek API key	Verify the server environment and authorization header
HTTP 422	Invalid request parameters	Compare the request with the V4 Chat Completion schema
HTTP 429	Account or model concurrency exceeded	Apply backoff and test against the selected model’s concurrency
Answer is cut off	`max_tokens` or total context limit reached	Inspect `finish_reason` and adjust the request safely
Unexpected cost or latency after moving to Pro	Pro was treated as a direct alias replacement	Return the canary to Flash and evaluate Pro as a separate upgrade

For status-specific diagnostics, see the DeepSeek API error codes guide. For the request and response structure, use the DeepSeek API guide.

Frequently asked questions

What is the direct replacement for `deepseek-chat`?

The behavior-preserving replacement is deepseek-v4-flash with thinking.type explicitly set to disabled.

What is the direct replacement for `deepseek-reasoner`?

The behavior-preserving replacement is deepseek-v4-flash with thinking.type explicitly set to enabled.

Is `deepseek-v4-pro` the new name for `deepseek-reasoner`?

No. Before the cutoff, DeepSeek documented the legacy reasoner alias as mapping to V4 Flash thinking mode. That was historical compatibility behavior. V4 Pro is a separate model choice that needs its own quality, cost, latency, and capacity evaluation.

Can I replace only the model string?

Not safely for deepseek-chat. Explicit V4 models default to thinking enabled, so you must disable thinking to preserve non-thinking behavior. For deepseek-reasoner, the default aligns with thinking mode, but setting it explicitly makes the migration auditable and prevents configuration ambiguity.

Do I need a new base URL or API key?

No change is documented for the canonical OpenAI-format base URL or DeepSeek API key. Keep https://api.deepseek.com and your existing secured DeepSeek key.

Which error will the retired aliases return?

DeepSeek has not documented one guaranteed post-cutoff status code. Chat-Deep.ai observed HTTP 400 for both aliases on July 25, but HTTP 200 with V4 Flash routing on July 28. Your migration test should therefore fail if an old alias remains in configuration even when the request succeeds; do not use an assumed 400, 404, or 422 response as the only detection rule.

Should I keep the old aliases as rollback values?

No. A rollback should restore a known application version while retaining canonical V4 model IDs. The retired aliases cannot provide a dependable post-cutoff rollback path.

Official sources

For related setup, endpoint, and production guidance, see the DeepSeek documentation hub.