DeepSeek V4 API 编程指南：路由 deepseek-v4-pro 和 deepseek-v4-flash

将编码会话的每一步都发送给同一个模型是最简单的路由策略，但通常也是最昂贵的。本教程展示了如何在 TokenLab 上使用 DeepSeek V4 API 进行编程，通过在 deepseek-v4-pro 和 deepseek-v4-flash 之间分配工作来优化成本。我们于 2026 年 10 月 3 日从实时 API 读取了两个模型的记录，以下所有内容均来自这些记录和 TokenLab 文档。你将获得一份对比表、一份工作成本估算、一个工具调用请求示例、重试和回退代码，以及预检检查方法。

关键要点

• 两个模型均列出了 1,000,000 token 的输入限制、384,000 token 的输出限制，以及相同的三种请求格式。价格是它们之间的主要区别。
• 按标价计算，deepseek-v4-pro 的单位输入 token 成本是 deepseek-v4-flash 的 4.4 倍，单位输出 token 成本是后者的 3.3 倍。
• 在我们 20 次调用的示例中，将 4 次调用路由至 pro，16 次路由至 flash，非高峰期成本约为 $0.18。若 20 次全部发送至 pro，成本约为 $0.46。
• 在收到 Retry-After 后重试 429。仅当 retryable 为 true 时才重试 500–504。切勿重试 400、401、402、403、404 或 413。
• 目录显示 deepseek-v4.1-flash 为活跃状态。deepseek-v4-pro 和 deepseek-v4-flash 均未指定替代模型。
• 在进行路由之前，请先从 GET /v1/models/:model 读取限制、格式和价格。不要硬编码复制的表格。

DeepSeek V4 API 编程：目录说明

我们于 2026 年 10 月 3 日获取了这两条记录。下表对它们进行了并排比较。价格为每 100 万 token 的美元金额，目录定价最后更新于 2026-10-02T16:53:30.068Z。

项目	deepseek-v4-pro	deepseek-v4-flash	来源，观察于 2026-10-03
上下文限制 (最大输入 token)	1,000,000	1,000,000	pro, flash
输出限制 (最大输出 token)	384,000	384,000	pro, flash
接受的请求格式	anthropic_messages, openai_chat_completions, openai_responses	anthropic_messages, openai_chat_completions, openai_responses	pro, flash
能力	json-mode, prompt-cache, tool-use	json-mode, prompt-cache, tool-use	pro, flash
非高峰期输入	$0.66	$0.15	pro, flash
非高峰期输出	$1.98	$0.60	pro, flash
非高峰期缓存读取	$0.022	$0.003	pro, flash
非高峰期缓存写入	$0.66	未列出	pro, flash
高峰期输入	$1.32	$0.30	pro, flash
高峰期输出	$3.96	$1.20	pro, flash
高峰期缓存读取	$0.044	$0.006	pro, flash
生命周期阶段	active, 发布于 2026-04-24	active, 发布于 2026-04-24	pro, flash

每条记录中的默认价格块与非高峰期条目一致。高峰期时间因记录而异。对于 deepseek-v4-pro，高峰价格适用于北京时间 09:00-12:00 和 14:00-18:00。对于 deepseek-v4-flash，记录显示高峰窗口适用于工作日，不包括中国公共假期。它提到非高峰期包括周末和这些假期，但未给出具体小时数。在围绕 flash 窗口进行预算之前，请检查定价端点。

生命周期和较新的 DeepSeek 模型

两条记录均显示 lifecycle stage active，且 replacement model、deprecated_at 和 retired_at 均为空。因此，目录中没有安排移除这两个模型，也没有为它们指定继任者。

目录中还列出了 deepseek-v4.1-flash。其记录（观察于 2026-10-03）显示为活跃状态，没有发布日期，也没有替代模型。它具有与 deepseek-v4-flash 相同的限制、格式和标价。它在能力列表中增加了 reasoning 和 vision，并显示非高峰期缓存写入价格为 $0.15。

这是一个单独的模型 ID，因此本文保持其主题。我们建议在替换之前先在你的任务上测试 deepseek-v4.1-flash。目录中还列出了 deepseek-v4-flash-vision-exp，但我们没有读取其记录。如果需要，请在 Models 页面上进行验证。

按任务路由 deepseek-v4-pro 和 deepseek-v4-flash

想象一个代理会话，它计划跨五个模块进行更改，编写编辑内容，然后生成一打测试存根。第一步需要最多的上下文和关注。最后一步是重复性的，重做成本很低。目录无法告诉你质量界限在哪里。2026 年 10 月 3 日观察到的 TokenLab 编码代理模型指南指出，排行榜结果无法预测模型遵循你自己的指令和工具的能力。

我们的起始启发式假设是，价格更高的模型在跨文件工作中能体现其价值。将其视为一个待测试的假设，而非结论：

+-------------------------------------------------------------+
|                      传入任务                                |
+-------------------------------------------------------------+
                               |
         [任务是否涉及多文件上下文、
          向后兼容性或安全审查？]
                               |
               +---------------+---------------+
               |                               |
             [是]                             [否]
               |                               |
               v                               v
       deepseek-v4-pro                 deepseek-v4-flash

将步骤推向 deepseek-v4-pro 的标准：

• 修改跨多个导入文件的逻辑。
• 安全或漏洞评估。
• 公共接口的严格向后兼容性。
• 准确性比周转时间更重要的多轮工作。

独立的测试脚手架、模式格式化、文档字符串和语法补全则交给 deepseek-v4-flash。

要测试该启发式方法，请遵循相同的指南。为每个模型提供相同的存储库状态、指令、工具和时间限制。然后比较正确性、通过的测试、不必要的更改、总 token 数、最终成本以及人工介入的频率。按任务类型保留结果，因为一个模型可能审查得很好但实现得很差。

估算编码代理循环成本

代理在每次调用时都会重新发送指令、历史记录、代码和工具结果。2026 年 10 月 3 日观察到的 成本指南指出，长会话的成本可能远高于单次聊天请求。我们根据标价计算了下方的算术结果。该结果仅为估算值，而非实际账单。

假设（我们的假设，未经测量）： 一个包含 20 次模型调用的循环，每次有 30,000 个输入 token 和 1,500 个输出 token。总计 600,000 个输入 token 和 30,000 个输出 token。

公式为 输入 token / 1M × 输入价格 + 输出 token / 1M × 输出价格。价格来自上表。

20 次调用全部使用 deepseek-v4-pro：

• 非高峰期：0.6 × $0.66 = $0.396 输入，加上 0.03 × $1.98 = $0.0594 输出，总计 $0.4554。
• 高峰期：0.6 × $1.32 = $0.792，加上 0.03 × $3.96 = $0.1188，总计 $0.9108。

20 次调用全部使用 deepseek-v4-flash：

• 非高峰期：0.6 × $0.15 = $0.09，加上 0.03 × $0.60 = $0.018，总计 $0.108。
• 高峰期：0.6 × $0.30 = $0.18，加上 0.03 × $1.20 = $0.036，总计 $0.216。

混合：4 次调用 pro，16 次 flash。 Pro 承担 120,000 个输入和 6,000 个输出 token。Flash 承担 480,000 个输入和 24,000 个输出 token。

• 非高峰期：pro 为 0.12 × $0.66 + 0.006 × $1.98 = $0.0792 + $0.01188 = $0.09108。Flash 为 0.48 × $0.15 + 0.024 × $0.60 = $0.072 + $0.0144 = $0.0864。总计 $0.17748。
• 高峰期：pro 为 0.12 × $1.32 + 0.006 × $3.96 = $0.1584 + $0.02376 = $0.18216。Flash 为 0.48 × $0.30 + 0.024 × $1.20 = $0.144 + $0.0288 = $0.1728。总计 $0.35496。

场景	非高峰期估算	高峰期估算
20 次调用使用 deepseek-v4-pro	$0.4554	$0.9108
20 次调用使用 deepseek-v4-flash	$0.1080	$0.2160
4 pro + 16 flash	$0.1775	$0.3550

估算值基于 2026-10-03 观察到的标价（pro, flash）。

缓存变体（非高峰期，假设：80% 的输入 token 为缓存读取）。 这意味着每个循环有 480,000 个缓存读取 token 和 120,000 个未缓存 token。

• Pro：0.48 × $0.022 = $0.01056，加上 0.12 × $0.66 = $0.0792，加上 $0.0594 输出，总计 $0.14916。
• Flash：0.48 × $0.003 = $0.00144，加上 0.12 × $0.15 = $0.018，加上 $0.018 输出，总计 $0.03744。

此变体按普通输入价格计算未缓存 token，并忽略了记录中未列出的 flash 缓存写入费用。在依赖此折扣之前，请在响应或 Usage 中确认缓存 token 的数量。计费指南还警告说，最低的单位 token 价格并不总是意味着完成任务的最低成本，因为重试会增加成本。

编码代理的工具调用请求

两条记录均列出了 tool-use，且均接受 openai_chat_completions。以下请求仅使用了工具调用指南（观察于 2026-10-03）中的字段：model、messages 和带有 type: "function" 的 tools。我们添加了 max_tokens，计费指南将其列为限制响应长度的一种方式。我们省略了 tool_choice，因为该指南仅在 Responses 格式中记录了它。

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "max_tokens": 2000,
    "messages": [
      {"role": "system", "content": "You are a software engineering assistant."},
      {"role": "user", "content": "The pagination test in tests/test_api.py fails. Find the cause."}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "read_file",
          "description": "Read a file from the repository",
          "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"]
          }
        }
      },
      {
        "type": "function",
        "function": {
          "name": "run_tests",
          "description": "Run the test suite for one path",
          "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"]
          }
        }
      }
    ]
  }'

模型在 tool_calls 中返回函数名称和参数。你的后端运行该工具。循环随后分五步运行：

1. 发送消息和工具定义。
2. 读取 tool_calls 的响应。
3. 在你的后端执行工具。
4. 以相同的 API 格式附加工具结果。
5. 继续直到模型返回最终答案。

指南未内联显示工具结果消息的形状。请参考 Create Chat Completion 参考（/api-reference/chat/create-completion），而不是猜测。

在执行任何调用之前，请验证参数并应用你自己的权限检查。使执行具有幂等性，因为客户端重试可能会重复相同的工具调用。在整个交换过程中保持一种 API 格式，因为不同格式对工具状态的表示方式不同。

两个模型之间的重试、退避和回退

2026 年 10 月 3 日观察到的 错误处理指南和 速率限制指南设定了此策略。根据 HTTP 状态和 code 进行分支处理，切勿根据 message 进行处理。

状态	重复相同的请求？	操作
400, 401, 402, 403, 404, 413	否	修复请求、密钥、余额、权限或输入
429	是	等待 Retry-After；如果不存在，使用带抖动的指数退避
500–504	仅当 retryable 为 true 时	尊重 retry_after 并限制尝试次数
响应前连接关闭	有时	如果工具调用可能重复副作用，请谨慎重试
输出到达后流中断	否	将其视为不完整；重复可能会产生不同的输出或第二次收费

两种情况需要格外小心。503 all_channels_failed 或 503 delivery_tier_unavailable 并不总是暂时的。当 retryable 为 false 且 retry_after 缺失时，请勿重复请求。在选择另一个模型之前，请检查 GET /v1/models。此外，context_length_exceeded 不会通过在两个模型之间切换来解决，因为两者都列出了相同的 1,000,000 token 输入限制。

以下代码应用了该策略。它将 max_retries=0 设置为 0，以便 SDK 不会在后台重试。每个模型有四次尝试机会，回退仅在第一个模型耗尽可重试错误后运行。

import os
import random
import time
from openai import OpenAI, APIStatusError, APIConnectionError

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
)

FALLBACK = {
    "deepseek-v4-pro": "deepseek-v4-flash",
    "deepseek-v4-flash": "deepseek-v4-pro",
}

def error_fields(exc):
    body = getattr(exc, "body", None)
    if isinstance(body, dict):
        return body.get("error", body)
    return {}

def backoff(attempt):
    return min(30, 2 ** attempt + random.random())

def retry_delay(exc, attempt):
    """等待秒数，如果请求不得重复则返回 None。"""
    if isinstance(exc, APIConnectionError):
        return backoff(attempt)
    fields = error_fields(exc)
    header = exc.response.headers.get("Retry-After")
    if exc.status_code == 429:
        return float(header) if header else backoff(attempt)
    if exc.status_code >= 500 and fields.get("retryable") is True:
        wait = fields.get("retry_after") or header
        return float(wait) if wait else backoff(attempt)
    return None

def chat_with_fallback(model, messages, tools=None, attempts=4):
    last_exc = None
    for candidate in (model, FALLBACK[model]):
        kwargs = {"model": candidate, "messages": messages}
        if tools:
            kwargs["tools"] = tools
        for attempt in range(attempts):
            try:
                return candidate, client.chat.completions.create(**kwargs)
            except (APIStatusError, APIConnectionError) as exc:
                delay = retry_delay(exc, attempt)
                if delay is None:
                    raise  # 4xx 或不可重试的 5xx：不要重复或回退
                last_exc = exc
                if attempt < attempts - 1:
                    time.sleep(delay)
        print(f"{candidate} 耗尽了重试次数，正在尝试 {FALLBACK[candidate]}")
    raise last_exc

def pick_model(is_complex):
    return "deepseek-v4-pro" if is_complex else "deepseek-v4-flash"

used, response = chat_with_fallback(
    pick_model(is_complex=False),
    [{"role": "user", "content": "Write a pytest case: an empty list returns 0 for sum_items()."}],
)
print(used, response.choices[0].message.content)

始终记录哪个模型回答了问题。编码代理指南警告说，回退可能会改变价格、上下文限制、工具格式或输出风格，因此在模型更改时通知用户。按标价计算，从 flash 回退到 pro 大约会使输入成本增加四倍，因此请对此发出警报。每次调用时保存响应头中的 Request ID，以便支持人员追踪故障。

路由前读取限制、格式和价格

2026 年 10 月 3 日观察到的 Get a Model 参考描述了 GET /v1/models/:model。响应携带一个 tokenlab 对象，其中包含 capabilities、pricing、max_input_tokens、max_output_tokens、accepted_request_formats 和 lifecycle。未知模型返回 404 model_not_found。计费指南还指向 GET /v1/models/:model/pricing 以获取当前价格。

import json
import urllib.request

def read_model(model_id):
    url = f"https://api.tokenlab.sh/v1/models/{model_id}"
    with urllib.request.urlopen(url, timeout=10) as resp:
        meta = json.load(resp)["tokenlab"]
    return {
        "max_input_tokens": meta.get("max_input_tokens"),
        "max_output_tokens": meta.get("max_output_tokens"),
        "formats": meta.get("accepted_request_formats"),
        "capabilities": meta.get("capabilities"),
        "lifecycle": meta.get("lifecycle"),
        "pricing": meta.get("pricing"),
    }

def preflight(model_id, input_tokens):
    info = read_model(model_id)
    problems = []
    if "openai_chat_completions" not in (info["formats"] or []):
        problems.append("chat completions not accepted")
    if "tool-use" not in (info["capabilities"] or []):
        problems.append("no tool-use capability")
    if info["max_input_tokens"] and input_tokens > info["max_input_tokens"]:
        problems.append("input exceeds max_input_tokens")
    return info, problems

for model_id in ("deepseek-v4-pro", "deepseek-v4-flash"):
    info, problems = preflight(model_id, input_tokens=30_000)
    print(model_id, json.dumps(info, indent=2), problems)

我们打印原始的 lifecycle 和 pricing，因为本文的证据没有显示该响应内部的确切 JSON 布局。检查一次输出，然后解析你需要的字段。文档建议不要硬编码复制的价格表，因此请在启动时或按计划运行检查。公共发现端点（如 GET /v1/models）有其自己的速率限制，因此请缓存结果，而不是按请求调用它。

对于速率限制，标准 User 层级允许每个 API 密钥每分钟 1,000 次请求（观察于 2026-10-03）。指南称活动配置可能有所不同。在 429 时，请相信返回的 X-RateLimit-Limit 和 Retry-After 值，而不是任何复制的数字。

常见问题解答

我可以通过 Anthropic Messages 格式调用 deepseek-v4-pro 吗？

可以。2026 年 10 月 3 日观察到，两条记录均将 anthropic_messages 列为接受的格式。编码代理指南给出的 Anthropic Messages 基础 URL 为 https://api.tokenlab.sh，不带 Chat Completions 使用的 /v1 后缀。工具模式因格式而异，因此在整个对话中保持一种格式。

我应该重试来自 deepseek-v4-pro 或 deepseek-v4-flash 的 503 错误吗？

仅当错误主体说明 retryable 为 true 时，然后等待 retry_after。带有 retryable: false 的 503 all_channels_failed 意味着请求在所选交付层级中没有供应。重复它没有帮助。在选择另一个模型之前，请检查 GET /v1/models，如错误处理指南所述。

deepseek-v4.1-flash 会取代 deepseek-v4-flash 吗？

目录中没有这样说。2026 年 10 月 3 日，deepseek-v4-flash 记录显示没有替代模型，而 deepseek-v4.1-flash 显示为活跃状态。两者共享限制和标价，较新的模型增加了 reasoning 和 vision 能力。请在你的任务上测试它，并按模型 ID 有意识地切换。

缓存的 token 会使 deepseek-v4-flash 在代理循环中更便宜吗？

可以。记录显示非高峰期缓存读取价格为每 100 万 token $0.003，而普通输入为 $0.15。成本指南建议在依赖折扣之前，在响应或 Usage 中确认缓存 token 的使用情况。缓存行为和价格因模型而异。

路由到 deepseek-v4-flash 会提高我的速率限制吗？

不会。速率限制指南称，更快的模型不会提高你账户的请求限制。模型速度、token 限制和账户速率限制是单独的约束，限制适用于每个 API 密钥。

在连接你的路由器之前，请检查 TokenLab 模型页面上的当前 deepseek-v4-pro 和 deepseek-v4-flash 条目。