DeepSeek API Getting Started: A Step-by-Step Quickstart

If you have an OpenAI or Anthropic client already wired up, the deepseek api getting started path is short enough to finish before your coffee cools: change a base URL, paste an API key, pick a model ID, and send a request. That’s the good news. The rest of this guide covers what the quickstart pages usually gloss over — which of the two current models to pick, how thinking mode toggles, why the API is stateless even though the web chat isn’t, and how to cost a workload without surprise bills.

Every step follows DeepSeek’s official API documentation as of October 2026. By the end you’ll have a working Python call, a correct cost estimate, and a migration plan for legacy model IDs.

What you’ll build in this guide

Three concrete outcomes: a working POST /chat/completions request in Python against deepseek-flash, a second call that switches thinking mode on and off and tries deepseek-v4-pro, and a cost estimate for a realistic workload with cache-hit, cache-miss and output tokens broken out. Everything uses the official OpenAI SDK — DeepSeek’s chat surface is wire-compatible, so you do not need a DeepSeek-specific client library.

A short orientation before the steps. DeepSeek’s API lists two model IDs (October 2026): deepseek-flash, served by DeepSeek-V4.1-Flash-1017 (released 17 October 2026), and deepseek-v4-pro, served by DeepSeek-V4-Pro-0813 (released 13 August 2026). Both have open weights under the MIT license, a 1M-token context window and up to 384K tokens of output, and both support thinking and non-thinking mode, with thinking on by default. Thinking mode is a request parameter on either model, not a separate model ID. Only deepseek-flash accepts image input.

Prerequisites

• Python 3.10+ with pip available, or Node.js 22+ if you prefer JavaScript (the minimums of the current openai packages on PyPI and npm, checked 25 October 2026).
• A DeepSeek platform account and an API key. If you do not have one yet, walk through our companion piece on how to get a DeepSeek API key first.
• A small top-up on your DeepSeek balance. A short first call on deepseek-flash costs a fraction of a cent at the rates in Step 6; keep deepseek-v4-pro experiments short until you’ve seen the cost math.
• Familiarity with environment variables. Never hardcode the key in a file you might commit.

Step 1: Install the OpenAI SDK

Because DeepSeek exposes an OpenAI-compatible wire format, any OpenAI client works once you redirect it. Install the official SDK with pip:

pip3 install openai

Node.js users can run npm install openai instead. DeepSeek also offers an Anthropic-compatible format at a separate base URL, https://api.deepseek.com/anthropic, so the Anthropic SDK is an alternative if your codebase already uses it. See our notes on DeepSeek OpenAI SDK compatibility for the parameter-by-parameter mapping.

Step 2: Store your API key safely

Export the key to your shell so it lives outside your source tree:

export DEEPSEEK_API_KEY="<your DeepSeek API key>"

On Windows PowerShell, use $env:DEEPSEEK_API_KEY = "<your DeepSeek API key>". For longer-term setups, put it in a .env file that is in .gitignore. If the key ever leaks, delete it and create a new one on the API keys page of the DeepSeek platform — there’s more detail in our writeup on DeepSeek API authentication.

Step 3: Make your first request

The canonical chat endpoint is POST /chat/completions, reached via base_url="https://api.deepseek.com". This is the Python example from DeepSeek’s Your First API Call page, with thinking mode written out explicitly:

# Please install OpenAI SDK first: `pip3 install openai`
import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="deepseek-flash",
    messages=[
        {"role": "system", "content": "You are a helpful assistant"},
        {"role": "user", "content": "Hello"},
    ],
    stream=False,
    reasoning_effort="high",
    extra_body={"thinking": {"type": "enabled"}},
)

print(response.choices[0].message.content)

If you prefer curl, the same call looks like this:

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
        "model": "deepseek-flash",
        "messages": [
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "Hello!"}
        ],
        "thinking": {"type": "enabled"},
        "reasoning_effort": "high",
        "stream": false
      }'

And in Node.js (save as index.mjs so the import syntax works):

// Please install OpenAI SDK first: `npm install openai`
import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "https://api.deepseek.com",
  apiKey: process.env.DEEPSEEK_API_KEY,
});

async function main() {
  const completion = await openai.chat.completions.create({
    messages: [{ role: "system", content: "You are a helpful assistant." }],
    model: "deepseek-flash",
    thinking: { type: "enabled" },
    reasoning_effort: "high",
    stream: false,
  });
  console.log(completion.choices[0].message.content);
}

main();

Set stream to true to receive the response as a stream instead.

Picking the right temperature

Thinking mode, the default, does not support temperature, presence_penalty or frequency_penalty — they are accepted without error but have no effect. To use DeepSeek’s temperature guidance, switch thinking off for the request:

resp = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Summarise MoE architecture in two sentences."}],
    temperature=1.3,
    max_tokens=400,
    extra_body={"thinking": {"type": "disabled"}},
)
print(resp.choices[0].message.content)

DeepSeek’s task-specific values for non-thinking mode:

• 0.0 — code generation and mathematics.
• 1.0 — data analysis and data cleaning.
• 1.3 — general conversation and translation.
• 1.5 — creative writing and poetry.

top_p behaves differently per model: on deepseek-flash it only takes effect in thinking mode (effective range 0.95–1.0), while on deepseek-v4-pro it is ignored in thinking mode and takes effect in non-thinking mode. Use max_tokens to cap output length — especially important with JSON mode, where truncation produces invalid output.

Step 4: Control thinking mode on deepseek-v4-pro

Thinking is enabled by default, with effort high. Use extra_body={"thinking": {"type": "disabled"}} for non-thinking mode. Set reasoning_effort to "low", "high" or "max" on either model — DeepSeek’s guidance is low for simple tasks, high for daily agent tasks and max for more complex scenarios (other values are mapped: minimal → low, medium and xhigh → high, ultra → max). When thinking is enabled the API returns reasoning_content alongside the final content.

resp = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Plan a zero-downtime Postgres 14-to-16 upgrade."}],
    reasoning_effort="max",
    extra_body={"thinking": {"type": "enabled"}},
)

print("Reasoning:", resp.choices[0].message.reasoning_content)
print("Answer:", resp.choices[0].message.content)

Use non-thinking mode for latency-sensitive or high-volume chat; use thinking mode when the task needs planning, multi-step reasoning, or agentic tool calls. In a multi-turn conversation without tools you do not need to send reasoning_content back; with tools, you must pass back the reasoning_content of all previous turns or the API returns a 400 error.

Step 5: Know which model ID to send

Here’s the current state, including the legacy names you may still find in older code:

If an integration still sends a legacy name, migration is a one-line model= swap — base_url does not change. DeepSeek’s 10 September 2026 Change Log puts it simply: “Change the model name to deepseek-flash to call the latest V4.1 Flash model.” For background on the model line, see our DeepSeek V4 models explainer.

Step 6: Cost your workload correctly

Both models have three token buckets: cache-hit input, cache-miss input, and output. Omitting any of them — particularly the uncached user message on each call — produces an optimistic estimate that reality will not honour. Each bucket also has a peak and an off-peak rate: peak hours are 01:00–04:00 and 06:00–10:00 UTC, Monday to Friday, excluding Chinese public holidays; all other hours are off-peak, at half the peak rate.

deepseek-flash rates (per 1M tokens, as of October 2026)

deepseek-v4-pro rates (per 1M tokens, as of October 2026)

Worked example: 1,000,000 deepseek-flash calls

Assume a 2,000-token cached system prompt, 200 uncached user-message tokens per call, and a 300-token response:

• 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

The same workload on deepseek-v4-pro costs $88.00 + $264.00 + $1,188.00 = $1,540.00 at peak and $44.00 + $132.00 + $594.00 = $770.00 off-peak — about 3.6× the Flash total. Real traffic usually straddles both periods, so the bill lands between the two totals. deepseek-flash is the sensible default for chat, summarisation and standard tool calling; DeepSeek’s 10 September 2026 news page says tests by multiple parties put V4.1-Flash ahead of V4-Pro on performance, cost, speed and total runtime, so check that deepseek-v4-pro improves results on your own tasks before paying more. Prices are from DeepSeek’s Models & Pricing page; check it and our DeepSeek API pricing page before committing numbers to a business case, and use our DeepSeek pricing calculator for arbitrary workloads.

Step 7: Handle statelessness

The API is stateless — you must resend the conversation history with each request. That contrasts with the web chat and mobile app, which maintain session history for you. A multi-turn pattern looks like this:

history = [{"role": "system", "content": "You are a terse assistant."}]

def turn(user_text):
    history.append({"role": "user", "content": user_text})
    resp = client.chat.completions.create(
        model="deepseek-flash",
        messages=history,
    )
    reply = resp.choices[0].message.content
    history.append({"role": "assistant", "content": reply})
    return reply

Because DeepSeek bills cache hits at a fraction of the miss rate, repeated stable prefixes — a long system prompt, a retrieval preamble, a tool schema — get cheap on subsequent calls. Our guide to DeepSeek context caching covers the prefix rules.

Step 8: Add JSON mode, tools, and streaming when you need them

Three features cover most needs beyond simple chat:

• JSON mode. Set response_format={"type": "json_object"}. It is designed to return valid JSON, not guaranteed. Include the word “json” plus a small example schema in the prompt, set max_tokens high enough to avoid truncation, and handle occasional empty content gracefully.
• Tool calling. Declare tools in the OpenAI-compatible format; supported in both thinking and non-thinking modes. In thinking mode, pass back the reasoning_content of every previous turn when the request carries tools, or the API returns a 400 error. Useful for routing to search, calculators, or internal APIs.
• Streaming. Pass stream=True to get server-sent-events chunks. When thinking is enabled, reasoning content streams alongside the final answer — render them into separate UI panes if you show them to end users.

Two Beta features are worth knowing about: FIM (Fill-In-the-Middle) completion for code use cases (non-thinking mode only — pass extra_body={"thinking": {"type": "disabled"}}), and Chat Prefix Completion for continuation-style prompts.

Verify it worked

A quick checklist after your first successful call:

1. Response status was 200 and choices[0].message.content is non-empty.
2. The usage field reports the token counts DeepSeek bills on.
3. For thinking-mode calls, reasoning_content is populated in addition to content.
4. You can reproduce the cost math in Step 6 against the usage numbers.

Common errors and fixes

Next steps

You now have a working integration, a correct cost model, and a migration plan. From here, two directions are worth your time: harden the developer ergonomics (streaming, tool calling, JSON mode) with the examples in our DeepSeek API code examples, or push into agentic and RAG workloads with the DeepSeek RAG tutorial. If you want the full landscape of developer resources, the DeepSeek tutorials hub has the rest of the sequence.