豆包 API 的 Key 不在豆包 App 生成，而在火山方舟控制台创建。很多人第一步就找错地方：在聊天应用里翻设置，或去费用中心找入口。要记住的是，豆包是模型系列，火山方舟是提供这些模型的服务平台，Key 属于火山引擎账号下的某个工作空间。
本文按“开通账号—创建 Key—限制权限—确认模型—排查 401—轮换”的顺序，把一条可上线的 Key 管理路径讲完；价格和配额以控制台为准。
说明：豆包、火山方舟、火山引擎、字节跳动是字节跳动及其关联公司的商标或产品名称。本文仅作技术讨论，与上述公司无隶属、代理或背书关系。接口、权限和配额可能调整，请以官方文档和控制台为准。
一、先分清账号、Key、工作空间与模型
Key 出问题，往往是下面四个对象没有对齐：
| 对象 | 在哪里 | 作用 | 常见错误 |
|---|---|---|---|
| 火山引擎账号 | 注册、实名、费用中心 | 决定余额、合同、发票和 Key 的归属 | 用个人账号跑企业业务，后续开票和对公付款对不上 |
| API Key | 方舟控制台的 API Key 管理页 | 调用时的身份凭证 | 复制时带空格、换行，或写进前端代码 |
| 工作空间 | 控制台左下角切换 | 隔离资源、成员和权限 | Key 与接入点不在同一工作空间，调用被拒绝 |
| 模型或接入点 | 模型列表、在线推理页 | 决定实际调用哪个模型 | 把模型 ID 和 ep- 开头的接入点 ID 混着填 |
记忆方法：账号决定谁付费，工作空间决定能看什么，Key 决定以什么身份调用，模型或接入点决定调用哪个版本。任何一项错位都可能表现为 401 或 404。
二、开通火山方舟并创建 API Key
以火山方舟控制台为例，流程如下：
- 注册火山引擎账号并完成实名认证。企业使用建议用企业主体，保证合同、付款和发票抬头一致。
- 进入火山方舟控制台，确认服务已开通并选好区域，例如华北（北京）。
- 在左下角确认当前工作空间。新账号通常在默认空间，团队项目建议单独建一个。
- 打开 API Key 管理页，选择“创建 API Key”，名称写清用途和环境，例如
doubao-dev-202610、doubao-prod-202610。 - 创建后立即存入密码管理器或服务端密钥管理服务，不要通过聊天工具或邮件传递完整 Key。
- 测试、预发、生产各建一把 Key，不要共用。官方文档当前说明一个主账号默认最多创建 50 个 API Key。
一个细节：官方文档提到，2026 年 9 月 17 日起新建的 Key 使用新的明文格式，认证方式不变；此前创建的 Key 继续有效。两种外观都正常，先确认 Key 属于哪个工作空间。
三、Key 的权限边界：工作空间、模型白名单与 IP 限制
API Key 不是整个账号的万能钥匙。官方文档明确，Key 只能访问创建时所在工作空间的模型服务和应用，不支持跨项目；接入点迁移到其他空间后，原 Key 会失效。
创建 Key 时或创建后，通常还可以做两类收紧：
- 限制可用模型：只允许 Key 调用指定的模型 ID 或自定义接入点，避免一把 Key 被拿去调用全部模型。
- 限制来源 IP：配置 IP 白名单，降低 Key 泄露后被异地使用的风险。
团队管理上，建议按“应用 + 环境”拆 Key，而不是按人拆。人员离职时只停用相关 Key，不影响其他服务；同时保留调用日志，能看清哪把 Key 在何时调用了哪个模型。工作空间适合隔离项目，成员权限与配额以控制台为准。
四、模型 ID 与推理接入点 ID，别混着填
火山方舟有两种常见调用方式：
- 预置推理：不需要提前创建接入点，
model直接填模型 ID，例如doubao-seed-2-1-pro-260915。模型 ID 通常带版本日期，不能凭记忆省略后缀。 - 自定义推理接入点：在“在线推理”页创建，
model填接入点 ID（通常以ep-开头）。它适合固定部署、精细管理或 LoRA 微调模型。接入点要先从“调度中”变为“健康”，才能稳定调用。
两种 ID 的区别不只是格式。官方文档说明，使用 Access Key（AK/SK）签名调用时，model 字段必须填接入点 ID；使用 API Key 时，可以按文档填模型 ID 或接入点 ID。部分模型或账号未开放“模型 ID 直调”，直接填模型名会返回 InvalidEndpointOrModel.ModelIDAccessDisabled，这时需要创建自定义接入点并改用 ep- ID。
因此，创建 Key 时不必先绑定模型，但上线前要确认：模型在当前账号和区域可用、Key 有权限访问、请求里的 model 与调用方式匹配。名称映射以控制台和站内模型价格为准。
五、把 Key 放进环境变量
不要把 Key 写进代码、配置文件或前端打包产物。服务端常见做法是使用环境变量：
# .env 只放在本机或密钥管理服务中，并加入 .gitignore
export ARK_API_KEY="你的火山方舟 API Key"
export ARK_MODEL_ID="doubao-seed-2-1-pro-260915"
# 使用自定义接入点时改为：
# export ARK_ENDPOINT_ID="ep-你的接入点ID"
Python 读取时用 os.environ["ARK_API_KEY"]，不要设默认值。容器用 Secret 挂载，CI/CD 用加密变量；日志只记录 Key 前缀或指纹。浏览器、移动端和小程序不能直接持有 Key，必须经过后端代理。
六、401、403、404、429 怎么排查
| 现象 | 常见错误码 | 常见原因 | 处理 |
|---|---|---|---|
| 401 | AuthenticationError |
Key 缺失、错误、已停用，或请求头没有 Bearer |
重新复制 Key，检查 Authorization 头，确认 Key 与接入点同空间 |
| 403 | AccessDenied |
Key 被限制模型或 IP，账号无资源权限 | 检查 Key 白名单、IP 白名单和工作空间权限 |
| 404 | InvalidEndpointOrModel.NotFound |
模型 ID、接入点 ID 写错，或当前空间无此资源 | 从控制台复制完整 ID，核对区域和工作空间 |
| 404 | ModelNotOpen |
模型尚未在账号内开通 | 在方舟控制台开通对应模型 |
| 404 | InvalidEndpointOrModel.ModelIDAccessDisabled |
当前账号不允许直接用模型 ID 调用 | 创建自定义推理接入点，改用 ep- ID |
| 429 | RateLimitExceeded.* |
账号、模型或接入点的 RPM/TPM 超限 | 降低并发，指数退避重试，必要时申请提额 |
| 500/503 | InternalServiceError、ServerOverloaded |
上游服务异常或过载 | 短暂等待后重试，准备备用模型或通道 |
排查顺序：先看 HTTP 状态，再看错误码，最后看请求体。401 不要先怀疑余额；余额不足通常对应 403 的 AccountOverdueError。404 也不要先改代码，先把模型 ID 和接入点 ID 从控制台重新复制。
七、官方直连与统一网关怎么选
官方直连适合只调用豆包、能自行完成实名与充值、需要火山引擎合同和发票的团队。Key 与 Base URL 必须成对使用：官方 Key 只配 https://ark.cn-beijing.volces.com/api/v3，网关 Key 只配网关地址，混用通常直接返回 401。
统一网关适合同时使用豆包、DeepSeek 等多家模型，或希望用一个入口统一账单、额度和日志的团队。选网关时重点确认：模型名称如何映射、流式与工具调用是否完整、Key 能否按项目限额、故障如何通知、数据条款是否满足要求。中商起航 AI 网关是独立的第三方接入服务，与字节跳动无隶属关系；需要测试可在注册页创建账号，计费见模型价格。
八、轮换与泄露处理
Key 应该像密码一样有生命周期，而不是一直用到报错：
- 新建一把同权限的新 Key，先只给测试或灰度实例使用。
- 更新环境变量或密钥管理服务，重启服务并确认调用正常。
- 观察 24–72 小时的错误率、延迟和用量。确认稳定后再停用旧 Key，不要先删除，保留一段时间便于回滚。
- 人员变动、代码泄露或 Key 出现在公开仓库时，立即停用并新建，不要只改密码。
- 检查最近的用量明细和日志，确认是否有异常模型、异常时段或异常来源 IP。
官方文档也提醒，Key 泄露意味着他人可以消耗你的配额。发现泄露时先停用止损，再排查原因。
相关阅读：
常见问题
豆包 API Key 能在豆包 App 里生成吗？
不能。豆包 App 面向普通用户，API Key 要在火山方舟控制台的 API Key 管理页创建。
创建 Key 时必须先选模型吗？
通常不必。Key 是账号或工作空间下的调用凭证，具体模型在请求的 model 字段中指定；也可以在 Key 上限制可调用的模型或接入点。
同一个 Key 昨天能用，今天为什么 401？
常见原因包括：Key 被停用或轮换、Key 与接入点不在同一空间、接入点迁移、请求头缺少 Bearer、账号状态异常。先核对 Key 归属，再查请求头和工作空间。
模型 ID 和 ep- 开头的接入点 ID 应该填哪个？
预置推理填模型 ID；自定义接入点填 ep- ID；使用 Access Key 签名调用时必须填接入点 ID。若返回 ModelIDAccessDisabled，说明当前账号不支持模型 ID 直调，需要创建接入点。
Key 泄露了应该先做什么？
立即停用或删除泄露的 Key，新建替代 Key 并更新服务端配置，然后检查用量和日志。不要先追查泄露路径，避免配额被持续消耗。
