深寻API文档（V4）实践者指南

如果你刚刚获得了DeepSeek API密钥并被告知要在周五发货，通常的第一个问题通常是：我在DeepSeek API文档中的起点在哪里，自V3以来有哪些变化？截至2026年4月24日的诚实答案是：变化很多。V4将模型系列重塑为两个层级，将思考模式变成了请求参数，并保留了您已知的与OpenAI兼容的线缆格式。本指南将带您了解第一天需要参考的内容——端点、参数、两个层级的定价计算以及旧ID的迁移窗口——并提供您可以粘贴到shell中的有效代码。

DeepSeek API实际上是什么

DeepSeek API是一个与OpenAI兼容的HTTP服务，通过单个聊天补全端点公开DeepSeek的开源混合专家模型。聊天请求击中 POST 参数，位于兼容OpenAI的端点 https://api.deepseek.com，认证是一个标准的携带令牌。如果你的代码库已经与OpenAI通信，你只需更改两行—— 基础URL 以及 API密钥 ——你就可以与DeepSeek通信了。DeepSeek还针对具有现有Claude形状代码的团队，在相同的基URL上提供与Anthropic兼容的表面。

两个让新用户第一天就感到困惑的点：

• 该API是无状态的。 DeepSeek 参数 API是一个“无状态”API，这意味着服务器不会记录用户请求的上下文，因此用户必须将所有之前的对话历史连接起来，并在每次请求中将它传递给聊天API。这与chat.deepseek.com上的网络聊天行为相反——网络/应用程序表面会为你保留会话历史；API不会。
• V4是一个系列，而不是一个单一模型。 您可以通过选择 模型 字段，并且你可以通过一个单独的参数选择推理努力。不再有专门的“推理器”模型ID。

当前模型ID（截至2026年4月24日）

V4今天作为预览版发布，并提供两种尺寸。DeepSeek-V4-Pro拥有1.6T参数（49B激活）而DeepSeek-V4-Flash拥有284B参数（13B激活）——两者都支持一百万个token的上下文长度。两者都是Hugging Face上的开放权重MoE检查点。

旧ID仍然有效，但它们处于倒计时状态。为了兼容性，它们分别对应于DeepSeek-V4-Flash的非思考模式和思考模式。两者都将退役。 2026-07-24 15:59 UTC. 迁移只需一行更改：只需更新 基础URL 不移动，你只需更新 模型. 如果你维护较旧的集成，请参阅我们关于 DeepSeek OpenAI SDK 兼容性的说明 截止日期之前。

输出长度在 V4 中也进行了扩展。最大输出为 384,000 个标记，并且思考最大模式明确需要空间——对于Think Max推理模式，DeepSeek建议将上下文窗口至少设置为384K个token。

快速入门：curl和Python中的有效请求

最简单可行的方法是对V4-Flash的非流式调用。V4默认启用思考；要选择更经济的非思考路径，请传递，然后使用此片段作为你的烟雾测试。对于更多变体——流式传输、工具调用、重试——请参阅我们的集合。 extra_body={"thinking": {"type": "disabled"}} 从 Python 或 "thinking": {"type": "disabled"} 在 JSON 主体中。这里是用 curl:

curl https://api.deepseek.com参数 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" 
  -d '{
    "模型": "deepseek-v4-flash",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user",   "content": "Summarise the DeepSeek V4 release in one sentence."}
    ],
    "thinking": {"type": "disabled"}
  }'

同样的调用在 Python 使用 OpenAI SDK —— 注意，这仅 基础URL 与 OpenAI 集成有所不同：

from openai import OpenAI

client = OpenAI(
    基础URL="https://api.deepseek.com",
    API密钥="YOUR_DEEPSEEK_KEY",
)

resp = client.chat.completions.create(
    模型="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user",   "content": "Summarise the DeepSeek V4 release in one sentence."},
    ],
    extra_body={"thinking": {"type": "disabled"}},  # V4 enables thinking by default; opt out for the cheapest path
)
print(resp.choices[0].message.content)

如果您还没有创建密钥，请从我们的 如何获取 DeepSeek API 密钥，然后使用此片段作为你的烟雾测试。对于更多变体——流式传输、工具调用、重试——请参阅我们的集合。 DeepSeek API 代码示例.

思考模式：一个参数，不是一个模型

V4将旧的“聊天与推理”分离合并为一个单一请求参数。V4两个等级都接受三个推理努力设置：

1. 非思考. 传递 extra_body={"thinking": {"type": "disabled"}} 选择退出V4默认设置。无推理跟踪。每个请求最快且最便宜。支持FIM（Beta）。
2. 思考（高） —— V4 的默认设置。 reasoning_effort="高" 启用思考模式时，这是V4在没有发送任何标志时的行为。当你想明确指出时，请显式传递；API返回ID，因此现有的解析代码仍然可以工作。 reasoning_content alongside the final content.
3. . 设置Thinking-max reasoning_effort="最大"最大努力；需要上述提到的较长的输出窗口。

V4-Pro在思考模式下的最小Python：

resp = client.chat.completions.create(
    模型="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Plan a safe schema migration for a 2 TB Postgres table."}],
    reasoning_effort="高",
    extra_body={"thinking": {"type": "enabled"}},
)
print(resp.choices[0].message.reasoning_content)  # reasoning content emitted before the final answer
print(resp.choices[0].message.content)            # the final answer

该响应的形状——一个单独的 reasoning_content 字段加上正常的 content ——与旧版 deepseek-reasoner 生成ID的时长较长；实际上，你将触摸到几个字段。DeepSeek直接在其文档中发布温度指导，这比重新发明更有价值。 DeepSeek API审查.

值得了解的核心请求参数

参数的参考页面 参数 深度处理时，思考模式如何获得额外的token，请参阅我们的

对于本地部署，DeepSeek建议将采样参数设置为温度=1.0，核心采样截止值=1.0。对于托管API，你可以根据特定任务偏离这些设置（代码为0.0，创意为1.5），但不要在没有检查的情况下将OpenAI或Claude的默认值复制到DeepSeek中。

JSON模式：设计，不保证

JSON模式是代理工作中最有用的功能之一，同时也是最常被误用的功能。三条规则：

• 包含该词 “json” 在提示中加上一个小示例架构。
• 设置 输出长度上限 足够高，以确保输出不会在对象中间截断。
• H以及le the occasional empty content response on the client side.

JSON模式是 设计用来返回有效的JSON，但不保证。如果您需要详细信息，我们将在 DeepSeek API JSON模式 中介绍验证模式.

测试版功能

DeepSeek API支持FIM（中间填充）补全，与OpenAI的FIM补全API兼容，允许用户为模型提供自定义的前缀/后缀以完成内容——常用于故事补全和代码补全等场景，并且与Chat补全API收费相同。FIM仅在非思考模式下运行，您必须将基本URL切换到 https://api.deepseek.com/beta. 聊天前缀补全需要最后一条消息的角色为助手，且前缀参数设置为True，还需要基础URL="https://api.deepseek.com/beta"以启用Beta功能。

定价和成本计算

DeepSeek对缓存命中输入令牌、缓存未命中输入令牌和输出令牌分别收费。不同级别的收费标准差异很大。截至2026年4月，每100万个令牌：

每个现实成本估算都列举了这三个类别。以下是一个 deepseek-v4-flash: 1,000,000次调用，每次调用包含一个2,000令牌的系统提示（跨调用缓存），一个200令牌的用户消息（到达时未缓存）和一个300令牌的响应。

Cached input   : 2,000 × 1,000,000 = 2,000,000,000 tok × $0.0028/M = $5.60
Uncached input :   200 × 1,000,000 =   200,000,000 tok × $0.14/M   = $28.00
Output         :   300 × 1,000,000 =   300,000,000 tok × $0.28/M   = $84.00
                                                                    --------
Total                                                               $117.60

相同工作负载在 deepseek-v4-pro 其费率表上的

Cached input   : 2,000,000,000 tok × $0.003625/M = $    7.25  (promo; list $29.00)
Uncached input :   200,000,000 tok × $0.435/M    = $   87.00  (promo; list $348.00)
Output         :   300,000,000 tok × $0.87/M     = $  261.00  (promo; list $1,044.00)
                                                    ---------
Total                                               $  355.25  (V4-Pro 75% promo through 2026-05-31; list $1,421.00)

在列表价格下，V4-Pro在该工作负载上的花费大约是V4-Flash的十倍（在2026年5月31日前的75% V4-Pro促销期间大约是三倍）。总输入令牌等于prompt_cache_hit_tokens和prompt_cache_miss_tokens，两者都会在报告中返回。 使用情况 每个响应中都有字段，因此您可以观察生产环境中的缓存命中率，而不是猜测。 DeepSeek定价计算器, 以及 for the full rate-card context see DeepSeek API pricing.

速率限制和配额

DeepSeek 不会像某些提供商那样发布每分钟令牌上限。平台在推理调度期间保持请求开放，而不是在大多数情况下用429状态码拒绝它们，这意味着您的重试逻辑需要明确的超时时间，而不是原始的指数退避。 GET /模型s 以及 GET /user/balance这些值得在您的部署检查中连接。 DeepSeek API速率限制.

错误处理模式

我们在以下位置保持关于吞吐量行为的最新记录。

• 总是验证工具调用参数。 函数参数由模型以JSON格式生成；模型并不总是生成有效的JSON，并且可能会生成您函数模式中未定义的参数，因此在调用您的函数之前，请在您的代码中验证这些参数。
• 只重试幂等调用。 在余额充值之前，402错误不可重试；5xx错误通常可以。
• 使用显式超时。 因为平台可以在调度期间保持连接，所以客户端的60-120秒超时加上有限的重试比无限期等待更合理。
• 记录 使用情况 每个调用。 缓存命中分割是您调试突然成本激增的方法。

完整的错误代码参考位于 DeepSeek API错误代码.

上下文缓存——最经济的优化

缓存命中定价是自动的：当提供商检测到您的 messages 前缀之前已经出现过，重复的标记在命中率（在V4-Flash上，$0.0028 vs $0.14 缓存未命中——自2026-04-26以来降低了98%）上计费。有两件事要记住。首先，只有命中；每个新的用户消息在模型看到它之前，对该前缀都是未命中。其次，缓存是机会性的，不是保证的——你不能假设命中率，只能测量它。对于代理工作的实际影响是将你的稳定系统提示和少样本示例放在[2]的开头。Hugging Face团队发布的V4版本博客也给出了对API用户有重要意义的架构变化的良好概述——两个MoE检查点在Hub上，DeepSeek-V4-Pro总参数量为1.6T，活跃参数量为49B，DeepSeek-V4-Flash总参数量为284B，活跃参数量为13B，两者都具有1M标记的上下文窗口。对于本网站上其他所有内容，[3]DeepSeek AI指南是一个独立资源，与DeepSeek及其母公司无关。模型ID、定价和API行为可能会变化；在做出生产决策之前，请检查官方DeepSeek文档和定价页面。 前缀 hits; each new user message is still a miss against that 前缀 until the 模型 has seen it. Second, the cache is opportunistic, not guaranteed — you cannot assume a hit rate, only measure it. The practical implication for agent work is to put your stable system prompt 以及 few-shot examples at the start of[2]. The V4 release blog from the Hugging Face team also gives a good overview of the architecture changes that matter to API users — two MoE checkpoints are on the Hub, DeepSeek-V4-Pro at 1.6T total parameters with 49B active 以及 DeepSeek-V4-Flash at 284B total with 13B active, both ，包含一个 1M-token context window. For everything else on this site, the[3] DeepSeek AI Guide is an independent resource 以及 is not affiliated with DeepSeek or its parent company. 模型IDs, pricing 以及 API behaviour change; check the official DeepSeek documentation 以及 pricing page before committing to a production decision.[3] DeepSeek AI Guide is an independent resource 以及 is not affiliated with DeepSeek or its parent company. 模型IDs, pricing 以及 API behaviour change; check the official DeepSeek documentation 以及 pricing page before committing to a production decision. messages 以及 let the variable user content trail at the end. More detail lives at DeepSeek上下文缓存.

下一步去哪里

如果您想在此页面的同时阅读完整的官方参考，请访问 api-docs.deepseek.com. The V4 release blog from the Hugging Face team also gives a good overview of the architecture changes that matter to API users — two MoE checkpoints are on the Hub, DeepSeek-V4-Pro at 1.6T total parameters with 49B active 以及 DeepSeek-V4-Flash at 284B total with 13B active, both ，包含一个 1M-token context window. For everything else on this site, the[3] DeepSeek AI Guide is an independent resource 以及 is not affiliated with DeepSeek or its parent company. 模型IDs, pricing 以及 API behaviour change; check the official DeepSeek documentation 以及 pricing page before committing to a production decision. DeepSeek API docs 以及 guides 集线器是起点。

DeepSeek AI Guide is an independent resource 以及 is not affiliated with DeepSeek or its parent company. 模型IDs, pricing 以及 API behaviour change; check the official DeepSeek documentation 以及 pricing page before committing to a production decision.