DeepSeek API Guide: Setup, V4 Models and Working Examples

The DeepSeek API uses the OpenAI-compatible base URL https://api.deepseek.com. Create an API key, choose deepseek-v4-flash or deepseek-v4-pro, and send requests through Chat Completions or the Responses API. Both current V4 models support the Responses API.

This independent DeepSeek API guide provides working cURL, PowerShell, Python, and Node.js examples; explains the current V4 models, pricing, thinking mode, streaming, tools, errors, and context caching; and publishes redacted results from our own API checks. Current documentation and pricing were last verified on August 16, 2026; dated API test results remain tied to their recorded run dates. Chat-Deep.ai is not the official DeepSeek Platform.

DeepSeek API quickstart in 60 seconds

1. Create and store an API key

Sign in to the official DeepSeek Platform, create a key, and copy it once. Never paste a real key into browser tools, frontend JavaScript, screenshots, public repositories, or support messages.

Store the key in an environment variable for the current terminal session:

# macOS or Linux
export DEEPSEEK_API_KEY="replace-with-your-key"

# Windows PowerShell
$env:DEEPSEEK_API_KEY = "replace-with-your-key"

2. Send a minimal request

This cURL request uses the current Flash model and explicitly disables thinking for a short connectivity check:

curl --silent --show-error --fail \
  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": "Reply with exactly: API_OK"}
    ],
    "thinking": {"type": "disabled"},
    "max_tokens": 16
  }'

A successful response is HTTP 200. Read the answer from choices[0].message.content and token counts from usage. The API can include other documented response fields, so production code should validate required fields without rejecting harmless additions.

3. Separate authentication, balance, and service health

A valid key is not proof of sufficient credit, and a funded account is not proof that every model is healthy. Use the read-only DeepSeek balance endpoint for current funding availability and DeepSeek status for incident checks.

For dated multi-region measurements rather than a provider SLA, use our independent DeepSeek API reliability and performance report, which publishes validated observations, latency percentiles, and downloadable data.

DeepSeek V4 models and current API status

DeepSeek's August 13, 2026 change log rolled out DeepSeek-V4-Pro-0813 as GA on App, Web, and API. The deepseek-v4-pro request ID did not change. Flash continues to serve DeepSeek-V4-Flash-0731 in public beta behind deepseek-v4-flash.

Dated test boundary: our August 3 live test returned HTTP 400 for Pro Responses before the August 13 GA rollout. That result remains valid evidence for its test date, but it is not the current support contract. The current Responses API reference lists both V4 model IDs.

The older names deepseek-chat and deepseek-reasoner were scheduled for discontinuation on July 24, 2026. New code should use the V4 model IDs. Our live compatibility table records what the legacy names actually returned at the verification time without treating a past schedule as present availability.

Working DeepSeek API examples

Every example in this section is designed to run as shown after the environment variable is set. The validation table records the exact runtime, dependency version, exit status, HTTP status, and observed output from the published blocks.

Windows PowerShell

$headers = @{
  Authorization = "Bearer $env:DEEPSEEK_API_KEY"
  "Content-Type" = "application/json"
}

$body = @{
  model = "deepseek-v4-flash"
  messages = @(
    @{ role = "user"; content = "Reply with exactly: API_OK" }
  )
  thinking = @{ type = "disabled" }
  max_tokens = 16
} | ConvertTo-Json -Depth 5

$response = Invoke-RestMethod `
  -Method Post `
  -Uri "https://api.deepseek.com/chat/completions" `
  -Headers $headers `
  -Body $body

$response.choices[0].message.content

Python with the OpenAI SDK

Install the current OpenAI Python package with python -m pip install --upgrade openai, then run:

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": "Reply with exactly: API_OK"}
    ],
    max_tokens=16,
    extra_body={"thinking": {"type": "disabled"}},
)

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

For setup, typed parsing, streaming, async calls, and environment troubleshooting, see the full DeepSeek Python SDK guide.

Node.js with the OpenAI package

Install the dependency with npm install openai. Save this as an ES module such as deepseek.mjs:

import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    { role: "user", content: "Reply with exactly: API_OK" },
  ],
  thinking: { type: "disabled" },
  max_tokens: 16,
});

console.log(response.choices[0].message.content);

Use the dedicated DeepSeek Node.js and TypeScript guide for strict TypeScript typing, server frameworks, and production project structure.

Exact code validation results

We copied each block from the saved article without rewriting it. Python and Node.js were executed against the live API with the temporary environment variable; cURL and PowerShell were executed unchanged against a local contract endpoint because the Windows test runner’s TLS stack failed before it could deliver those two live requests. The key, full response body, request ID, and account data were not published.

The Python and Node.js blocks were executed live exactly as published. The cURL and PowerShell request shapes, headers, JSON bodies, and output selectors passed unchanged against a local contract endpoint, but are not presented as live executions because the runner’s Windows TLS stack failed before those requests reached DeepSeek.

DeepSeek Responses API: support and differences

DeepSeek's native Responses API now supports both deepseek-v4-flash and deepseek-v4-pro at the same https://api.deepseek.com base URL. The interface remains stateless, so clients must resend the required conversation history. The August 3 test table below is retained as dated pre-GA evidence.

import os
from openai import OpenAI

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

response = client.responses.create(
    model="deepseek-v4-flash",
    instructions="Reply with exactly API_OK.",
    input="Run the connectivity check.",
)

print(response.output_text)

DeepSeek's Responses API is stateless. It does not support previous_response_id, conversation, or server-side store; the response reports store: false. Unsupported parameters may be silently ignored, so a request returning HTTP 200 does not prove that every requested feature was applied. Validate the returned behavior and fields.

Responses API streaming

Responses streaming uses semantic server-sent events with increasing sequence numbers. It ends with response.completed, response.incomplete, or response.failed; unlike Chat Completions streaming, it does not end with data: [DONE].

stream = client.responses.create(
    model="deepseek-v4-flash",
    instructions="Answer in one short sentence.",
    input="What is an API?",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Thinking mode and reasoning effort

Thinking mode is enabled by default. In the OpenAI Chat Completions format, toggle it with {"thinking":{"type":"enabled"}} or disabled, and control depth with reasoning_effort. With the Python OpenAI SDK, pass the DeepSeek-specific thinking object through extra_body.

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "user", "content": "Which is larger: 9.11 or 9.8?"}
    ],
    reasoning_effort="high",
    extra_body={"thinking": {"type": "enabled"}},
)

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

The current mapping is identical for both V4 models. The documented direct Chat effort values are low, high, and max; compatibility inputs medium and xhigh map to high. Thinking is enabled by default with high effort. In thinking mode, temperature, top_p, presence_penalty, and frequency_penalty have no effect even though compatibility behavior may avoid an error.

If a thinking-mode turn performs a tool call, preserve and send its complete reasoning_content with the assistant tool-call message in subsequent turns. DeepSeek documents a 400 error when that required content is omitted. See our thinking mode guide for the complete message loop.

Streaming, JSON output, and tool calls

Chat Completions streaming

Set stream: true to receive data-only SSE chunks. Chat Completions streaming ends with data: [DONE]. DeepSeek may send : keep-alive comments while a request waits for inference; a custom parser must ignore those comments rather than treating them as JSON.

For end-to-end timing, measure request start, response headers, first reasoning token, first answer token, and final event separately. A single “latency” number hides the difference between queueing and generation.

JSON output

Chat Completions: set response_format to {"type":"json_object"}, include the word “json” in the prompt, show the desired shape, and validate the result. Responses API: use text.format with type: "json_object" or type: "json_schema"; schema mode also requires a name and a valid JSON Schema object. Allow enough output tokens to avoid truncation, and validate every response. The full implementation is in our DeepSeek JSON output guide.

Tool calls

Tool calling lets the model request a function; your application remains responsible for validating arguments, authorizing the action, running the function, and returning the result. Both current V4 models support tools. Strict tool schemas are a beta feature that require the https://api.deepseek.com/beta base URL and a supported JSON Schema subset. Use the DeepSeek tool-calling guide for a complete safe loop.

Multi-turn requests and context caching

Chat Completions and Responses are stateless: the application sends the history needed for each turn. Keep only relevant messages, summarize when appropriate, and budget the entire repeated prefix. DeepSeek's context cache is automatic. In response usage, cached input is reported separately; no manual cache key is required.

Cache hits depend on repeated prefixes. Preserve stable system instructions and shared context at the beginning, then append changing user data. Do not treat caching as a privacy boundary; use documented user_id isolation and keep personal data out of identifiers. See the context caching guide for measurement and cost calculations.

Observed cache result: we sent the same 890-token prefix three times. The first request reported 0 cache-hit tokens and 890 misses. Requests two and three each reported 768 cache-hit tokens and 122 misses, an 86.3% hit share for this fixture. That is a dated observation, not a guarantee that every repeated prompt will be cached.

DeepSeek API endpoints and compatibility

OpenAI compatibility does not mean every OpenAI endpoint, parameter, tool, modality, or persistence feature exists. Keep compatibility tests in CI, pin SDK versions where appropriate, and inspect DeepSeek's current API documentation before adopting a new client feature. Our OpenAI SDK migration guide covers the required configuration changes.

DeepSeek API pricing

DeepSeek bills input and output tokens, with a lower input rate for cache hits. Both tables use USD per one million tokens. The first table contains the current rates; the second table preserves the historical rates that were effective through August 16, 2026 at 15:59 UTC.

Current pricing: DeepSeek applies peak rates during 01:00–04:00 and 06:00–10:00 UTC and off-peak rates at all other times. Peak rates are twice the current off-peak rates.

Always confirm the official current pricing before budgeting.

Use our DeepSeek API pricing guide for billing interpretation or the DeepSeek API cost calculator to model cache-hit, cache-miss, and output tokens without sending a request.

Original DeepSeek API test results

We ran a preregistered, low-cost compatibility suite from a managed test environment (network region not asserted) between 2026-08-03T23:16:24Z and 2026-08-03T23:26:05Z. Calls were sequential with concurrency one, a 60-second timeout, and no automatic retries. The temporary API key remained in process memory and was never written to evidence files.

Frozen test evidence: the tables in this section report the August 3 run exactly as observed. The Pro Responses limitation, the effort mapping quoted inside the result matrix, and phrases such as “use Flash for now” are scoped to that pre-GA test date. DeepSeek changed the current contract on August 13; the present-day guidance appears above.

Timing, tokens, and cost

These tests establish point-in-time contract behavior, not a provider SLA, universal latency ranking, or regional availability claim. The Pro output-budget control shows why reasoning workloads need headroom. The legacy aliases still routed to Flash on the test date, but explicit V4 IDs remain the production recommendation. The undocumented medium effort value was accepted but is not represented here as supported. Costs are deterministic estimates from observed usage and the dated standard list prices, not invoice readings.

For a dedicated evaluation of very large Chat Completions requests rather than short contract checks, see the reproducible long-context API benchmark with matched V4 Flash and Pro cases and downloadable data.

Download the sanitized test harness, runnable examples, assertions, and redacted result format from the DeepSeek API request builder repository on GitHub. No credential, raw authenticated response, request identifier, or account value is included.

DeepSeek API request builder and error decoder

Choose an API surface, model, thinking setting, and common feature to generate cURL, PowerShell, Python, or Node.js code. The tool also explains common HTTP errors. It runs entirely in your browser, never asks for an API key, never sends an API request, and does not store your selections.

The generated code deliberately contains an environment-variable reference instead of a credential. Review generated requests before running them, particularly beta features, tools, and any operation that can trigger external actions.

DeepSeek API errors and production checklist

DeepSeek documents account-level concurrency of 2,500 for Flash and 500 for Pro. Exceeding the applicable limit returns 429. Requests can remain connected while waiting; non-streaming responses may receive empty lines and streaming responses may receive keep-alive comments. If inference has not started after ten minutes, the server closes the connection.

• Keep API keys in a secret manager or protected server environment, never client-side code.
• Set connect, first-byte, idle, and overall timeouts intentionally instead of one ambiguous timeout.
• Retry only transient failures with exponential backoff, jitter, a maximum attempt count, and duplicate-work protection.
• Validate structured output and tool arguments before using them.
• Track model, endpoint, HTTP status, duration, token fields, cache fields, and finish reason without storing prompts by default.
• Use application-generated pseudonymous user_id values; do not put personal information in them.
• Keep a feature-compatibility test because unsupported Responses parameters can be silently ignored.
• Monitor the official change log and re-run contract tests before changing models or SDK versions.

For deeper handling, use the DeepSeek error-code guide, rate-limit guide, API testing guide, and observability guide.

DeepSeek API FAQ

Is the DeepSeek API free?

The DeepSeek API is usage-billed according to input, output, and cache-hit token rates. An account may have granted credit, but availability and amount are account-specific. Check the official Billing page and current pricing rather than assuming a permanent free tier.

What is the DeepSeek API base URL?

The OpenAI-compatible base URL is https://api.deepseek.com. The separate Anthropic-compatible base URL is https://api.deepseek.com/anthropic.

Which DeepSeek API model ID should I use?

Use deepseek-v4-flash for the current Flash model or deepseek-v4-pro for Pro. Avoid starting new integrations with the retired or legacy aliases deepseek-chat and deepseek-reasoner.

Does DeepSeek support the OpenAI Responses API?

Yes. The native Responses API supports both deepseek-v4-flash and deepseek-v4-pro. The API is stateless, so send the required history in each request. The August 3 Pro rejection shown above remains a dated pre-GA observation.

Can I use the OpenAI SDK with DeepSeek?

Yes. Set your DeepSeek key and change base_url or baseURL to https://api.deepseek.com. Compatibility is not universal: test the endpoints, parameters, tools, and modalities your application actually uses.

What is the DeepSeek API context window?

DeepSeek's current model table lists a 1M-token context window and 384K maximum output for both V4 Flash and V4 Pro. A request exceeding the context limit can return HTTP 400, so reserve space for the requested output and tool messages.

Is the DeepSeek API the same as DeepSeek Chat?

No. The API is a metered developer service on the DeepSeek Platform, while the web and app products provide an end-user chat interface. Model availability, billing, limits, and release timing can differ.

Why does the DeepSeek API return 429?

HTTP 429 means the applicable rate or concurrency limit was reached. Concurrency is calculated at account level across keys. Reduce parallel work, queue requests, and retry with bounded exponential backoff and jitter.

Official sources and update log

• DeepSeek API change log
• Models and pricing
• Responses API reference
• Thinking mode guide
• Rate Limit and Isolation
• Official error codes
• Create Chat Completion reference

Editorial standard: Published prices and capabilities are sourced from DeepSeek's primary documentation. Live-test statements are limited to the exact dated observations shown above. Planned features are described as plans, not as completed releases.