豆包大模型的 API 统一在火山引擎·火山方舟(ARK)平台开放,API Key 需从方舟控制台申请。完整流程为注册实名、开通模型、创建 API Key、创建推理接入点四步,其中「推理接入点 ID」是新手最容易漏掉的一环——调用时的 model 参数要填它,而不是模型名。首次开通语言模型每个可享 50 万免费 tokens。本文给出申请步骤、免费额度、调用示例与注意事项。 豆包 API Key 在哪里申请
先明确一件事:豆包网页版与 App 不提供 API Key。面向消费者的产品(doubao.com)与面向开发者的开放平台(火山方舟)是两套体系,账号与用途都不同。要调 API,必须走火山方舟。
| | |
|---|
| console.volcengine.com/ark | 申请 API Key、开通模型、创建推理接入点、查看用量与账单 |
| | |
| | |
| volcengine.com/product/ark | |
方舟提供 OpenAI 兼容接口,已有基于 OpenAI SDK 的代码通常只改三个值就能迁移:API Key、base_url、model。
API Key 申请与配置的 4 个步骤
从零到第一次成功调用,按以下顺序走即可:
- 注册与实名认证:打开 volcengine.com 注册账号(支持手机号、邮箱等方式),进入账号管理完成实名认证。这是硬性前提,不实名无法使用任何 API 能力,也是很多人第一步就卡住的地方;
- 开通模型:进入方舟控制台的「开通管理」,找到要用的豆包模型逐个开通,也可直接「一键开通所有模型」。开通本身免费、不产生费用,但不开通就无法调用;
- 创建 API Key:进入「API Key 管理」,点击「创建 API Key」,起一个便于区分的名字后创建。生成后立即复制保存——平台不会再次完整显示,丢失只能重新创建;
- 创建推理接入点:进入「在线推理」创建推理接入点,选择已开通的模型与地域,创建成功后会得到一个 ep 开头的接入点 ID。这一步最容易被跳过,但它是调用时 model 参数要填的值。
四个环节里,「开通模型」和「创建接入点」是方舟体系特有的两步,从 OpenAI 或其他平台迁移过来的人常常只做了第 1、3 步就直接写代码,然后对着报错怀疑人生。
豆包大模型的免费额度有多少
官方方舟产品页列出了各模型的免费额度,首次开通语言模型每个可享 50 万 tokens:
| | |
|---|
| Doubao-Seed-2.1-pro / Doubao-Seed-2.1-turbo / Doubao-Seed-Evolving | |
| |
| Doubao-Seed-Evolving / 2.1-pro / 2.1-turbo | |
| | |
Doubao-Seedream-4.5 / Doubao-Seedream-4.0 | |
| | |
| |
| | |
| | |
计费方式为按输入与输出 tokens 总量计费,每小时出账、按量后付费;调用时优先消耗免费额度,用完后再按实际 token 消耗结算。以下是官方页面列出的部分参考价格,实际以方舟定价页为准:
| | |
|---|
| 输入 6.00 元/百万 tokens,输出 30.00 元/百万 tokens | |
| 输入 6 元/百万 tokens,输出 30 元/百万 tokens | |
| 文生图 0.22 元/张,图生图 0.22 元/张 | |
| | |
另需注意欠费规则:账户余额不足或扣为负值即为欠费,官方说明欠费后 2 小时内补缴账单可正常使用服务。生产环境建议设置余额告警,不要等接口返回失败才去查。
拿到 Key 后怎么调用
方舟提供 OpenAI 兼容接口,最省事的方式是直接用 OpenAI 的 SDK,只替换三个值:
也可以用火山方舟官方 SDK volcenginesdkarkruntime(pip install volcenginesdkarkruntime)初始化 Ark 客户端,参数与上面一致。
关于 model 参数:推荐填写第 4 步创建的推理接入点 ID(ep 开头),这是官方推荐的稳定用法;部分模型也支持直接填写模型名(如 doubao-seed-1-6-251015)。接入点支持指定单一模型或智能路由,具体以控制台创建时的选项为准。
使用 API Key 的注意事项
- Key 只完整显示一次:创建时立刻复制进密码管理器或 .env,丢了只能重建,所有引用旧 Key 的服务都要同步改。
- 不要硬编码、不要进 Git、不要放前端:前端环境变量会随构建产物公开。生产环境用环境变量或密钥管理服务,并在日志中对请求头脱敏。
- 不实名认证就调不通:这是平台硬性要求,不是可选项。排查"为什么报错"时先确认这一步。
- 不开通模型会调用失败:开通免费但必需,换模型时要再确认该模型是否已开通。
- 别漏掉推理接入点:只拿 Key 不建接入点,model 参数无从填写。这是本流程中最高频的卡点。
- 免费额度有模型粒度与时效:每个模型单独计算,额度与活动规则会调整,请在控制台「资源包」中查看实际余额。
- 警惕第三方"中转 Key"与共享号:你的提示词、文档与业务数据会经过不受控的服务器,且随时可能因风控中断。
- 按项目分 Key:一个项目一把,出问题时只吊销那一把,也便于在用量统计里定位消耗来源。
- 设置余额告警:后付费模式下欠费会停服,别让线上业务卡在一张账单上。
豆包 API Key 常见问题
Q:申请 API Key 要花钱吗?
A:申请本身免费,也不需要信用卡。首次开通语言模型每个可享 50 万免费 tokens,用完后按实际 token 消耗计费。
Q:API Key 丢了能找回吗?
A:不能。平台只保存 Key 的哈希值,不会再次完整显示。只能在控制台删除旧 Key 并重新创建,然后更新所有引用处。
Q:调用时报 Authentication failed 怎么办?
A:按顺序排查四项:环境变量 ARK_API_KEY 是否真的生效、Key 是否复制完整(注意首尾空格)、Key 是否已被删除或吊销、base_url 是否拼写正确。
Q:model 该填接入点 ID 还是模型名?
A:推荐填推理接入点 ID(ep 开头),这是官方推荐用法且便于做模型路由;部分模型支持直接填模型名,具体以控制台显示为准。
Q:能直接用 OpenAI 的 SDK 吗?
A:可以。方舟提供 OpenAI 兼容的 chat-completions 接口,只需替换 api_key、base_url 与 model 三个值。
Q:豆包 App 或网页版里能拿到 API Key 吗?
A:不能。网页版与 App 面向消费者使用,API Key 必须到火山方舟控制台(console.volcengine.com/ark)申请。
Q:免费额度用完了怎么办?
A:切换到仍在额度内的其他模型,或在控制台充值后继续按量付费。长期使用者建议按模型性价比做选型,而不是默认用旗舰模型。
以上内容整理自火山引擎官网、火山方舟产品页与官方技术文档,模型列表、免费额度、价格、控制台入口与调用参数可能随官方更新而变动,请以火山方舟官方页面最新公布为准。