You shipped a prototype against `deepseek-chat`, traffic grew, and now the bills, the latency tail, and the occasional empty JSON response are real problems. This guide is the set of DeepSeek API best practices I apply to my own V4 deployments after migrating from V3.2 the week the Preview dropped. It assumes you have an API key and a working OpenAI SDK call, and focuses on the choices that actually move cost, reliability, and quality once you go past “hello world.” You will get a tier-selection rubric, the parameter map for thinking mode, a worked cost calculation for both V4-Pro and V4-Flash, caching tactics, JSON-mode caveats, and an error-handling pattern that survives launch-week throttling.

What the DeepSeek API actually is in April 2026

The DeepSeek API is a stateless HTTP service that accepts OpenAI-compatible Chat Completions requests at POST /chat/completions against the base URL https://api.deepseek.com. As of the V4 Preview announcement on April 24, 2026, DeepSeek-V4-Pro has 1.6T total / 49B active params with performance rivaling top closed-source models, and DeepSeek-V4-Flash has 284B total / 13B active params as a fast, efficient, and economical choice. Both ship as open-weight Mixture-of-Experts models under the MIT license, both default to a 1,000,000-token context, and both can produce up to 384,000 output tokens per response.

Two architectural facts shape every best practice that follows. First, the API supports OpenAI ChatCompletions and Anthropic APIs, and both models support 1M context and dual modes (Thinking / Non-Thinking). Second, the API is stateless — DeepSeek does not retain conversation history server-side. The web chat at chat.deepseek.com keeps your sessions; the API does not. You resend the full messages array on every call.

Legacy IDs and the migration window

If your codebase still references deepseek-chat or deepseek-reasoner, it works today and will continue to work for a few more months. deepseek-chat and deepseek-reasoner will be fully retired and inaccessible after Jul 24th, 2026, 15:59 (UTC Time), currently routing to deepseek-v4-flash non-thinking/thinking. The migration is a one-line change: keep base_url, just update model to deepseek-v4-pro or deepseek-v4-flash. There is no excuse to leave it until retirement week. Switch in a feature flag, run for a day, delete the legacy ID. Our DeepSeek OpenAI SDK compatibility notes cover the exact import paths.

Quickstart: the call you should be making in 2026

Below is the minimal Python snippet I now use as a template. It targets deepseek-v4-flash — the right default for chat, classification, summarisation, and most agent tool-calls — and leaves thinking off for cost reasons.

from openai import OpenAI

client = OpenAI(
    api_key="sk-...",                 # from the DeepSeek console
    base_url="https://api.deepseek.com",
)

resp = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Explain context caching in two sentences."},
    ],
    temperature=1.3,                   # DeepSeek's recommended chat default
    max_tokens=512,
    stream=False,
)
print(resp.choices[0].message.content)

The same call against POST /chat/completions in curl looks like this; useful for smoke-testing from CI without an SDK:

curl https://api.deepseek.com/chat/completions 
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "ping"}],
    "max_tokens": 32
  }'

For a guided walkthrough of authentication, billing setup, and your first call, see our DeepSeek API getting started tutorial and the page on how to get a DeepSeek API key.

Pick the right tier — V4-Flash or V4-Pro

The single highest-leverage decision for a DeepSeek API production deployment is which tier you route to. V4-Pro is roughly an order of magnitude more expensive on output, so the default should be Flash, with Pro reserved for tasks that empirically benefit.

Rates are from DeepSeek’s official pricing page as of April 25, 2026 and corroborated by independent trackers such as deepseek-v4-flash costs $0.028 per 1M cache-hit input tokens, $0.14 per 1M cache-miss input tokens, and $0.28 per 1M output tokens; deepseek-v4-pro costs $0.145 per 1M cache-hit input tokens, $1.74 per 1M cache-miss input tokens, and $3.48 per 1M output tokens. Off-peak discounts that V3 users may remember are no longer in effect — they ended September 5, 2025 and were not reintroduced for V4. For a live calculator, see the DeepSeek pricing calculator.

A simple routing rule

1. Start every new feature on V4-Flash. Build evals.
2. If your eval shows V4-Flash failing on a category — typically agentic coding, multi-step tool use, or hard math — re-run that subset on V4-Pro.
3. If Pro lifts pass-rate by enough to justify ~7× output cost on those calls, route only that category to Pro. Keep everything else on Flash.

DeepSeek says both models are more efficient and performant than DeepSeek V3.2 due to architectural improvements, and have almost “closed the gap” with current leading models on reasoning benchmarks; V4-Pro-Max outstrips OpenAI’s GPT-5.2 and Gemini 3.0 Pro on some tasks, but those wins concentrate in maximum-effort thinking — not the cheap fast path most chat traffic should take.

Use thinking mode deliberately, not by default

In V4, thinking is a request parameter on either tier, not a separate model ID. Three settings:

• Non-thinking — omit reasoning_effort and the thinking flag. Fastest and cheapest. The right default for chat, RAG, and structured extraction.
• Thinking (high) — reasoning_effort="high" with extra_body={"thinking": {"type": "enabled"}}. Returns reasoning_content alongside the final content. Use for multi-step reasoning, planning, hard math.
• Thinking-max — reasoning_effort="max". Reserved for the hardest agent and reasoning workloads. For the Think Max reasoning mode, set the context window to at least 384K tokens or you will get truncated outputs.

One trap: thinking mode does not support the temperature, top_p, presence_penalty, or frequency_penalty parameters; for compatibility, setting these will not trigger an error but will also have no effect. If your code carefully tunes temperature=0.0 for code generation and you flip thinking on, the temperature is silently ignored. Plan accordingly.

A thinking-mode call:

resp = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Plan a zero-downtime DB migration."}],
    reasoning_effort="high",
    extra_body={"thinking": {"type": "enabled"}},
)
print(resp.choices[0].message.reasoning_content)  # the thinking trace
print(resp.choices[0].message.content)            # the final answer

Tune temperature to the task

DeepSeek publishes specific temperature recommendations — match them unless you have a reason not to.

If you find yourself at temperature=0.7 across the board, you are probably leaving determinism on the table for code paths and creativity for writing paths. More on prompt-side tuning lives in our DeepSeek prompt engineering guide.

Caching: the cheapest 80% you will ever buy

Context caching applies automatically when DeepSeek detects a repeated message prefix. The cache-hit input rate is 5× cheaper than the cache-miss rate on V4-Flash and 12× cheaper on V4-Pro. The implications:

• Put the long, stable content (system prompt, retrieval results that recur, few-shot examples) at the beginning of messages. Volatile content (the user’s new question) goes last.
• Avoid timestamps, request IDs, or randomised greetings in your system prompt. Each one is a cache-miss waiting to happen.
• Cache hits do not free you from paying for the user’s new tokens. The miss line in your bill is the new turn against the cached prefix.

For implementation specifics and how the prefix matcher behaves under streaming and tool calls, see our deep dive on DeepSeek context caching.

A worked cost example for both tiers

Workload: 1,000,000 calls per day, each with a 2,000-token system prompt that the cache catches, a 200-token user message that does not, and a 300-token response.

V4-Flash (the default recommendation)

Cached input :  2,000 × 1,000,000 = 2,000,000,000 tok × $0.028/M = $56.00
Uncached in  :    200 × 1,000,000 =   200,000,000 tok × $0.14/M  = $28.00
Output       :    300 × 1,000,000 =   300,000,000 tok × $0.28/M  = $84.00
                                                                  -------
Total                                                              $168.00

V4-Pro (frontier-tier, same workload)

Cached input :  2,000,000,000 tok × $0.145/M = $290.00
Uncached in  :    200,000,000 tok × $1.74/M  = $348.00
Output       :    300,000,000 tok × $3.48/M  = $1,044.00
                                                --------
Total                                            $1,682.00

Same traffic, ten times the bill. If your eval does not show a meaningful win for Pro on the workload, the math is the answer. The DeepSeek cost estimator automates the same arithmetic against your own token volumes; the DeepSeek token counter helps you measure them in the first place.

JSON mode without the empty-string bug

JSON mode is set with response_format={"type": "json_object"}. DeepSeek’s docs describe it as designed to return valid JSON, not guaranteed. Three rules:

1. Include the literal word “json” in your prompt and a small example schema. The model uses both signals.
2. Set max_tokens high enough to cover the worst-case output. A truncated JSON object is invalid JSON.
3. Always handle the empty-content case. The API can return an empty string under load; treat it like a transient error and retry once.

A defensive pattern:

resp = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system",
         "content": "Reply only as JSON matching {"sentiment": "pos|neg|neu"}."},
        {"role": "user", "content": review_text},
    ],
    response_format={"type": "json_object"},
    max_tokens=128,
    temperature=0.0,
)
raw = resp.choices[0].message.content or ""
try:
    parsed = json.loads(raw)
except json.JSONDecodeError:
    parsed = retry_or_fallback()

Full request/response shapes and edge cases are catalogued in the DeepSeek JSON mode reference.

Streaming and tool calling

Set stream=True to receive server-sent-event chunks. With thinking enabled, reasoning_content streams alongside the final content — render them in separate UI surfaces or you will confuse end users. For implementation patterns including backpressure handling, see our DeepSeek API streaming guide.

Tool calling uses the OpenAI-compatible tools array. It works in both thinking and non-thinking modes. DeepSeek-V4 is integrated with leading AI agents like Claude Code, OpenClaw and OpenCode, which is a direct consequence of OpenAI- and Anthropic-compatible surfaces — your existing tool definitions port cleanly. The function calling reference covers the exact JSON-schema requirements.

FIM and Chat Prefix Completion (Beta)

Both are useful — Fill-In-the-Middle for code editors, Chat Prefix Completion for continuation-style prompts where you need the model to extend a partial assistant message. FIM is non-thinking-only; do not pass reasoning_effort in FIM calls.

Error handling that survives launch week

Treat the API as eventually reliable, not always reliable. The error envelope is OpenAI-shaped, so existing retry middleware works.

Two operational habits I recommend:

• Idempotency. Hash (model, messages, temperature, seed) and cache successful responses for ~60 seconds. Cuts duplicate spend on retried client calls.
• Tier fallback. If V4-Pro returns 503, retry the request on V4-Flash with the same body. Most traffic is fine on Flash; degraded mode beats outage.

The full status code map is in our DeepSeek API error codes reference, and rate-limit specifics live in DeepSeek API rate limits.

Observability and security checklist

• Log usage.prompt_tokens, usage.completion_tokens, and the cached/uncached split on every response. Without this, you cannot debug a bill.
• Store API keys in your secrets manager, not in .env files committed by accident. Rotate quarterly.
• Consider data residency: requests go to DeepSeek-operated infrastructure subject to Chinese law. For regulated workloads, evaluate self-hosting the open weights — see our notes on running DeepSeek through DeepSeek Docker deployment.
• Pin model strings; do not interpolate from user input.
• Set per-tenant token budgets in your application layer. Provider-side limits are coarse.

For more on the broader ecosystem and where the API fits, see the DeepSeek API docs and guides hub.

Last verified: 2026-04-25. DeepSeek AI Guide is an independent resource and is not affiliated with DeepSeek or its parent company. Model IDs, pricing and API behaviour change; check the official DeepSeek documentation and pricing page before committing to a production decision.