豆包 API 怎么接入？火山方舟密钥申请与 SDK 调用
数据截至 2026-07，价格与限额以各官网为准。
豆包 API 接入走的是火山引擎的”方舟”（Ark）平台，和很多厂商”注册完直接拿 key 调模型”的路子不太一样——你得先给要用的模型建一个专属的”推理接入点”（Endpoint），再用 Endpoint ID 去调用；搞懂这一步，剩下的 OpenAI 兼容调用就跟别家没什么区别。
不少人第一次接豆包会卡在这儿：教程里说”去控制台建 key”，结果建完 key 一调用还是报错，因为漏了建接入点这一步。这篇按真实顺序走一遍，把这个和别家不一样的机制讲透，再给一段能直接跑的代码。
火山方舟和别家不一样的地方：先建”推理接入点”
打开 console.volcengine.com 或直接搜”火山引擎控制台”，用手机号或企业主体注册，然后必须完成实名认证——没实名，连模型都选购不了，这一步跳不过去。
实名之后，重点来了：豆包不是”注册完就有一个万能 key 能调所有模型”，而是要先进方舟控制台 → 在线推理 → 自定义推理接入点，点”创建推理接入点”，选你要用的模型（豆包系列、DeepSeek 系列等火山上架的模型都在这个入口选），确认后系统会给你生成一个专属的 Endpoint ID，长得像 ep-20250512195705-c8kq4 这样一串。
这么设计是有道理的：接入点相当于给”某个模型的某次调用配置”开了一个独立的控制面板，方便你在控制台里单独看这个接入点的限流、监控、账单，而不是所有模型混在一笔账里说不清楚。如果你同时用豆包主力模型和编程模型，建议分开建两个接入点，将来查用量、查报错都好定位。
建完接入点之后，才轮到拿 API Key：进控制台里的 API Key 管理页面，点”创建 API Key”，复制保存——这一步和别的平台一样，密钥只显示一次，关掉弹窗就看不到明文了，当场存进密码管理器，别只是瞄一眼。方舟的 Key 还支持精细化权限管理，比如绑定 IP 白名单、限制能访问的资源范围，团队协作场景下这个功能挺实用，能避免一个 key 泄露就全盘失控。
还有一个安全建议值得提一句：主账号的 Access Key 权限比较大，如果你的场景只是调用推理接口，官方建议单独建一个 IAM 子账号来管这类调用型 Key，别拿主账号权限最大的凭证到处塞进代码里。
拿到 Endpoint ID 和 API Key 之后：调用怎么发
方舟的推理接口是 OpenAI 兼容的，这是它对开发者最友好的一点——如果你之前写过 OpenAI SDK 的代码，几乎不用重学，只要换两个参数：base_url 换成火山的地址，api_key 换成刚才拿到的 Key。
Base URL 固定是：
https://ark.cn-beijing.volces.com/api/v3
Chat 对话接口对应的完整路径是 POST https://ark.cn-beijing.volces.com/api/v3/chat/completions，但你一般不用自己拼 URL，用 SDK 传 base_url 就行。
Python 侧，先装官方 openai SDK（不用装火山专属包也能跑）：
import os
from openai import OpenAI
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="ep-20250512195705-c8kq4", # 这里填你自己创建的接入点 Endpoint ID
messages=[
{"role": "system", "content": "你是一个有帮助的助手。"},
{"role": "user", "content": "你好，介绍一下你自己"},
],
)
print(response.choices[0].message.content)
这里最容易让新手犯迷糊的地方是 model 这一行——官方示例里 model 既可以填你自己创建的 Endpoint ID（ep- 开头那串），也可以直接填模型 ID 本身（比如 doubao-seed-1-6-251015 这种带版本号的字符串），两种写法官方文档里都有出现，效果是一样的。区别在于：填 Endpoint ID，控制台那边的限流、监控、账单都会记在这个接入点名下，方便管理；直接填模型 ID 调用也能通，但你就没法在控制台按接入点维度单独看这次调用的数据了。新建正式应用，建议优先用 Endpoint ID，图个方便后续排查问题。
流式输出也很简单，加一个 stream=True，逐块读 chunk.choices[0].delta.content 就行，跟标准 OpenAI SDK 的流式写法完全一致，没有额外要学的东西。
如果你不想依赖 openai 这个包，火山官方也提供了专属 SDK volcenginesdkarkruntime，走的是新版 Responses API 风格：
import os
from volcenginesdkarkruntime import Ark
client = Ark(
base_url="https://ark.cn-beijing.volces.com/api/v3",
api_key=os.getenv("ARK_API_KEY"),
)
response = client.responses.create(
model="doubao-seed-2-1-pro-260628", # 示例接入点/模型名，实际以控制台生成为准
input="hello",
)
print(response)
两条路都能走通，选哪个看团队习惯——如果项目里已经大量用 openai 这个包做多家模型的适配层，走兼容模式省事；如果就专门服务豆包这一家、想用官方最新特性，装专属 SDK 也不麻烦。
新用户免费额度：50 万 tokens 够跑不少测试了
注册火山引擎并开通方舟之后，新用户有一份一次性”安心体验”额度：豆包全系模型（包括方舟上架的 DeepSeek 系列等其他厂商模型）共赠送 50 万 tokens 的免费推理额度，够你把接入流程完整跑通、写几十上百次测试请求了，不用一上来就掏钱。
这份额度有几个使用上的边界要注意：它只能抵扣按 token 计费的在线推理费用，不能用来抵扣插件调用、知识库调用产生的费用，也不能抵扣批量推理（Batch）产生的 token 消耗；但可以抵扣上下文缓存命中和未命中的 token、以及输出 token 的费用，只是抵不了缓存本身的存储费用这一小块。另外，部分基础模型（豆包 pro/lite 的 4K、32K 版本）还额外给了 1 万 RPM、80 万 TPM 的免费流量额度，主要是给这些入门规格用的，别和 50 万 tokens 那笔一次性额度搞混了，这是两码事。
至于网上有说法提到控制台”开通管理”页可以手动加入什么”协作奖励计划”、每天再送 200 万 tokens——这条信息来自第三方汇总而非官方一手文档，本文不把它当成确定事实写，如果你感兴趣，去控制台的开通管理页面自己核实一遍最靠谱，别按传闻直接规划预算。
常见坑 / 注意
- 建 key 前先建接入点：忘了这一步是新手最常踩的坑，key 建好了但没对应可用的接入点，调用照样报错。
- 实名认证是硬门槛：没实名连模型都选购不了，注册完先把这一步走完再往下弄。
- 密钥只显示一次：弹窗关掉就是明文再见，当场复制存好。
- model 字段填 Endpoint ID 还是模型 ID 都行：但填 Endpoint ID 才能在控制台按接入点单独看限流和账单，新项目建议优先用它。
- 50 万 tokens 免费额度抵不了 Batch 和插件调用：别以为这份额度啥都能抵，账单细则见上一节。
- 主账号 Access Key 别到处塞：只做推理调用，走 IAM 子账号更安全。
- 别把第三方传闻当官方规则：比如”每日 200 万 tokens 协作奖励”这类没有官方一手文档确认的说法，用之前自己去控制台核实一遍。