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 输出与函数发起调用实战。

常见报错排查

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

接入之后

常见问题

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

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