跳到主要内容

API Key 与鉴权问题

API 密钥（API Key）是调用 Bita API 的身份凭证。遇到鉴权失败时，先确认使用了正确的密钥，再检查当前接口协议要求的请求头、密钥状态和权限。

API 密钥和登录密码有什么区别？​

两者用途不同：

凭据用途使用位置
登录密码登录 Bita API 网站和控制台登录页面
API 密钥通过代码、SDK 或第三方工具调用模型API 请求头、SDK 配置或环境变量

登录密码不能作为 API 密钥调用接口。请在控制台的「API 密钥」页面创建密钥，具体步骤参见创建 API 密钥。

不要使用其他平台的密钥

即使使用 OpenAI、Anthropic 或 Gemini 兼容 SDK，请求发送到 Bita API 时也必须填写 Bita API 控制台创建的密钥，不能填写原厂平台或其他中转服务的密钥。

不同接口应该怎样鉴权？​

接口协议Base URL推荐鉴权请求头
OpenAI 兼容https://www.bita-api.com/v1Authorization: Bearer YOUR_BITA_API_KEY
Anthropic 兼容https://www.bita-api.comx-api-key: YOUR_BITA_API_KEY
Gemini 兼容https://www.bita-api.comx-goog-api-key: YOUR_BITA_API_KEY

Anthropic Messages 请求还需要携带协议版本：

anthropic-version: 2023-06-01

Bita API 的 Anthropic 兼容接口也支持 Bearer 方式，但使用 Anthropic SDK 时建议沿用 x-api-key。不要在同一个客户端中同时配置多份不同的密钥，否则可能难以判断实际发送了哪一份凭据。

完整的地址和请求头说明参见 Base URL 与身份验证。

如何验证密钥是否可用？​

先使用最小请求查询模型列表。这样可以把密钥或地址问题与对话参数问题分开排查。

OpenAI 兼容接口​

curl -i "https://www.bita-api.com/v1/models" \
  -H "Authorization: Bearer $BITA_API_KEY"

Anthropic 兼容接口​

curl -i "https://www.bita-api.com/v1/models" \
  -H "x-api-key: $BITA_API_KEY" \
  -H "anthropic-version: 2023-06-01"

Gemini 兼容接口​

curl -i "https://www.bita-api.com/v1beta/models" \
  -H "x-goog-api-key: $BITA_API_KEY"

预期结果是返回 200 和模型列表。密钥可用但列表中没有目标模型时，通常应检查密钥分组和模型范围，而不是继续修改鉴权请求头。

先确认环境变量已经设置

上面的示例从 BITA_API_KEY 环境变量读取密钥。如果变量为空，请先在当前终端中设置；修改环境变量后，已经运行的 SDK、编辑器或第三方工具通常需要重启才能读取新值。

为什么返回 401 Unauthorized？​

401 表示请求没有通过身份验证。按顺序检查：

  1. 请求中是否真的携带了密钥：配置文件中存在密钥，不代表运行中的进程已经读取它。
  2. 密钥是否完整：重新从控制台复制，检查是否被聊天工具截断，或包含换行、引号和首尾空格。
  3. 请求头名称是否正确：OpenAI 使用 Authorization，Anthropic 使用 x-api-key，Gemini 使用 x-goog-api-key。
  4. Bearer 格式是否正确：应为 Bearer、一个半角空格、完整密钥；不要只发送密钥值。
  5. 域名是否正确：确认请求实际发送到 www.bita-api.com，而不是其他平台或旧代理地址。
  6. 是否使用了旧密钥：检查环境变量、.env、系统凭据、SDK 参数和第三方工具配置，确认没有旧值覆盖新值。

正确与错误的 Bearer 示例：

# 正确
Authorization: Bearer YOUR_BITA_API_KEY

# 错误：缺少 Bearer
Authorization: YOUR_BITA_API_KEY

# 错误：Bearer 后缺少空格
Authorization: BearerYOUR_BITA_API_KEY

如果最小 cURL 请求成功，而 SDK 或第三方工具仍返回 401，说明密钥本身通常没有问题，应重点检查该工具的配置来源和实际请求地址。

为什么返回 403 Forbidden？​

403 通常表示密钥已经被识别，但当前调用不被允许。检查：

  • 密钥是否处于已启用状态。
  • 密钥是否已经超过有效期。
  • 密钥自身的独立额度是否已耗尽。
  • 账户余额是否充足。
  • 密钥所属分组是否支持目标模型。
  • 密钥的模型范围是否包含目标模型。
  • 工具使用的接口类型是否与目标模型匹配。

密钥显示“无限额度”只表示没有单独的密钥额度上限，不代表账户余额无限，也不代表可以调用所有分组和模型。详细规则参见 API 密钥权限与额度限制。

为什么密钥之前可用，现在失效了？​

密钥值没有变化，也可能因为其他条件改变而无法调用：

现象建议检查
所有接口突然返回 401密钥是否被删除，客户端是否改用了错误或不完整的值
所有模型返回 403密钥状态、有效期、独立额度和账户余额
只有一个模型失败模型 ID、分组、模型范围和渠道可用状态
修改分组后失败新分组是否支持原模型，客户端是否需要刷新模型列表
更换密钥后仍使用旧密钥服务、终端、编辑器或容器是否已重新加载配置

可以在控制台查看用量与调用日志，确认请求是否到达 Bita API、使用了哪个模型以及返回了什么错误。

为什么控制台复制的密钥仍然无效？​

复制过程和配置层级经常会引入问题：

  • .env 文件中把注释、中文标点或多余空格一起写入了值。
  • 从富文本或聊天软件复制时带入了不可见换行。
  • Docker、进程管理器或编辑器仍使用启动时读取的旧环境变量。
  • SDK 构造函数中的 apiKey 覆盖了环境变量。
  • shell 配置文件、项目级 .env 和系统环境变量存在同名配置。
  • 第三方工具分别保存了“全局提供商”和“当前模型”的两份凭据。

排查时不要把完整密钥打印到终端或日志。可以只确认变量是否为空：

if [ -n "$BITA_API_KEY" ]; then
  echo "BITA_API_KEY 已设置"
else
  echo "BITA_API_KEY 为空"
fi

然后使用本页的最小 cURL 请求验证。如果 cURL 成功，再逐层检查应用配置。

可以把密钥写在代码里吗？​

不建议。服务端项目应通过环境变量或密钥管理服务读取：

import os

api_key = os.environ["BITA_API_KEY"]
const apiKey = process.env.BITA_API_KEY;

同时注意：

  • 不要把 .env、配置文件或调试日志提交到 Git。
  • 不要在前端 JavaScript、网页源码、浏览器扩展或移动应用安装包中内置密钥。
  • 浏览器应用应调用你自己的服务端，由服务端安全地调用 Bita API。
  • CI/CD 中使用平台提供的 Secret 功能，并限制可以读取密钥的任务和成员。
  • 生产、测试和本地开发使用不同密钥。

多个应用可以共用一枚密钥吗？​

技术上可以，但不推荐。为每个项目、工具、设备或成员创建独立密钥有以下好处：

  • 可以单独设置额度和有效期。
  • 可以从日志区分用量来源。
  • 某个客户端泄露时只需轮换对应密钥。
  • 可以为不同模型选择合适的分组和权限。

密钥名称应体现用途，例如 production-api、Claude Code 或 team-alice，不要使用难以区分的通用名称。

密钥泄露后怎么办？​

只从代码或聊天记录中删除密钥是不够的；已经暴露的密钥值应视为不再安全：

  1. 立即在控制台停用旧密钥，阻止继续调用。
  2. 查看使用日志和余额，确认是否存在异常请求或消耗。
  3. 创建分组、模型范围、额度和有效期正确的新密钥。
  4. 更新所有合法客户端并重启相关进程。
  5. 使用最小请求验证新密钥，再删除旧密钥。
  6. 如果密钥进入了 Git 历史，还应清理历史并检查其他可访问的副本；但无论是否清理成功，都必须轮换密钥。

完整操作参见管理 API 密钥：密钥泄露后的处理。

反馈鉴权问题时提供什么？​

可以提供：

  • 请求时间和时区。
  • 接口协议、Base URL 和完整路径。
  • HTTP 状态码和完整错误消息。
  • 使用的 SDK 或第三方工具名称及版本。
  • 密钥名称、所属分组和状态。
  • 已脱敏的请求示例，以及问题是否能通过最小 cURL 请求复现。

不要提供完整 API 密钥、登录密码、Authorization 请求头或包含密钥的截图。需要继续按状态码排查时，参见常见错误码。