DeepSeek API Guide: Setup, V4 Models and Working Examples

The DeepSeek API uses the OpenAI-compatible base URL https://api.deepseek.com. Its current V4 API catalog has three IDs: text-only deepseek-v4-flash and deepseek-v4-pro, plus the experimental multimodal deepseek-v4-flash-vision-exp for image understanding. All three support Chat Completions and the Responses API.

This independent DeepSeek API guide provides working cURL, PowerShell, Python, and Node.js examples; explains the current V4 models, Vision image input, pricing, thinking mode, streaming, tools, errors, and context caching; and publishes redacted results from our own API checks. DeepSeek’s official model, pricing, Vision, Responses, Files, Thinking Mode, and Tool Calls documentation was last verified on August 24, 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. DeepSeek now also lists the experimental deepseek-v4-flash-vision-exp, serving DeepSeek-V4-Flash-Vision-Exp for multimodal image understanding.

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 all three V4 model IDs. Vision Exp was not part of that August 3 test.

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.

DeepSeek Vision image input: URL, Base64, and file_id

deepseek-v4-flash-vision-exp is the V4 API model for image understanding. deepseek-v4-flash and deepseek-v4-pro remain text-only. DeepSeek accepts JPEG, PNG, GIF, and WebP images in user messages through three methods. General-purpose files such as PDF, DOCX, spreadsheets, archives, and arbitrary text files remain unsupported; the current Files API is specifically for supported image formats.

This Chat Completions example uses a public URL. To send Base64 instead, replace the URL with a complete data URL such as data:image/jpeg;base64,<BASE64_DATA>.

curl https://api.deepseek.com/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-vision-exp",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Describe this image."},
        {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
      ]
    }]
  }'

For a reusable image, upload it with purpose user_data, keep the returned file_id, and reference that ID in the model request. The Files API does not turn unsupported documents into valid inputs.

from openai import OpenAI
import os

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

with open("image.png", "rb") as image:
    uploaded = client.files.create(file=image, purpose="user_data")

response = client.chat.completions.create(
    model="deepseek-v4-flash-vision-exp",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What is in this image?"},
            {"type": "file", "file_id": uploaded.id},
        ],
    }],
)

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

In the Responses API, put the prompt in an input_text part and the image in an input_image part. Supply either image_url—for a public URL or Base64 data URL—or file_id; do not send both in the same image part. See DeepSeek’s official Vision guide, Files API guide, and our complete Vision Exp model guide.

Important limits: a single inline or external image can be up to 32 MiB, a Files API image up to 64 MiB, and a request can contain up to 600 images. Total image payload is limited to 64 MiB without file_id and up to 200 MiB with it. DeepSeek resizes images for inference and bills the resulting image tokens as input tokens, with a maximum of 384 input tokens per image.

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

For the frozen model-by-case evidence behind those capabilities, read the 48-result Responses compatibility audit: 34 PASS and 14 FAIL across Flash and Pro, with Web Search run as a separate six-result track.

DeepSeek's native Responses API supports deepseek-v4-flash, deepseek-v4-pro, and deepseek-v4-flash-vision-exp 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 and predates Vision Exp.

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.

If the goal is a first-party agent interface rather than direct HTTP integration, continue with the DeepSeek Harness 0.1.1 series setup guide. The latest verified official GitHub release/tag is dsh-v0.1.1-rc.2, a pre-release; do not infer that a stable 0.1.1 package exists.

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 published effort-mapping table above is specifically for Flash and Pro; it should not be generalized to Vision Exp without model-specific documentation. For Flash and Pro, 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 Chat Completions request does not include tools, prior reasoning_content may be omitted and is ignored if supplied. If the request includes tools, preserve every complete reasoning_content value returned by the assistant in all subsequent requests between user messages—even when the model did not make a tool call. DeepSeek documents a 400 error when required reasoning 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. DeepSeek’s current model table lists tool-call support for Flash, Pro, and Vision Exp. 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. Images are converted to input tokens and billed at the model’s input rate. Both tables use USD per one million tokens. The first table contains the current rates; the second table preserves the historical Flash and Pro rates that were effective through August 16, 2026 at 15:59 UTC, before Vision Exp appeared in the current catalog.

Current pricing: DeepSeek applies peak rates from Monday through Friday during 01:00–04:00 and 06:00–10:00 UTC. All other times, including all day Saturday and Sunday, are off-peak. 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 “Two model IDs” result, 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. Vision Exp was not part of that run. DeepSeek changed the current contract after the test; the August 21 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, one of the three current model IDs, thinking settings, image source when using Vision Exp, and common features to generate cURL, PowerShell, Python, Node.js, or raw JSON. The tool also explains common HTTP errors. It runs entirely in your browser, never asks for an API key, never uploads an image, never sends an API request, and does not store your selections.

The generated code deliberately contains an environment-variable reference instead of a credential. For Vision examples it accepts only a URL, a complete Base64 data URL, or a previously created image file_id; it does not read or upload local files. Review generated requests before running them, particularly experimental models, 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, 500 for Pro, and 2,500 for Vision Exp. 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 efficient text workloads, deepseek-v4-pro for harder text reasoning and coding, or the experimental deepseek-v4-flash-vision-exp when the request must understand images. 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 deepseek-v4-flash, deepseek-v4-pro, and deepseek-v4-flash-vision-exp. The API is stateless, so send the required history in each request. Vision images use input_image parts. The August 3 Pro rejection shown above remains a dated pre-GA observation.

Does the DeepSeek API support images and files?

Vision Exp supports JPEG, PNG, GIF, and WebP images supplied by public URL, Base64 data URL, or an image file_id from the Files API. Flash and Pro are text-only. General document and arbitrary file input remains unsupported: do not confuse a supported image file_id with generic input_file, PDF, DOCX, spreadsheet, or archive support.

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 V4 Flash, V4 Pro, and Vision Exp. A request exceeding the context limit can return HTTP 400, so reserve space for the requested output, image tokens, 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.

If you are deciding what to build rather than debugging a request, browse DeepSeek use cases by task. For questions about Chat-Deep.ai access, accounts, or privacy—not the official API contract—see the Chat-Deep.ai API and access FAQ.

Official sources and update log

• DeepSeek API change log
• Models and pricing
• Vision guide
• Files API guide
• Using the Responses API
• 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.