跳到主要内容

鉴权方式

鉴权，简单说就是让服务器确认「这个请求是谁发的、有没有权限」。这页不讲抽象授权模型，只讲用户最常碰到的两个问题：

  1. API 到底该用什么 token
  2. 为什么我明明有 token，还是 401 或 403

先说结论​

  • 调 API 时，默认使用 Bearer Token（Bearer 是把令牌放进 Authorization 请求头的标准写法）
  • 控制台登录状态不等于 API 可用
  • 401 更常见于 token 本身有问题
  • 403 先查额度（令牌或账户额度是否用尽），再查策略（分组、模型权限或来源限制）

API 默认怎么传​

彼源 AI 的 API 密钥是一串以 sk- 开头的令牌。默认放在 Authorization 请求头（随请求一起附带的说明信息）里：

Authorization: Bearer sk-...

curl、SDK、客户端或自部署前端，本质上都是把这个值放进请求。

除了默认的 Bearer，彼源 AI 还兼容另外两种传法，方便你直接对接对应协议的 SDK：

  • Anthropic 协议：用 x-api-key: sk-...，并带上 anthropic-version 请求头。
  • Gemini 协议：用 x-goog-api-key: sk-...，或在地址后加 ?key=sk-...。

拿不准用哪种，就用默认的 Bearer，兼容性最好。

什么不是 API 鉴权​

很多人第一次会把下面几件事混在一起：

  • 控制台登录
  • API token
  • 某个客户端本地缓存的 key

要分清：

  • 控制台登录，是你进入网页工作台的身份
  • API token，是程序、客户端和脚本真正调用模型时用的凭证

控制台能登录，不代表 API 一定通。
API 通，也不代表你控制台里一定配对了当前那把 token。

最小验证方式​

最稳的做法永远是先跑：

curl https://api.biyuan.ai/v1/models \
  -H "Authorization: Bearer <YOUR_TOKEN>"

这一步至少能验证：

  • Base URL 是不是对的
  • token 有没有生效
  • 当前 token 大致能看到哪些模型

不想用命令行的话：登录控制台，在操练场选同一个模型发一句话，能收到回复就说明账号、令牌和额度都正常，问题多半出在客户端配置。

401 和 403 的区别​

一句话记住：

  • 401 先查令牌——多半是没带、复制不全、过期或已停用。
  • 403 先查额度，再查策略——先看错误文案：额度类（「该令牌额度已用尽」「用户额度不足」）先处理额度；策略类再查分组、模型权限或来源（IP）限制。

每种报错的真实返回文案和对应解决办法，见错误与状态码。

令牌应该怎么用才安全​

最推荐的方式不是「一个大 token 到处复用」，而是：

  • 一个客户端一个 token
  • 一个服务一个 token
  • 一个环境一个 token

这样做的好处是：

  • 泄露时影响面更小
  • 审计更清晰
  • 排障更快

令牌泄露后怎么办​

建议顺序：

  1. 先停用或轮换可疑 token
  2. 再到控制台「使用日志」查看最近的请求，确认有没有异常调用
  3. 再决定是否新建一个限制更严的令牌（收紧模型权限、分组或来源限制），替换旧令牌

不要在已经怀疑泄露的情况下还继续长期保留旧 token。

令牌轮换建议​

按用途来看更稳：

  • 临时测试：短有效期
  • 桌面客户端：定期轮换
  • 生产服务：独立 token + 轮换流程

如果你已经把 token 发给了不该长期保留的地方，那就不要犹豫，直接换。

模型限制和来源限制什么时候会生效​

模型限制​

当 token 只被允许访问部分模型时，客户端即使拿到了 token，也不代表它能调用所有模型。

来源限制​

如果平台或 token 配了 IP / 来源限制，那么：

  • 在允许来源内：正常
  • 在不允许来源内：通常会报 403

以下场景最容易出现这类问题：

  • 本地开发时切换了网络
  • 在办公室和家里之间切换
  • 部署环境发生变更

常见问题​

我明明复制了 token，为什么还是 401​

优先检查：

  • token 前后有没有多空格
  • 客户端是不是还缓存旧值
  • 有没有漏掉 Bearer

我能看到模型，但一调用就 403​

优先检查：

  • 令牌或账户额度是否用尽（去控制台「钱包管理」和令牌列表看）
  • 当前模型是否真的在 token 权限范围内
  • 当前分组是否允许该模型完整调用
  • 当前来源是否被限制

为什么网页能进，API 却不行​

因为这根本就是两套路径：

  • 网页依赖登录会话
  • API 依赖 Bearer Token

推荐动作​

如果你现在正在排查鉴权问题，最省时间的顺序是：

  1. 先确认 Base URL
  2. 先确认 Bearer Token
  3. 跑 GET /v1/models
  4. 再发最小 chat/completions
  5. 最后再回具体客户端排查

下一步​