DeepSeek API 配置指南：Key、Base URL 与 reasoner 使用要点

一、简介与适用场景

DeepSeek 的性价比在同档位模型里几乎没有对手，而且它有一个别家少见的机制——上下文硬盘缓存：重复出现的前缀（比如固定的 system 提示词、长文档）在命中缓存后，输入部分的价格会大幅下降。对于要反复处理同一份长文档的场景，这个机制能省下相当可观的成本。

必须先说清楚：DeepSeek 没有长期免费档。注册时会给一点体验额度，用完就必须充值。网上流传的「DeepSeek 免费 API」基本都是中转站在转卖，不是官方政策，请不要按免费方案来规划。

适合看这篇的情况：需要高性价比的中文对话与代码能力、有反复处理长文档的场景、或者想用 deepseek-reasoner 做需要显式推理的任务。

二、注册与获取 Key

1. 打开 DeepSeek 开放平台 用手机号注册。
2. 完成实名认证，然后在充值页面预存金额。
3. 进入 API keys 页面创建密钥，复制 sk- 开头的字符串。Key 只显示一次。
4. 建议在「用量」页面设置提醒，避免线上服务把余额跑空后突然全线报错。

三、Base URL 与鉴权

• Base URL：https://api.deepseek.com/v1
• 鉴权方式：Authorization: Bearer sk-xxxxxxxx
• 对话端点：/chat/completions

官方文档提到 https://api.deepseek.com 和 https://api.deepseek.com/v1 都能用，后者只是为了兼容那些会强制拼接路径的 OpenAI SDK，这里的 v1 与模型版本无关。为了避免客户端行为不一致，本站统一推荐填带 /v1 的完整形式。

模型只有两个：deepseek-chat（通用对话）和 deepseek-reasoner（推理模型）。别去填 deepseek-v3 这种在别处看到的名字，官方端点不认。

四、客户端接入示例

Cherry Studio 内置了 DeepSeek：

1. 打开「设置 → 模型服务 → DeepSeek」。
2. API 密钥填 sk- 字符串，API 地址保持默认。
3. 模型列表里会自动出现 deepseek-chat 和 deepseek-reasoner。
4. 使用 reasoner 时把客户端的超时时间调长一些，推理模型的首个 token 会明显更慢。

五、代码示例

curl：

curl https://api.deepseek.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "用一句话解释什么是 API"}]
  }'

Python（处理 reasoner 的思维链字段）：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com/v1",
)

resp = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=[{"role": "user", "content": "9.11 和 9.8 哪个大？"}],
)
message = resp.choices[0].message
print("思维链：", getattr(message, "reasoning_content", ""))
print("最终答案：", message.content)

Node.js：

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: 'https://api.deepseek.com/v1',
});

const resp = await client.chat.completions.create({
  model: 'deepseek-chat',
  messages: [{ role: 'user', content: '用一句话解释什么是 API' }],
});
console.log(resp.choices[0].message.content);

关键提醒：多轮对话时，绝对不要把 reasoning_content 回填进下一轮的 messages。官方明确规定这样做会直接报 400，只能回填 content。

六、常见错误排查