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/completionsFIM 补全(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-flashdeepseek-v4-pro
模型版本DeepSeek-V4-FlashDeepSeek-V4-Pro
上下文长度1M1M
输出长度最大 384K最大 384K
思考模式支持非思考与思考模式(默认)支持
JSON Output支持支持
Tool Calls支持支持
FIM 补全(Beta)仅非思考模式仅非思考模式
输入(缓存命中)0.02 元/百万tokens0.1 元/百万tokens
输入(缓存未命中)1 元/百万tokens3 元/百万tokens(2.5折)
输出2 元/百万tokens6 元/百万tokens(2.5折)
⚠️ 注意:deepseek-chatdeepseek-reasoner 将于 2026/07/24 下线,分别映射到 deepseek-v4-flash 的非思考模式和思考模式。

POST /chat/completions

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

POST https://api.deepseek.com/chat/completions
📥 请求参数
参数名类型必填描述
modelstring必填模型 ID: "deepseek-v4-flash" 或 "deepseek-v4-pro"
messagesarray必填对话消息列表
messages[].rolestring必填角色: "system" / "user" / "assistant" / "tool"
messages[].contentstring必填消息内容
thinkingobject可选思考模式控制
thinking.typestring可选"enabled" 或 "disabled"(默认 enabled)
reasoning_effortstring可选推理强度: "high"(默认)或 "max"
max_tokensinteger可选最大生成 token 数
response_formatobject可选响应格式,支持 {"type": "json_object"}
stopstring / string[]可选停止序列(最多16个)
streamboolean可选是否 SSE 流式输出
stream_optionsobject可选流式选项
temperaturenumber可选采样温度 0-2(默认 1)
top_pnumber可选核采样概率(默认 1)
toolsarray可选工具列表(最多128个)
tool_choicestring/object可选"none" / "auto" / "required" / 指定函数
logprobsboolean可选返回 token 对数概率
top_logprobsinteger可选每位置返回 top N token(0-20)
user_idstring可选自定义用户标识
📤 响应字段 (choices[].message)
字段名类型描述
contentstring模型回复内容
reasoning_contentstring思考模式的推理内容
rolestring始终为 "assistant"
tool_callsarray工具调用请求
📤 响应字段 (usage)
字段名类型描述
prompt_tokensinteger输入 token 数
prompt_cache_hit_tokensinteger缓存命中 token 数
prompt_cache_miss_tokensinteger缓存未命中 token 数
completion_tokensinteger输出 token 数
total_tokensinteger总 token 数
completion_tokens_details.reasoning_tokensinteger推理 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
📥 请求参数
参数名类型必填描述
modelstring必填"deepseek-v4-pro"
promptstring必填前缀提示
suffixstring可选后缀
max_tokensinteger可选最大生成 token 数
stopstring/string[]可选停止序列
streamboolean可选流式输出
temperaturenumber可选采样温度
top_pnumber可选核采样概率
💻 代码示例
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[].idstring模型标识符
data[].objectstring始终为 "model"
data[].owned_bystring模型所属组织
💻 代码示例
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
📤 响应字段
字段名类型描述
currencystring货币: "CNY" 或 "USD"
total_balancestring总可用余额
granted_balancestring赠金余额
topped_up_balancestring充值余额
💻 代码示例
curl https://api.deepseek.com/user/balance \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}"

🧠 思考模式

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

核心参数
参数名类型描述
thinking.typestring"enabled"(默认)或 "disabled"
reasoning_effortstring"high"(默认)或 "max"。Agent 工具(如 Claude Code)会自动设为 "max"
💡 映射规则:low / medium 映射到 highxhigh 映射到 max。思考模式下,temperaturetop_ppresence_penaltyfrequency_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 URLhttps://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