DeepSeek API 使用指南：从申请 Key 到跑通调用

一切从一条报错开始，这个夏天我亲眼见了两次。同事照某篇教程敲了 pip install deepseek-api，pip 回了他一屏红字。另一回是装上了、示例一跑，服务器回 Model Not Exist——因为教程里写的 deepseek-chat，2026 年 7 月 24 日就跟 deepseek-reasoner 一起退役了。这两种失败都不怪键盘前的人：教程过期了，DeepSeek API 已经往前走了。

本文全部对齐 2026 年 8 月的现行口径：真正能解析的模型名、真实存在的取 Key 流程、GA 版上线的参数。一篇讲完从零到生产级调用链——Key、第一次调用、流式、思考模式、多轮对话、结构化输出、限流。顺带一张纠错表，把流传甚广的教程还在教错的东西逐条对清。

DeepSeek API 是什么

DeepSeek API 是一个说两种行业标准方言的 chat 接口：OpenAI 格式和 Anthropic 格式。双兼容就是它的全部设计哲学——你不需要装新 SDK、学新报文格式、重写任何东西，把现有 OpenAI 客户端指到另一个 base URL、换一个模型字符串就完事。会调 GPT 就会调 DeepSeek。

三个官方域名各司其职，分清它们比想象中重要——这个话题的搜索结果里至少混着八个仿冒站（deep-seek.com、deepseekv4pro.com 之流），既不是文档也不是控制台：

域名	用途
platform.deepseek.com	控制台：建 Key、查余额、看用量
api-docs.deepseek.com	文档与指南
api.deepseek.com	你的代码真正请求的端点

现行模型名，以及它们背后实际指向的 checkpoint：

模型字符串	实际 checkpoint	定位
`deepseek-v4-flash`	V4-Flash-0731	快且便宜，日常主力
`deepseek-v4-pro`	V4-Pro-0813	深度推理旗舰
`deepseek-v4-flash-vision-exp`	实验版	文本+图像输入

这个映射是刻意设计的：调用名保持稳定，DeepSeek 在背后把它指到最新 checkpoint。但有两个名字不再解析：deepseek-chat 和 deepseek-reasoner，2026 年 7 月 24 日全部退役。任何还在敲这两个名字的教程，描述的都是一个已经不存在的产品。（模型规格、跑分和完整价格见站内 DeepSeek V4 全解。）

申请 DeepSeek API Key

认证就是一个普通的 HTTP Bearer token——一个字符串、一个请求头。获取方式：登录 platform.deepseek.com，进 API Keys 页，点创建，立刻复制。Key 只显示一次。流程到此为止，没有更多仪式。

有两件事值得说透，因为中文圈在这两件事上噪音很大。

第一：没有 OAuth 流程、没有企业认证表单、没有权限范围勾选。有些流传很广的教程描述了一套"OAuth 2.0 双阶段认证+实名验证"——那套流程不存在。哪篇指南让你配 OAuth 凭证，你读到的就是小说。

第二：把 Key 当密码保管，因为它就是能花钱的密码。生产环境的标准纪律：

# .env —— 永不硬编码、永不提交
DEEPSEEK_API_KEY=sk-your-key-here

import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv("DEEPSEEK_API_KEY")
if not api_key:
    raise RuntimeError("Missing DEEPSEEK_API_KEY")

Key 只留在服务端。发到浏览器或打包进 App 的 Key 就不再是秘密了——那是捐款。

第一次调用 DeepSeek API

官方首个调用示例是裸 HTTP 写的，值得慢慢读一遍，因为每个字段之后都会以 SDK 的形态再出现——这段 curl 我到现在接到任何新账号都先跑一遍：一枪验证 key、网络、模型名三样全通，之后出了问题才好排查：

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
        "model": "deepseek-v4-pro",
        "messages": [
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "Hello!"}
        ],
        "thinking": {"type": "enabled"},
        "reasoning_effort": "high",
        "stream": false
      }'

端点是 api.deepseek.com 上的 POST /chat/completions。messages 按角色堆叠——先 system 人设，再用户轮次。thinking 打开思维链开关，reasoning_effort 设定思考强度，stream: false 表示等整个 JSON 响应一次性回来。

Python 版

"OpenAI 兼容"在实际开发里买到的东西是这个——装标准 OpenAI SDK，不是任何第三方"deepseek"包（其中几个是非官方的，有一个著名的是纯编造的）：

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-v4-flash",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "用两句话解释 HTTP cookie。"},
    ],
)
print(response.choices[0].message.content)

迁移只改两行：base_url 和模型字符串。其余一切——重试、类型、流式助手——都是你现有 OpenAI 代码换个工牌继续上班。用 Anthropic SDK 的代码库同理，指到 https://api.deepseek.com/anthropic。

流式输出

设 stream=True，响应以服务器推送事件（SSE）到达：一串 JSON 块，每块带着装有几个新 token 的 delta。头几个词在模型想完全部内容之前就冒出来——这就是聊天"感觉活着"和"感觉在下文件"的区别。

stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "写一首关于延迟的俳句。"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

流式与否，响应里的 usage 字段都会报 prompt_tokens 和 completion_tokens——你的账单就是从这两个数字算出来的。现在就养成记日志的习惯，下文 token 一节讲它们意味着什么。

流式有两个第一周就回本的习惯——我自己都是付过学费才养成的。给每个请求设显式超时——一条卡死的连接占着槽位不放，跟一个特别慢的模型没有区别，重连好过干等。流中途断掉时，重发整个请求：半截输出只是展示材料，服务端不记得它，没有断点续传 token 可发。低客单价的请求让这两个习惯都无痛——这也是"先在 flash 档上把业务跑起来、实测出差距再升 pro"的一个静默论据。

思考模式与 Effort：真正要紧的两个旋钮

跟老 API 的一个重大区别：思考模式默认开启，默认档位 high。回答之前，模型先走一遍思维链再作答——难题准确率上去，延迟跟着上去。

effort 参数是三个真实档位的油门。low 是市区代步——快速回答、最少盘算。high 是高速巡航，默认甜点位。max 是赛道模式：给证明题、架构决策、疑难调试用满额推理预算。还有个值得知道的怪癖——请求 medium 或 xhigh，平台都会映射成 high。映射表直接来自思考模式指南：

你请求的	模型实际跑的
low	low
medium	high
high	high
xhigh	high
max	max

简单调用想关掉思考，传开关即可——注意 Python 细节：OpenAI SDK 不认识这个字段，所以要塞进 extra_body：

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "9.11 和 9.8 哪个大？"}],
    reasoning_effort="high",
    extra_body={"thinking": {"type": "enabled"}},
)

两个多数教程跳过的深水细节。

其一，思考模式之内，采样参数——temperature、top_p、presence_penalty、frequency_penalty——全部无效。API 会静默收下（为了兼容既有软件）然后忽略。我曾为此安静地耗掉一个下午——调 temperature 死活没变化，最后在文档里翻到那行字。你遇到一样的情况：就是这个原因，不是你代码的 bug。

其二，思维链从 reasoning_content 字段返回，跟 content 并排。后续轮次里，历史 reasoning_content 在请求不带 tools 参数时会被服务端忽略——所以放心把旧推理从存储的上下文里剥掉，一点不亏。

多轮对话：没有记忆的服务员

chat 端点没有记忆，一点都没有。每个请求都是一位全新顾客：服务端只读你发来的 messages 数组，作答，然后把这一桌忘得干干净净。所谓多轮对话，是你——客户端——自己留着对话记录，每轮把整桌内容重新念给服务员听。

messages = [{"role": "user", "content": "世界上最高的山是什么？"}]

response = client.chat.completions.create(
    model="deepseek-v4-flash", messages=messages
)
messages.append(response.choices[0].message)   # 服务员的回答

messages.append({"role": "user", "content": "第二高呢？"})
response = client.chat.completions.create(
    model="deepseek-v4-flash", messages=messages
)
print(response.choices[0].message.content)

第二轮发出去三条：原始问题、存下来的回答、新问题。这个模式——追加回答、追加新轮次、全量重发——就是对话记忆的全部秘密，也是长 agent 会话每轮成本线性上涨的原因。（让这些越长越长的对话记录保持高效的提示词策略，见提示词技巧。）

结构化 JSON 输出

当输出要喂给解析器而不是人眼时，自由散文就是 bug。JSON 模式锁死输出形状，靠三条规则：设响应格式、在提示词里写 "json" 这个词并给示例、设 max_tokens 上限防止长答案把对象截断在半路。

system_prompt = """
The user will provide some exam text. Please parse the "question"
and "answer" and output them in JSON format.
EXAMPLE INPUT:
Which is the highest mountain in the world? Mount Everest.
EXAMPLE JSON OUTPUT:
{"question": "...", "answer": "..."}
"""

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": "世界上最长的河是什么？尼罗河。"},
    ],
    response_format={"type": "json_object"},
    max_tokens=512,
)
print(response.choices[0].message.content)

提示词里漏了示例，质量会掉；漏了 max_tokens，一个话痨回答可能停在半个花括号上——那是只在生产环境才炸给你看的 json.loads 崩溃。

限流与 user_id 救生索

并发按账号计数，跟用哪把 Key 发的请求无关。想象一家餐厅：你的账号有固定桌数，每个在途请求从发出到收完最后一个字节都占一张桌。

模型	每账号并发上限
deepseek-v4-pro	500
deepseek-v4-flash	2,500
deepseek-v4-flash-vision-exp	2,500

越过线就是 HTTP 429——退避重试，别硬怼。要更多桌子？扩容申请免费，平台按真实业务量匹配额度。现行数字以限流页为准。

如果你在一个账号下服务很多终端用户，user_id 把大堂隔成包间。按请求传它——字母数字连字符下划线、最长 512 字符、别塞隐私信息——平台按身份隔离三件事：内容安全处理、KV 缓存（一个用户缓存过的上下文绝不渗进另一个人的）、调度。OpenAI SDK 里它也走 extra_body：

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "你好！"}],
    extra_body={"user_id": "customer-8801"},
)

对提额账号，每个 user_id 还有各自的并发上限——一个失控租户饿不死其他人。

Token 与账单

计费按 token，心算很友好：1 个英文字符约 0.3 token，1 个汉字约 0.6。一篇 1000 词的英文文章，模型还没作答就先吃掉约 1300 输入 token。精确数字永远以响应 usage 字段回传的为准——要对账就看它，别信任何估算器；官方文档另附 tokenizer demo 供离线计算。图像输入按尺寸走一套公式、每图有上限。

每个 token 多少钱、峰时谷时怎么算——那是定价问题，有自己的答案页，V4 全解带着现行价表和生效日期。

Chat API 之外

/chat/completions 是正门，不是整栋房子。文档里围绕它还有：

GET /models——列出你的 Key 能摸到哪些模型，含 owner 与可用性
GET /user/balance——钱包查询，给仪表盘和消费告警用
Files API——上传一次、按 ID 引用（免费）
Context Caching——自动前缀缓存，命中价是未命中的三十分之一
FIM completion——填空中段，给代码编辑流用
Responses API——更新的响应格式，8 月 13 日起 GA
Anthropic 格式接口——同一批模型，…/anthropic 路径

还有一扇完全不用写代码的门：编程 Agent。Claude Code、GitHub Copilot、OpenCode 都能纯配置把 DeepSeek 设为后端模型。Claude Code 接入教程把环境变量配方从头到尾走了一遍——如果你的目标是"DeepSeek 进我的终端"，那就是绕过上面一切的捷径。

2026 年的常见坑

上面讲的一切对撞还在流传的一切，一张表收口：

旧教程说	2026 年现实
`pip install deepseek-api`、`from deepseek_api import DeepSeekClient`	不存在这个官方包。`pip install openai`，`base_url` 指 `https://api.deepseek.com`
`model="deepseek-chat"` / `"deepseek-reasoner"`	2026 年 7 月 24 日退役。用 `deepseek-v4-flash` 或 `deepseek-v4-pro`
OAuth 2.0、实名验证、企业认证才可用	platform.deepseek.com 拿 Bearer Key，仅此而已
JWT 签名、HMAC 请求签名	都不存在。`Authorization: Bearer` 请求头
思考模式里调 temperature	思考开启时静默无效
把 deep-seek.com / deepseekv4pro.com 当官网	官方三件套：platform.deepseek.com、api-docs.deepseek.com、api.deepseek.com

比所有条目更老的元规则：先看教程的发布日期，再看它的代码块。这个 API 七月退役了模型名、八月调了价——在那之前写的任何东西都是考古材料。

常见问题

DeepSeek API 怎么接入？三步：在 platform.deepseek.com 的 API Keys 页建 Key；装 OpenAI SDK（pip install openai）；用 base_url="https://api.deepseek.com" 加你的 Key 构造客户端。第一个调用就是标准的 chat completion，model="deepseek-v4-flash"。

DeepSeek API 用什么 SDK？没有专用 SDK。它同时兼容 OpenAI 和 Anthropic 两家 SDK——复用其中任何一个，只改 base URL（https://api.deepseek.com 或 https://api.deepseek.com/anthropic）和模型名。

DeepSeek API 的 base URL 是什么？OpenAI 格式用 https://api.deepseek.com；Anthropic 格式用 https://api.deepseek.com/anthropic。对话请求发 POST /chat/completions。

deepseek-chat 还能用吗？不能。deepseek-chat 和 deepseek-reasoner 已于 2026 年 7 月 24 日退役。替代品是 deepseek-v4-flash 和 deepseek-v4-pro，自动指向最新 checkpoint（V4-Flash-0731 和 V4-Pro-0813）。

API 免费吗？怎么查余额？按量付费，自动上下文缓存能摊薄重复输入的成本。实时余额一个调用就有——GET /user/balance——每个响应的 usage 字段给出逐次调用的 token 数供对账。

限流多少？429 什么意思？deepseek-v4-pro 并发 500，deepseek-v4-flash 和视觉模型并发 2500，按账号计。429 表示越过上限：退避重试。更高上限可通过免费扩容申请拿到。

能用 Anthropic 格式的代码调吗？能——Anthropic SDK 配 base_url="https://api.deepseek.com/anthropic"，模型名不变。工具定义和消息结构都直接沿用。

从这里出发三步走：拿一把 Key，原样跑通 curl 片段直到看到回复，然后决定这个模型在你技术栈里的位置——今晚先写个脚本，还是让编程 Agent 干重活（Claude Code 接入教程）。兼容接口真正的承诺不是哪个模型的跑分，而是：集成代码永远是你的，模型变成一行就能换的决定。

Edward Wang