火山引擎方舟 / 豆包 API 完全指南：通过 TheRouter 接入字节跳动大模型平台

火山方舟（Volcano Ark）是字节跳动旗下火山引擎推出的大模型服务平台。它通过一个 OpenAI 兼容端点提供完整的豆包模型家族——从超低成本的 Seed 2.0 Mini 到前沿级别的 Seed 2.0 Pro。你只需要替换 base_url 和 api_key，现有的 OpenAI SDK 代码无需任何改动就能调用字节跳动的模型。

写这份指南是因为火山引擎的文档虽然全面，但分散在数十个页面中，而「火山引擎」「火山方舟」「豆包」「Seed」之间的关系也经常让开发者困惑。这是我们在首次把火山引擎接入路由配置时，希望手边能有的那份参考文档。

火山方舟、豆包和 Seed 的关系

命名层级如下：

• 火山引擎（Volcengine）是字节跳动的云平台，类似于阿里云或 AWS 的定位。
• 火山方舟（Volcano Ark）是火山引擎中的 AI 模型服务层，所有大模型 API 调用都经过方舟。
• 豆包（Doubao）是面向消费者的 AI 产品品牌，API 模型以豆包命名。
• Seed 是字节跳动内部的研究团队名称，同时也是最新一代模型的系列名（Seed 1.6、Seed 1.8、Seed 2.0）。

实际操作流程：在火山引擎注册账号，打开方舟控制台，开通豆包模型，然后调用方舟 API。

OpenAI 兼容指供应商提供一个 chat-completions 接口，其请求与响应结构与 OpenAI API 契约足够接近——只需替换三个值（API key、base URL、模型名），原来的 OpenAI SDK 调用即可直接工作。最小实践面是POST /v1/chat/completions 带 messages、model， 并返回 OpenAI 形式的流式响应。

3 分钟快速开始

第 1 步：注册火山引擎账号。 前往 console.volcengine.com 注册。支持手机号、邮箱和微信登录。完成实名认证——这是调用任何模型的前提条件。

第 2 步：获取 API Key。 进入方舟控制台 → 侧栏 API Key 管理 → 创建 API Key。复制保存——火山引擎不会再次显示完整 Key。

第 3 步：开通模型。 在方舟控制台的开通管理页面激活你需要使用的豆包模型。每个模型需要单独开通——不开通就无法调用。

第 4 步：发送第一次请求。 安装 OpenAI Python SDK：

pip install --upgrade openai

然后运行：

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("ARK_API_KEY"),
    base_url="https://ark.cn-beijing.volces.com/api/v3",
)

response = client.chat.completions.create(
    model="doubao-seed-1-6-251015",
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手。"},
        {"role": "user", "content": "用一段话解释什么是火山方舟。"},
    ],
)

print(response.choices[0].message.content)

完成。你刚刚用标准 OpenAI SDK 调用了豆包模型。唯一的区别：base_url 指向方舟，api_key 是方舟的 Key，model 是豆包的模型 ID。

Base URL 说明： 方舟 API 端点是 https://ark.cn-beijing.volces.com/api/v3。Coding Plan（面向 Claude Code、Cursor 等编程工具）使用专用端点 https://ark.cn-beijing.volces.com/api/coding。

可用模型：完整豆包产品线

火山引擎托管了完整的豆包模型家族。以下是截至 2026 年 6 月可通过 TheRouter 路由的核心模型：

定价来源：models-data.ts 和 火山方舟定价页面，获取时间 2026-06-13。价格为 USD/1M tokens。

2026-10-10 更新：已移除 Doubao 1.5 Pro (32K) 与 Doubao Seed 1.6 两行——字节跳动于 2026-09-21 下线了这两个快照（火山方舟模型下线公告第九批），它们在 TheRouter 上已不再可用。厂商指定的替代模型是 Doubao Seed 2.0 Lite。

模型层级解读

Seed 2.0 系列（2026 年 2 月发布）是最新一代，针对生产部署做了系统优化：

• Pro ——前沿模型。在复杂推理、多步骤任务和 Agent 工作流上表现最佳。发布时在 LMSYS Chatbot Arena 总榜排名第 6、视觉榜排名第 3（来源）。
• Code Preview ——专为 Agentic 编程设计。与 Pro 同价，针对软件开发工作流优化，支持 256K 上下文和 UI 截图视觉能力。
• Lite ——高性价比变体。大约 Pro 80% 的质量，但成本大幅降低，适合需要控制成本的生产负载。
• Mini ——超低成本。输入价格 $0.000072/1M tokens，是目前可用的最便宜的生产级 LLM API 之一。适合分类、信息抽取和高吞吐场景。

Seed 1.6 系列仍然可用且实用：

• Seed 1.6 ——256K 上下文通用模型，定价极低。支持思考模式、非思考模式和自适应思考模式。
• Seed 1.6 Thinking ——深度推理变体，输出包含显式推理轨迹。较高的输出价格反映了思考 token 的开销。

1.5 系列是上一代，仍可用于现有集成。

通过方舟 API 直接访问的扩展模型

除了可通过 TheRouter 路由的模型外，火山方舟还托管更多豆包模型：Doubao Seed 1.8（256K 上下文，增强 Agent 能力）、Doubao Seed Code（专用编程模型）、各类视觉变体和嵌入模型（doubao-embedding-large）。方舟还托管第三方模型——包括 DeepSeek R1/V3、GLM 和 Kimi 模型——使用同一个 API Key 和端点即可访问。

OpenAI SDK 配置：base_url、模型 ID 和流式输出

Python

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("ARK_API_KEY"),
    base_url="https://ark.cn-beijing.volces.com/api/v3",
)

# 非流式
response = client.chat.completions.create(
    model="doubao-seed-2-0-pro-260215",
    messages=[{"role": "user", "content": "什么是 Transformer？"}],
)
print(response.choices[0].message.content)

# 流式
stream = client.chat.completions.create(
    model="doubao-seed-2-0-pro-260215",
    messages=[{"role": "user", "content": "写一首关于 AI 的俳句"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

curl

curl https://ark.cn-beijing.volces.com/api/v3/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seed-2-0-pro-260215",
    "messages": [{"role": "user", "content": "你好！"}]
  }'

深度思考模式

火山方舟支持 Seed 1.6 及以上模型的思考模式。通过 extra_body 启用：

response = client.chat.completions.create(
    model="doubao-seed-1-6-251015",
    messages=[{"role": "user", "content": "证明根号 2 是无理数。"}],
    extra_body={
        "thinking": {"type": "enabled", "budget_tokens": 32000}
    },
)

思考 token 会出现在响应中并按输出价格计费，但推理轨迹本身提供了模型解题过程的可见性。

函数调用 / 工具使用

以上所有豆包模型均支持标准 OpenAI tools 和 tool_choice 参数的函数调用：

response = client.chat.completions.create(
    model="doubao-seed-2-0-pro-260215",
    messages=[{"role": "user", "content": "北京现在天气怎么样？"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的当前天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名称"}
                },
                "required": ["city"]
            }
        }
    }],
    tool_choice="auto",
)

定价详解

火山方舟对 Seed 系列采用基于输入长度的分级定价。以下是 Seed 1.6/1.8 模型的官方人民币定价：

来源：火山方舟定价页面，获取时间 2026-06-13。

短输出优惠： 当输入 ≤ 32K 且输出 ≤ 200 tokens 时，输出价格降至 ¥2/百万 tokens。适合分类和信息抽取任务。

思考 token 按同一输出价格计费——推理轨迹不额外收费。

与其他平台对比

豆包的定价非常激进——Seed 2.0 Mini 的输入价格 $0.000072/1M tokens 是目前可用的最低生产级 LLM API 价格之一。对于高吞吐、成本敏感的场景（客服分流、文档抽取、分类），这个价格很难被击败。

免费额度

新注册火山引擎账号完成实名认证后，每个模型赠送 50 万 tokens 的免费推理额度，有效期 30 天。火山引擎还提供「安心模式」，将用量限制在免费额度内——用完即停，不产生额外费用。

常见错误及排查

错误码来源：火山方舟错误码参考，获取时间 2026-06-13。

排查优先级： API Key 有效性 → 模型是否开通 → 账户余额 → 请求参数 → 限流。

模型开通的坑

与百炼或硅基流动不同——拿到 API Key 就能立即调用任意模型——火山方舟要求你在控制台手动开通每个模型才能调用。如果漏掉这一步，你会收到 404 ModelNotOpen 错误，看起来好像模型根本不存在。几乎所有开发者在首次对接方舟时都会踩这个坑。

生产上线清单

在将火山方舟集成部署到生产环境之前：

• API Key 轮换 ——将 Key 存储在环境变量或密钥管理器中，绝不写入源代码。方舟 API Key 不会自动过期，但建议定期轮换。
• 模型开通检查 ——确认每个计划调用的模型都已在方舟控制台开通。在 CI 管道中自动化此检查。
• 限流感知 ——火山引擎对每个模型执行 RPM（每分钟请求数）和 TPM（每分钟 token 数）限制。监控 429 响应，实现指数退避。
• 内容审核 ——火山引擎执行中国大陆内容合规要求。输入和输出都可能被标记。在错误处理路径中妥善处理 400 InputTextSensitiveContentDetected。
• 计费告警 ——在火山引擎计费控制台设置消费告警。开发阶段使用「安心模式」防止意外扣费。
• 延迟基线 ——方舟的北京端点（ark.cn-beijing.volces.com）针对中国大陆流量优化。如果你的服务器在中国大陆以外，预期会有较高延迟。据此配置超时时间。
• 备援策略 ——配置供应商备援，当火山方舟不可达或限流时，应用自动切换到备选供应商。TheRouter 的备援路由会自动处理这一点。

TheRouter 集成

TheRouter 通过配置的供应商路由 OpenAI 兼容请求，其中包括火山方舟。如果你已经在使用 TheRouter，可以直接把豆包模型添加到路由配置中，无需修改任何应用代码。

上表中列出的全部 8 个豆包模型都可通过 TheRouter 使用，前缀为 bytedance/。例如：

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_THEROUTER_KEY",
    base_url="https://api.therouter.ai/v1",
)

response = client.chat.completions.create(
    model="bytedance/doubao-seed-2.0-pro-260215",
    messages=[{"role": "user", "content": "来自 TheRouter 的问候！"}],
)

备援链

你可以将豆包模型配置为备援链的一部分——例如，优先使用 Doubao Seed 2.0 Pro，当火山引擎不可用时切换到 DeepSeek V4：

bytedance/doubao-seed-2.0-pro-260215 → deepseek/deepseek-v4-flash

这样你既能享受豆包的价格优势，又能获得多供应商冗余的可靠性。完整配置详见LLM API 备援路由指南。

延伸阅读

• 火山方舟文档中心 ——官方文档
• 火山方舟快速入门 ——官方入门指南
• 火山方舟定价 ——官方定价页面
• 火山方舟 OpenAI SDK 兼容说明 ——SDK 迁移说明
• Seed 2.0 正式发布 ——字节跳动 Seed 团队公告
• 火山方舟错误码参考 ——完整错误码文档
• TheRouter 火山引擎供应商页面 ——模型目录和路由配置