跳到主要内容

鉴权

两种 key，别搞混​

类型用途位置
API 令牌（sk-）调用 /v1 等模型接口请求头
PANEL PAT调用管理接口请求头

普通使用只需要 API 令牌。面板 PAT 是给自动化脚本管后台用的。

API 令牌的三种传法​

# 1. OpenAI 风格（推荐）
Authorization: Bearer ***

# 2. Anthropic 风格
x-api-key: ***
anthropic-version: 2023-06-01

# 3. Gemini 风格
x-goog-api-key: ***
# 或查询参数
?key=***
多种头同时带时，以 Bearer 为准

平台同时兼容 Authorization: Bearer、x-api-key、x-goog-api-key、?key= 四种鉴权头， 按你使用的 SDK 习惯填即可。同时带多个头时以 Authorization: Bearer 优先。

协议自适应

/v1/models 会根据你带的头决定返回哪种格式的模型列表： 带 x-api-key + anthropic-version 返回 Anthropic 形态，带 x-goog-api-key 返回 Gemini 形态，否则返回 OpenAI 形态。

IP 白名单​

每把令牌都可以设置 IP 白名单（单个 IP 或 CIDR 网段），在控制台令牌的「IP 白名单」字段里填。

设置后，名单外的来源调用会返回 403：

{
  "error": {
    "code": "ip_not_allowed",
    "message": "..."
  }
}

报错信息里会带着平台看到的来源 IP，并且不扣费。把该 IP 加进白名单，或清空白名单即可恢复。

提示

这是给服务端调用加锁的推荐做法 —— 即使 key 泄露，攻击者的 IP 也拿不到额度。 生产 key 建议必设。

面板接口（PAT）​

管理后台的自动化调用使用：

Authorization: Bearer <pat>

也兼容单值写法 Authorization: <pat>。

注意

PAT 不接受 URL 参数传递。不要再带 New-Api-User 头——新版鉴权已经 不用它了，带上会被忽略。

登录会话（浏览器）​

如果你在做前端集成：

项说明
Access TokenJWT，15 分钟有效，只存内存
Refresh Token随机不透明值，最长 30 天，HttpOnly Cookie
Refresh 路径/api/user/auth，SameSite=Strict

new_api_has_session 只是"是否签发过 Refresh Cookie"的提示位， 不含任何凭据，也不参与鉴权判定。

安全建议​

  1. 每个环境一把独立 key。
  2. 生产 key 设过期时间，定期轮换。
  3. 服务器调用填 IP 白名单（见上），名单外来源直接 403 且不扣费。
  4. key 泄露立刻禁用，不要试图"改密码保住它"。
  5. key 不要写进前端代码、公开仓库或聊天截图。