📋 接口总览
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 结构化输出、流式响应等全部功能。
| 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| 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 | 可选 | 自定义用户标识 |
| 字段名 | 类型 | 描述 |
|---|---|---|
| content | string | 模型回复内容 |
| reasoning_content | string | 思考模式的推理内容 |
| role | string | 始终为 "assistant" |
| tool_calls | array | 工具调用请求 |
| 字段名 | 类型 | 描述 |
|---|---|---|
| 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 数 |
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。仅支持非思考模式。
| 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| 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
列出所有可用的模型。
| 字段名 | 类型 | 描述 |
|---|---|---|
| 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
查询当前账户的余额信息,包括赠金和充值余额。
| 字段名 | 类型 | 描述 |
|---|---|---|
| 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