# DeepSeek API 完整接口文档

基于官方文档 api-docs.deepseek.com 全面解析。兼容 OpenAI / Anthropic SDK 格式，支持 deepseek-v4-flash 和 deepseek-v4-pro 模型。

支持模型: deepseek-v4-flash · deepseek-v4-pro 文档日期: 2026-05-18 Base URL: https://api.deepseek.com

## 📋 接口总览

DeepSeek API 提供 RESTful HTTP 接口，兼容 OpenAI 和 Anthropic SDK 格式。所有请求与响应均使用 JSON 格式。流式响应使用 SSE（Server-Sent Events）。

方法 | 接口路径 | 描述
--- | --- | ---
POST | /chat/completions | 对话补全（主接口）
POST | /completions | FIM 补全（Beta）
GET | /models | 列出可用模型
GET | /user/balance | 查询账户余额

## ⚡ 快速开始

获取 API Key 后即可开始调用。支持 OpenAI SDK 兼容格式，也可直接使用 HTTP 请求。

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

    from openai import OpenAI

    client = OpenAI(
        api_key="<your api key>",
        base_url="https://api.deepseek.com"
    )

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

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

## 💰 模型 & 价格

DeepSeek 提供两个模型版本，均支持 1M 上下文长度和最大 384K 输出长度。

项目 | deepseek-v4-flash | deepseek-v4-pro
--- | --- | ---
模型版本 | DeepSeek-V4-Flash | DeepSeek-V4-Pro
上下文长度 | 1M | 1M
输出长度 | 最大 384K | 最大 384K
思考模式 | 支持非思考与思考模式（默认） | 支持
JSON Output | 支持 | 支持
Tool Calls | 支持 | 支持
FIM 补全（Beta） | 仅非思考模式 | 仅非思考模式
输入（缓存命中） | 0.02 元/百万tokens | 0.1 元/百万tokens
输入（缓存未命中） | 1 元/百万tokens | 3 元/百万tokens（2.5折）
输出 | 2 元/百万tokens | 6 元/百万tokens（2.5折）

⚠️ 注意：`deepseek-chat` 和 `deepseek-reasoner` 将于 2026/07/24 下线，分别映射到 deepseek-v4-flash 的非思考模式和思考模式。

## POST /chat/completions

DeepSeek 核心对话接口。支持多轮对话、思考模式、工具调用、JSON 结构化输出、流式响应等全部功能。

POST https://api.deepseek.com/chat/completions
📥 请求参数

参数名 | 类型 | 必填 | 描述
--- | --- | --- | ---
model | string | 必填 | 模型 ID: "deepseek-v4-flash" 或 "deepseek-v4-pro"
messages | array | 必填 | 对话消息列表
messages[].role | string | 必填 | 角色: "system" / "user" / "assistant" / "tool"
messages[].content | string | 必填 | 消息内容
thinking | object | 可选 | 思考模式控制
thinking.type | string | 可选 | "enabled" 或 "disabled"（默认 enabled）
reasoning_effort | string | 可选 | 推理强度: "high"（默认）或 "max"
max_tokens | integer | 可选 | 最大生成 token 数
response_format | object | 可选 | 响应格式，支持 {"type": "json_object"}
stop | string / string[] | 可选 | 停止序列（最多16个）
stream | boolean | 可选 | 是否 SSE 流式输出
stream_options | object | 可选 | 流式选项
temperature | number | 可选 | 采样温度 0-2（默认 1）
top_p | number | 可选 | 核采样概率（默认 1）
tools | array | 可选 | 工具列表（最多128个）
tool_choice | string/object | 可选 | "none" / "auto" / "required" / 指定函数
logprobs | boolean | 可选 | 返回 token 对数概率
top_logprobs | integer | 可选 | 每位置返回 top N token（0-20）
user_id | string | 可选 | 自定义用户标识

📤 响应字段 (choices[].message)

字段名 | 类型 | 描述
--- | --- | ---
content | string | 模型回复内容
reasoning_content | string | 思考模式的推理内容
role | string | 始终为 "assistant"
tool_calls | array | 工具调用请求

📤 响应字段 (usage)

字段名 | 类型 | 描述
--- | --- | ---
prompt_tokens | integer | 输入 token 数
prompt_cache_hit_tokens | integer | 缓存命中 token 数
prompt_cache_miss_tokens | integer | 缓存未命中 token 数
completion_tokens | integer | 输出 token 数
total_tokens | integer | 总 token 数
completion_tokens_details.reasoning_tokens | integer | 推理 token 数

💡 提示：思考模式下（thinking.type="enabled"），`reasoning_content` 字段包含模型的推理过程，`content` 为最终回答。多轮对话中，非工具调用轮次的 reasoning_content 不需要携带回上下文，工具调用轮次的 reasoning_content 必须携带。
💻 代码示例

    from openai import OpenAI

    client = OpenAI(api_key="<your api key>", base_url="https://api.deepseek.com")

    response = client.chat.completions.create(
        model="deepseek-v4-pro",
        messages=[
            {"role": "system", "content": "你是一个专业的编程助手，请用中文回答。"},
            {"role": "user", "content": "解释 JavaScript 的事件循环机制"}
        ],
        stream=False
    )

    print(response.choices[0].message.content)
    print(f"输入: {response.usage.prompt_tokens} tokens, 输出: {response.usage.completion_tokens} tokens")

    const response = await fetch('https://api.deepseek.com/chat/completions', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${API_KEY}`
      },
      body: JSON.stringify({
        model: 'deepseek-v4-pro',
        messages: [
          { role: 'system', content: '你是一个专业的编程助手。' },
          { role: 'user', content: '解释 JavaScript 的事件循环机制' }
        ],
        stream: true
      })
    });

    const reader = response.body.getReader();
    const decoder = new TextDecoder();
    let buffer = '';

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      buffer += decoder.decode(value, { stream: true });
      const lines = buffer.split('\n');
      buffer = lines.pop();
      for (const line of lines) {
        if (!line.startsWith('data: ') || line === 'data: [DONE]') continue;
        const chunk = JSON.parse(line.slice(6));
        const content = chunk.choices[0]?.delta?.content;
        if (content) process.stdout.write(content);
      }
    }

    from openai import OpenAI

    client = OpenAI(api_key="<your api key>", base_url="https://api.deepseek.com")

    response = client.chat.completions.create(
        model="deepseek-v4-pro",
        messages=[{"role": "user", "content": "9.11 和 9.8 哪个更大？"}],
        reasoning_effort="high",
        extra_body={"thinking": {"type": "enabled"}}
    )

    msg = response.choices[0].message
    print(f"[思考过程]\n{msg.reasoning_content}")
    print(f"\n[最终回答]\n{msg.content}")

    const response = await fetch('https://api.deepseek.com/chat/completions', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${API_KEY}`
      },
      body: JSON.stringify({
        model: 'deepseek-v4-pro',
        messages: [{ role: 'user', content: '杭州今天天气怎么样？' }],
        stream: false,
        tools: [{
          type: 'function',
          function: {
            name: 'get_weather',
            description: '获取指定城市的当前天气信息',
            parameters: {
              type: 'object',
              properties: {
                location: { type: 'string', description: '城市名称' }
              },
              required: ['location']
            }
          }
        }]
      })
    });

    const data = await response.json();
    console.log('工具调用:', data.choices[0].message.tool_calls);

    from openai import OpenAI
    import json

    client = OpenAI(api_key="<your api key>", base_url="https://api.deepseek.com")

    response = client.chat.completions.create(
        model="deepseek-v4-pro",
        messages=[
            {"role": "system", "content": "请以 JSON 格式输出，包含 question 和 answer 字段。"},
            {"role": "user", "content": "世界上最高的山是什么？珠穆朗玛峰。"}
        ],
        response_format={"type": "json_object"}
    )

    data = json.loads(response.choices[0].message.content)
    print(json.dumps(data, ensure_ascii=False, indent=2))

    from openai import OpenAI

    client = OpenAI(api_key="<your api key>", base_url="https://api.deepseek.com")

    messages = [
        {"role": "system", "content": "你是一个专业的编程助手，请用中文回答。"},
        {"role": "user", "content": "JavaScript 中 Promise 和 async/await 的区别是什么？"}
    ]

    response = client.chat.completions.create(
        model="deepseek-v4-pro",
        messages=messages,
        stream=True
    )

    full_reply = ""
    for chunk in response:
        content = chunk.choices[0].delta.content
        if content:
            full_reply += content
            print(content, end="", flush=True)

    # Continue conversation
    messages.append({"role": "assistant", "content": full_reply})
    messages.append({"role": "user", "content": "能给一个 async/await 的代码示例吗？"})

📤 响应示例

    {
      "id": "chatcmpl-abc123",
      "object": "chat.completion",
      "created": 1716000000,
      "model": "deepseek-v4-pro",
      "choices": [{
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "JavaScript 的事件循环（Event Loop）是...",
          "reasoning_content": null,
          "tool_calls": null
        },
        "finish_reason": "stop"
      }],
      "usage": {
        "prompt_tokens": 24,
        "prompt_cache_hit_tokens": 12,
        "prompt_cache_miss_tokens": 12,
        "completion_tokens": 156,
        "total_tokens": 180,
        "completion_tokens_details": {
          "reasoning_tokens": 0
        }
      },
      "system_fingerprint": "fp_abc123"
    }

## POST /completions (FIM Beta)

FIM (Fill-In-the-Middle) 补全，用于代码补全、内容续写等场景。最大补全长度 4K。仅支持非思考模式。

POST https://api.deepseek.com/beta/completions
📥 请求参数

参数名 | 类型 | 必填 | 描述
--- | --- | --- | ---
model | string | 必填 | "deepseek-v4-pro"
prompt | string | 必填 | 前缀提示
suffix | string | 可选 | 后缀
max_tokens | integer | 可选 | 最大生成 token 数
stop | string/string[] | 可选 | 停止序列
stream | boolean | 可选 | 流式输出
temperature | number | 可选 | 采样温度
top_p | number | 可选 | 核采样概率

💻 代码示例

    from openai import OpenAI

    client = OpenAI(api_key="<your api key>", base_url="https://api.deepseek.com/beta")

    response = client.completions.create(
        model="deepseek-v4-pro",
        prompt="def fib(a):",
        suffix="    return fib(a-1) + fib(a-2)",
        max_tokens=128
    )
    print(response.choices[0].text)

## GET /models

列出所有可用的模型。

GET https://api.deepseek.com/models
📤 响应字段

字段名 | 类型 | 描述
--- | --- | ---
data[].id | string | 模型标识符
data[].object | string | 始终为 "model"
data[].owned_by | string | 模型所属组织

💻 代码示例

    from openai import OpenAI

    client = OpenAI(api_key="<your api key>", base_url="https://api.deepseek.com")
    models = client.models.list()
    for model in models.data:
        print(f"{model.id} - {model.owned_by}")

## GET /user/balance

查询当前账户的余额信息，包括赠金和充值余额。

GET https://api.deepseek.com/user/balance
📤 响应字段

字段名 | 类型 | 描述
--- | --- | ---
currency | string | 货币: "CNY" 或 "USD"
total_balance | string | 总可用余额
granted_balance | string | 赠金余额
topped_up_balance | string | 充值余额

💻 代码示例

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

## 🧠 思考模式

DeepSeek 模型支持思考模式（Thinking Mode），让模型在回答前进行深度推理。适用于数学、逻辑、编程等需要复杂推理的场景。

核心参数

参数名 | 类型 | 描述
--- | --- | ---
thinking.type | string | "enabled"（默认）或 "disabled"
reasoning_effort | string | "high"（默认）或 "max"。Agent 工具（如 Claude Code）会自动设为 "max"

💡 映射规则：`low` / `medium` 映射到 `high`，`xhigh` 映射到 `max`。思考模式下，`temperature`、`top_p`、`presence_penalty`、`frequency_penalty` 参数将被忽略。
💡 多轮对话注意事项：非工具调用轮次的 `reasoning_content` 不需要携带回上下文；工具调用轮次的 `reasoning_content` 必须携带回上下文。

## 🔧 工具调用

DeepSeek 支持 Function Calling（工具调用），允许模型调用外部函数来获取信息或执行操作。

核心要点

特性 | 描述
--- | ---
工具数量 | 最多 128 个工具
tool_choice | "none" / "auto" / "required" / 指定函数名
strict 模式 (Beta) | 使用 `base_url="https://api.deepseek.com/beta"`，设置 `strict: true`
思考模式兼容 | DeepSeek-V3.2 起支持思考模式下的工具调用

## 📄 JSON 输出

DeepSeek 支持结构化 JSON 输出，确保模型返回合法的 JSON 格式数据。

使用方法

步骤 | 描述
--- | ---
1. 设置格式 | 请求参数中设置 `response_format: {"type": "json_object"}`
2. 指示模型 | 必须在 system 或 user 消息中明确指示模型生成 JSON 格式输出

## 🔗 Anthropic 兼容

DeepSeek 提供 Anthropic Messages API 兼容接口，可直接使用 Anthropic SDK 调用。

接入方式

配置项 | 描述
--- | ---
Base URL | `https://api.deepseek.com/anthropic`
SDK | 直接使用 Anthropic SDK，无需修改代码
支持内容类型 | text content、tool_use、thinking（array type="thinking"）

📄 本文档基于 api-docs.deepseek.com 官方文档生成

支持模型: deepseek-v4-flash · deepseek-v4-pro · 文档日期: 2026-05-18

平台: platform.deepseek.com · SDK: OpenAI SDK · Anthropic SDK