DeepSeek API 接入教程：Key、Base URL 与第一次调用（2026）

DeepSeek API 接入本身不复杂，真正容易卡住的是三件事：Key 属于哪个平台、Base URL 有没有写全、模型名是不是当前版本。很多“调不通”并不是模型能力问题，而是凭证和地址没有对齐。

本文从注册、充值、创建 Key 开始，按顺序完成第一次 curl 和 Python 调用，再把流式输出、thinking 模式、max_tokens 和常见报错讲清楚。照着做一遍，基本可以把接入链路跑通。

说明：DeepSeek 是其权利人的商标，本文与 DeepSeek 官方无隶属关系。模型名、参数与限额可能随版本调整，本文以 2026 年 10 月官方文档的常见形态为例，最终以官方文档和站内模型价格为准。

一、接入前先分清四件事

API 接入失败，多数不是模型能力问题，而是下面四个对象没有对齐：

对象	作用	最容易错的地方
账号	决定余额、账单和 Key 的归属	拿 A 平台的 Key 配 B 平台的地址
API Key	身份凭证	复制时带了空格、换行或引号
Base URL	请求发往哪个入口	少写 /v1，或把官方地址和网关地址混用
模型名	请求里的 model 字段	沿用旧文章里的过期名称

记忆方法很简单：Key 和 Base URL 必须成对出现。官方 Key 只配官方入口，网关 Key 只配网关入口，混用通常直接返回 401。

二、注册、充值、创建 Key

以官方开放平台为例，顺序如下：

1. 打开 DeepSeek 开放平台，注册并登录。
2. 按页面提示完成必要验证，进入充值页面。
3. 第一次先充小额，确认到账后再跑批量任务。
4. 进入 API Keys 页面，新建 Key，名称写清用途，例如 deepseek-test、deepseek-prod。
5. 复制 Key 后立即保存到密码管理器或服务端环境变量，页面关闭后通常不再完整显示。
6. 给测试和生产分别建 Key，并设置预算或用量提醒。

如果使用中商起航 AI 网关，流程类似：在注册页创建账号，进入控制台创建 Key、充值，再按本文后面的 OpenAI 兼容方式调用。两边不要共用同一把 Key，否则出问题时很难判断是余额、限流还是配置错误。

三、Base URL 与模型名：先确认再写代码

官方文档当前给出的 OpenAI 兼容入口是 https://api.deepseek.com，聊天补全路径为 /chat/completions。部分旧教程会写 https://api.deepseek.com/v1，是否可用要以官方文档当前说明为准；不确定时，先用官方示例里的地址跑通。

项目	官方直连	中商起航 AI 网关
Base URL	https://api.deepseek.com	https://ai.zhongshangqihang.com/v1
聊天路径	/chat/completions	/v1/chat/completions
Key 来源	官方开放平台	网关控制台
模型名	以官方文档为准	以站内模型价格为准
适合	只用 DeepSeek、官方访问与支付顺畅	需要统一入口、多模型或人民币账单

截至 2026 年 10 月，官方文档列出的模型名是 deepseek-flash 和 deepseek-v4-pro；旧文章里的 deepseek-chat、deepseek-reasoner 不一定仍然可用。不要凭记忆填模型名，调用前对照官方文档或站内价格页。

四、第一次 curl：先跑通最小请求

先关掉 thinking，减少变量。官方入口示例：

export DEEPSEEK_API_KEY="sk-你的密钥"

curl "https://api.deepseek.com/chat/completions" \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-flash",
    "messages": [{"role": "user", "content": "只回复 OK"}],
    "thinking": {"type": "disabled"},
    "max_tokens": 32
  }'

返回 200 且 choices[0].message.content 里有内容，说明 Key、Base URL、模型名三项都对。若改用网关，只替换 URL 为 https://ai.zhongshangqihang.com/v1/chat/completions，并换成网关 Key。

注意 thinking 是 DeepSeek 的扩展参数，不是所有 OpenAI 兼容服务都支持。网关不支持时去掉该字段，或按网关文档改用对应参数。

五、Python 第一次调用：用 OpenAI SDK

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",  # 网关改为 https://ai.zhongshangqihang.com/v1
)

resp = client.chat.completions.create(
    model="deepseek-flash",
    messages=[
        {"role": "system", "content": "你是中文技术助手，回答简洁。"},
        {"role": "user", "content": "用三句话解释什么是向量数据库。"},
    ],
    max_tokens=512,
    extra_body={"thinking": {"type": "disabled"}},
)

print(resp.choices[0].message.content)
print(resp.usage)

OpenAI SDK 不认识 thinking 字段，所以要通过 extra_body 传入。跑通后先看 usage：输入、输出各多少 Token，缓存命中是否返回，推理内容是否单独计数。这些数据比“感觉快不快”更能指导后面的成本和超时设置。

六、流式输出与 reasoning_content

thinking 默认开启，默认强度为 high。开启后，响应里会出现 reasoning_content，它和最终正文 content 同级；流式响应里则在 delta.reasoning_content 中逐块返回。

stream = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "写一个读取 CSV 的 Python 示例"}],
    stream=True,
    max_tokens=4096,
    reasoning_effort="high",
    extra_body={"thinking": {"type": "enabled"}},
)

reasoning, answer = [], []
for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    if getattr(delta, "reasoning_content", None):
        reasoning.append(delta.reasoning_content)
    if delta.content:
        answer.append(delta.content)

print("思考过程：", "".join(reasoning))
print("最终回答：", "".join(answer))

多轮对话时，如果请求里带 tools，上一轮的 reasoning_content 要完整回传，否则可能返回 400；不带 tools 时可以不带，服务端会忽略。面向终端用户时，思考内容建议折叠展示，不要默认全部展开。

七、max_tokens、temperature 与 thinking 怎么配

任务	thinking	建议起点	说明
连通性测试	关闭	max_tokens 32–128	只要一个短回复
分类、抽取	关闭	256–1024	输出结构化，减少思考开销
客服、写作	开启	1024–4096	可按效果调整 effort
代码、复杂推理	开启	4096 以上	给思考过程留足预算

官方文档当前标注：上下文长度为 1M Token，max_tokens 范围为 1 到 384K；不设置时，非 thinking 默认 8K，thinking 默认 64K，reasoning_effort 为 max 时默认 128K。这些数值可能调整，以官方文档为准。

thinking 模式下，temperature、presence_penalty、frequency_penalty 不生效，调它们不会报错，但也不会改变结果。max_tokens 也不能压得太低：思考内容会占用输出预算，预算太小可能还没写到正文就被截断。

八、401、402、429、超时怎么排查

现象	常见原因	处理
401	Key 错误、缺少 Bearer、Key 与 Base URL 不属于同一平台	重新复制 Key，检查请求头，确认入口匹配
402	账户余额不足	充值后重试，先查余额再改代码
429	请求过快、并发或 QPS 超限	降并发、指数退避、按项目拆 Key
400/422	参数、模型名或上下文不合法	看错误信息，核对模型名和 max_tokens
超时	网络、长输出、thinking 耗时	分开设置连接与读取超时，限制输出
500/503	上游服务错误或过载	短暂等待后退避重试

429 的并发上限按账号统计，不是每把 Key 平均分配。同一账号下多把 Key 共用额度，所以“多建几把 Key”并不能绕过并发限制。官方文档还说明，如果 10 分钟内没有开始推理，连接会被断开；客户端要能识别这种情况并重试。

九、Key 安全：上线前至少做五件事

1. Key 只放在服务端环境变量或密钥管理服务里，不写进前端、仓库和日志。
2. 测试、预发、生产各用一把 Key，出问题能快速定位和停用。
3. 设置余额提醒或消费上限，异常调用时先止损。
4. 日志里只记录 Key 前缀或指纹，不记录完整值。
5. 人员变动或怀疑泄露时立即轮换，并检查最近的用量记录。

十、从官方切到网关：只改两处

迁移时先改 base_url 和 api_key，模型名按网关价格页重新确认，其余请求体尽量保持不变。用同一批真实提示词对比输出、耗时和 usage，观察 3–7 天后再切生产。保留官方直连作为备用通道，出问题时能快速回滚。

需要统一入口或多模型账单，可以在中商起航 AI 网关创建测试 Key，价格与可用模型见模型价格。

相关阅读：

• DeepSeek API Key 获取教程
• DeepSeek API 常见报错与限流排查
• DeepSeek API 价格与计费

常见问题

Base URL 到底要不要加 /v1？

以官方文档当前示例为准。官方 OpenAI 兼容入口写作 https://api.deepseek.com，聊天路径是 /chat/completions；网关通常使用 /v1 前缀。不要凭旧教程猜，先用 curl 打一次完整地址。

401 是 Key 错还是余额不足？

401 是鉴权失败，优先查 Key 是否正确、是否带了 Bearer、Key 与 Base URL 是否属于同一平台。余额不足通常返回 402，两者不要混为一谈。

第一次调用要不要开 thinking？

建议先关闭，用最短请求确认链路通。确认 Key、地址、模型名都没问题后，再按任务需要开启，并从较低的 reasoning_effort 开始测试。

max_tokens 设多少合适？

先按任务给一个够用的值，跑通后再收紧。分类和抽取可以从几百开始，长文和代码留几千；thinking 模式要给思考内容留预算，设得太小容易截断正文。

官方 Key 能直接配网关地址吗？

不能。官方 Key 只对应官方入口，网关 Key 只对应网关入口，混用通常返回 401。切换入口时，Key 和 Base URL 要成对更换。