鉴权

Sakrylle API 支持两类凭证：

• 手动 API Key：sk-xxxxxxxxxxxxxxxx
• OAuth access token：sk_oauth_xxxxxxxxxxxxxxxx

两者都通过 HTTP 请求头传递。不要把凭证放进 query string。

手动 API Key

支持的请求头

方式	示例	说明
Authorization: Bearer	Authorization: Bearer sk-xxxxxxxxxxxxxxxx	默认推荐写法
x-api-key	x-api-key: sk-xxxxxxxxxxxxxxxx	兼容部分 Anthropic 风格客户端
x-goog-api-key	x-goog-api-key: sk-xxxxxxxxxxxxxxxx	兼容 Google-style header 的客户端

WARNING

同一个请求只发送一种鉴权头即可，不要混发多种头。

创建 API Key

1. 登录 控制台。
2. 进入 API Keys 页面。
3. 点击 新建 API Key，可选填写备注。
4. 复制以 sk- 开头的字符串并妥善保存。

验证 Key 是否有效

最简单的探活方式是 GET /v1/models：

curl https://api.sakrylle.com/v1/models \
  -H "Authorization: Bearer $SAKRYLLE_API_KEY"

OAuth access token

OAuth token 推荐统一使用 Authorization: Bearer：

Authorization: Bearer sk_oauth_xxxxxxxxxxxxxxxx

OAuth token 的权限由 scope 控制。本文档里最常见的几个 scope：

Scope	用途
profile:read	读取 /v1/me.user
account:read	读取 /v1/me.account、current_group、allowed_groups 等账户视图
account:balance:read	读取余额字段

按请求切换分组

OAuth token 可以在 model 中使用数值分组前缀：

curl https://api.sakrylle.com/v1/chat/completions \
  -H "Authorization: Bearer sk_oauth_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "3:gpt-5.6-sol",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

格式固定为 <group_id>:<model>。这里的 group_id 是数值 ID，不是字符串别名。

如果 model 不带前缀，则使用该 OAuth token 当前绑定的默认分组。

列出所有已授权分组的模型

curl "https://api.sakrylle.com/v1/models?groups=all" \
  -H "Authorization: Bearer sk_oauth_xxxxxxxxxxxxxxxx"

这个查询参数只对 OAuth token 生效；手动 API Key 会忽略它。

详见 Models API。

已弃用：query 参数传 key

通过 URL 查询参数 ?key=... 或 ?api_key=... 传 key 已弃用，网关会返回 400：

{
  "error": {
    "message": "Passing API key via query parameter is not supported. Use the Authorization header instead.",
    "type": "invalid_request_error",
    "code": "api_key_in_query_deprecated"
  }
}

安全建议

WARNING

API Key 等同于密码：任何拿到它的人都可以使用你的额度。

• 把 key 放进环境变量：

  export SAKRYLLE_API_KEY=sk-xxxxxxxxxxxxxxxx

• 开发、测试、生产分别使用不同 key。
• 泄露后立刻在控制台撤销并重建。
• 不要把 key 硬编码到浏览器端或移动端应用中。
• 不要在公开 issue、截图、日志里暴露完整 key。

鉴权失败的常见错误

状态码	含义	常见原因
401 Unauthorized	缺鉴权头、key 无效、token 过期	Bearer 前缀漏写、key 拼错、OAuth token 失效
403 Forbidden	key/token 有效，但当前分组或 scope 不允许访问	分组未开放该模型、OAuth scope 不足
402 类错误	余额或额度不足	钱包余额不足、订阅已到期
429 Too Many Requests	触发限流	并发过高、多个客户端共享一个 key

完整对照见 错误码。