DeepSeek API 接入指南:从创建 Key 到第一次发起调用
DeepSeek API 采用与主流大模型服务兼容的请求格式,接口地址、模型名和鉴权路径保持一致,由此绝大多数客户端 SDK 只需替换 base_url 和模型名即可接入。
本页给出最小可运转示例、流式与结构化输出写法,和最典型的几类报错排查。
四步完成接入
- 注册 API 开放平台账号:进入 API 开放平台完成注册并登录控制台。
- 创建并留存 API Key:在控制台创建密钥。密钥多数时候只在创建时详尽显示一次,请立刻复制到安全位置;一旦怀疑泄露,立刻撤销并重建。
- 设定地址与模型名:把 base_url 指向官方文档给出的 API 地址(使用
/v1路径),模型名按事项选定deepseek-chat或deepseek-reasoning。 - 发起最小发起调用并验证:先用一次只有一句话的请求跑通链路,核对能正常返回 assistant 材料,再接入业务。
最小可运行示例
curl
把密钥放进环境变量,防止出现在命令历史里:
export DEEPSEEK_API_KEY="sk-你的密钥"
curl https://api.deepseek.com/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-d '{
"model": "deepseek-chat",
"messages": [
{"role": "system", "content": "你是一个严谨的技术助理。"},
{"role": "user", "content": "用三句话解释什么是 API。"}
],
"stream": false
}'返回体中的 choices[0].message.content 即为模型回应,usage 字段给出本次消耗的 token 数量。
Python
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-chat",
messages=[
{"role": "system", "content": "你是一个严谨的技术助理。"},
{"role": "user", "content": "用三句话解释什么是 API。"},
],
temperature=0.3,
max_tokens=1024,
)
print(response.choices[0].message.content)
print(response.usage)用官方兼容的 Python SDK 即可,不用专用依赖;把 base_url 换成 DeepSeek 地址是接入的关键一步。
JavaScript
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.DEEPSEEK_API_KEY,
baseURL: "https://api.deepseek.com",
});
const stream = await client.chat.completions.create({
model: "deepseek-reasoning",
messages: [{ role: "user", content: "解释一下什么是流式输出。" }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}流式输出与结构化输出
流式输出:把 stream 设为 true,服务端会以增量事件逐段返回,前端拼接即可得到打字机效果。对话场合不妨开启,批量事项可关闭以减少请求次数。
结构化输出:需要在程序里直接使用结果时,开启 JSON 对象的响应格式,并在系统提示中明确字段、类型与嵌套关系:
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{"role": "system", "content": "仅输出 JSON,字段为 city、population、tags(字符串数组)。"},
{"role": "user", "content": "杭州的人口规模和标签。"},
],
response_format={"type": "json_object"},
)
import json
data = json.loads(response.choices[0].message.content)
print(data["city"], data["tags"])输出后务必做一次结构校验,必要时重试或做后处理修补,防止模型偶发多出解释性文字导致解析失败。更多工程化写法见 JSON 输出与函数发起调用实战。
常见报错排查
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
| 返回材料为空或被截断 | max_tokens 过小、提示词过长 | 提高 max_tokens,压缩历史消息,必要时分多轮请求再合并 |
| 回应不符合预期格式 | 缺少格式约束或示例 | 补充字段阐述与示例 JSON,开启 JSON 响应模式并做校验 |
| 连接超时 | 网络链路不平稳、服务端繁忙 | 设定合理的超时与重试次数,批量事项降低并发 |
| 401 身份验证失败 | 未带 Authorization 头、Key 复制时带空格换行、Key 已撤销 | 核对使用 Bearer 密钥 格式,从环境变量读取并做去空格处理 |
| 429 频率或额度受限 | 请求过快、并发过高、余额不足 | 加入指数退避重试,校验控制台余额与速率限制设定 |
接入之后
- 想了解该发起调用哪个模型更合适,看 DeepSeek 模型家族对比。
- 想把 API 能力做成详尽后端流程,看 JSON 输出与函数发起调用实战。
- 正在比较各家 API 的接入成本,看 DeepSeek vs ChatGPT vs Claude。
DeepSeek API 接入问答
DeepSeek 的 API 地址是什么?
DeepSeek API 使用官方文档中给出的接入域名,多数客户端只需把 base_url 设定为官方 API 地址的 /v1 路径,并使用与 OpenAI 兼容的请求格式与响应格式。模型名可选 deepseek-chat 与 deepseek-reasoning,前者更契合通用事项,后者偏向推理事项。
DeepSeek API Key 在哪里创建?
API Key 在 API 开放平台的控制台中创建。密钥多数时候只在创建时详尽显示一次,请立刻留存到安全的位置;若是怀疑已经泄露,应在控制台撤销该密钥并重新创建一个。
调用 DeepSeek API 报 401 错误怎么解决?
401 表示身份验证未经由,典型原因是请求头中没有带 Authorization、Key 复制时多了空格或换行、要么用了已经撤销的旧 Key。核对 Authorization 的格式为 Bearer 加上你的密钥,并从环境变量读取而不是硬编码。
调用 DeepSeek API 报 429 错误怎么解决?
429 表示请求过于频繁或触及速率与额度限制。处理路径是给请求加上指数退避重试,校验控制台的余额与速率限制设定,并防止在循环里以极高并发重复发送同样的请求。
怎么让 DeepSeek 输出严格的 JSON?
在请求中开启响应格式为 JSON 对象的模式,并在系统提示中写清字段名称、类型与嵌套关系,并给出示例 JSON。输出前先校验是否符合预期结构,必要时重试一次或做后处理修补。
DeepSeek API 怎么实现流式输出?
在请求参数中把流式开关设为真,服务端就会以增量事件的形式逐段返回材料,客户端按事件拼接即可得到逐字输出效果。对话类前端用它实现打字机观感,批量事项则不必开启。