鉴权

每次访问 /v1/* 都需要带 API key。BUZZ 同时接受三种鉴权 header,所以 Anthropic、OpenAI、Google GenAI 三家官方 SDK 都能直接使用 —— 只要把 base URL 指到 https://buzzai.cc,原有鉴权代码不用改。

三种 header 写法

哪种顺手就用哪种,鉴权完成之后行为完全一致 —— 四种 header 解析到的都是同一把 key。

什么时候用哪种?

原则:跟着 SDK 的默认行为走,不要改 SDK 的请求层。

Anthropic SDK

官方 anthropic(Python)和 @anthropic-ai/sdk(Node)默认发 x-api-key。把 base URL 指到 BUZZ 即可:

from anthropic import Anthropic

client = Anthropic(
    base_url="https://buzzai.cc",
    api_key="",
)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://buzzai.cc",
  apiKey: process.env.BUZZ_API_KEY,
});

OpenAI SDK(走 /v1/chat/completions)

OpenAI SDK 默认发 Authorization: Bearer ...。配合 OpenAI 兼容的 /v1/chat/completions 路径使用:

from openai import OpenAI

client = OpenAI(
    base_url="https://buzzai.cc/v1",
    api_key="",
)

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "ping"}],
)

Google GenAI SDK

官方 google-genai SDK 默认发 x-goog-api-key。BUZZ 在 Gemini 兼容路径上识别这个 header,SDK 不改代码就能复用 BUZZ key 调网关上的 Gemini 兼容模型。

curl / 自写 HTTP 客户端

原始 HTTP 调用最省心的写法是 Authorization: Bearer —— 跟 BUZZ 其他 REST 接口(billing 等非 relay 端点)写法一致,代码风格统一。

curl -X POST https://buzzai.cc/v1/messages \
  -H "Authorization: Bearer $BUZZ_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{ "model": "claude-haiku-4-5-20251001", "max_tokens": 32, "messages": [{"role":"user","content":"ping"}] }'

SDK Header 速查表

API key 管理

Key 在用户后台 Tokens 页面管理。同样的操作可以通过 /api/token/* 用 session 或 access token 鉴权来做(注意:这里的 access token 与 sk- relay key 不是同一种鉴权)。

每把 key 可配置的字段

状态值

生命周期:创建 / 取出 / 轮换 / 删除

创建

用后台表单或 POST /api/token/ 创建 key。Key 由后端生成,创建接口本身不会回显完整值。要拿到完整 key,在后台点行内复制按钮,或调 POST /api/token/<id>/key。列表接口出于安全只返回 mask 形态,例如 OnyH**********esAm。

取出

把完整 key 当一次性密钥处理:复制一次,放进秘密管理器或环境变量,不要再贴回后台、聊天工具、文档。

轮换

轮换流程:新建一把 key → 部署到所有用旧 key 的位置 → 删旧 key。BUZZ 不支持原地刷新 key,只能"删一把建一把"。

删除

支持软删:DELETE /api/token/<id>。批量删除走 POST /api/token/batch,body 形如 {"ids":[1,2,3]}。

安全最佳实践

• 用环境变量,不要硬编码字面值。 启动时读 BUZZ_API_KEY(或你项目自己的命名)。绝不要把 key 贴进源码仓库、后台、截图、聊天工具。
• 只放在不入库的文件里。 安全位置:.env(必须 gitignore)、秘密管理器(AWS Secrets Manager、GCP Secret Manager、HashiCorp Vault)、CI/CD 的 secret store。
• 按服务 / 环境拆 key,不要一把通用。 每个服务、每个环境(dev / staging / prod)各发一把 key。一旦泄漏只影响一处,轮换成本也低。
• 能用 IP 白名单就用。 如果你的请求来自固定出口 IP(生产服务器、CI runner、NAT 网关),把 IP 写进 allow_ips。这相当于把"任何拿到 key 的人都能调"收敛成"白名单 IP 上拿到 key 的人才能调"。
• 高风险 key 加 model_limits。 例如限制只能用 claude-haiku-4-5-20251001,即使被滥用,单次调用成本也封顶。
• 给 key 设过期时间。 短期原型、demo、临时合作的 key 应该明确填 expired_time。-1 方便但容易忘。
• 定期轮换。 长期生产 key 至少每 90 天轮换一次;一旦怀疑泄漏(CI 日志、误推 commit、人员离职)立即轮换。
• 监控用量异常。 用 key 自身鉴权调 GET /api/usage/token/ 可读到剩余额度和最近用量。配告警监控突增。
• 泄漏时:先删,再排查。 后台软删立即生效。然后建新 key、重新部署,再去看日志复盘。

鉴权错误

BUZZ 网关侧错误响应包络:

{
  "error": {
    "type": "buzz_error",
    "message": "Invalid token... (request id: 202605260713594...)"
  }
}

Anthropic 透传错误保持官方原样,顶层带 request_id。

相关链接

• 快速接入 — 5 分钟跑通第一个调用。
• POST /v1/messages — 完整请求 / 响应参考。
• GET /api/token/ — 编程方式管理 key。
• 错误处理 — 重试策略与 BUZZ 特有的 503 场景。