DeepSeek API 接入指南:从创建 Key 到第一次调用

DeepSeek API 采用与主流大模型服务兼容的请求格式,接口地址、模型名和鉴权方式保持一致,因此绝大多数客户端 SDK 只需替换 base_url 和模型名即可接入。本页给出最小可运行示例、流式与结构化输出写法,以及最常见的几类报错排查。

四步完成接入

  1. 注册 API 开放平台账号:进入 API 开放平台完成注册并登录控制台。
  2. 创建并保存 API Key:在控制台创建密钥。密钥通常只在创建时完整显示一次,请立刻复制到安全位置;一旦怀疑泄露,立刻撤销并重建。
  3. 配置地址与模型名:把 base_url 指向官方文档给出的 API 地址(使用 /v1 路径),模型名按任务选择 deepseek-chat 或 deepseek-reasoning。
  4. 发起最小调用并验证:先用一次只有一句话的请求跑通链路,确认能正常返回 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 输出与函数调用实战。

常见报错排查

现象 常见原因 处理方式
401 身份验证失败 未带 Authorization 头、Key 复制时带空格换行、Key 已撤销 确认使用 Bearer 密钥 格式,从环境变量读取并做去空格处理
429 频率或额度受限 请求过快、并发过高、余额不足 加入指数退避重试,检查控制台余额与速率限制设置
返回内容为空或被截断 max_tokens 过小、提示词过长 提高 max_tokens,压缩历史消息,必要时分多轮请求再合并
回答不符合预期格式 缺少格式约束或示例 补充字段说明与示例 JSON,开启 JSON 响应模式并做校验
连接超时 网络链路不稳定、服务端繁忙 设置合理的超时与重试次数,批量任务降低并发

接入之后

常见问题

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 怎么实现流式输出?

在请求参数中把流式开关设为真,服务端就会以增量事件的形式逐段返回内容,客户端按事件拼接即可得到逐字输出效果。对话类前端用它实现打字机观感,批量任务则不必开启。