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

常见报错排查

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

接入之后

常见问题

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

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