鉴权

所有请求都通过 API Key 鉴权。在控制台创建 Key,在请求头里带上它,即可调用任意已开通的模型。

获取 API Key

在控制台签发并管理你的 Key:

• 控制台:https://swato.ai/login

Key 形如 sk-...。妥善保存,它等同于你的账户凭证。

在请求中携带 Key

不同协议面用不同的请求头。

OpenAI 兼容面与 Anthropic 兼容面都使用标准的 Authorization: Bearer 头:

Authorization: Bearer sk-...

Gemini 原生面(/v1beta)沿用 Gemini 自己的约定,使用 x-goog-api-key 头,或 ?key= 查询参数:

x-goog-api-key: sk-...

GET /v1beta/models?key=sk-...

curl 示例

向 OpenAI 兼容面发送一次带 Bearer 头的请求:

curl https://swato.ai/v1/chat/completions \
  -H "Authorization: Bearer $SWATO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<见 GET /v1/models 获取确切 id>",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Gemini 原生面对应的写法:

curl "https://swato.ai/v1beta/models/<model>:generateContent" \
  -H "x-goog-api-key: $SWATO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Hello"}]}]
  }'

Key、分组与平台

这是理解鉴权行为的关键模型,请仔细阅读。

每个 API Key 都属于一个分组(group),每个分组绑定一个平台(platform):OpenAI / Anthropic / Google。平台决定了这个 Key 能用哪些端点。 同一个端点会按你所用 Key 的分组平台自动选路,因此你走哪条协议面,取决于你拿哪个 Key 去调用。

Key 分组平台	可用协议面	典型端点
OpenAI	OpenAI 兼容	/v1/chat/completions、/v1/responses、/v1/images/generations、/v1/images/edits
Anthropic	Anthropic 兼容	/v1/messages、/v1/messages/count_tokens
Google	Gemini 原生	/v1beta/models/{model}:{action}

跨平台调用会失败。例如:图片端点(/v1/images/generations、/v1/images/edits)只对 OpenAI 平台的分组开放;用一个非 OpenAI 分组的 Key 去打这些端点,会得到 404。

GET /v1/models 与 GET /v1/usage 为各平台共享。要确认你的 Key 实际能调用哪些模型,以 GET /v1/models 的返回为准。

TIP

关于按 Key 分组平台自动选路、上游故障如何回退,详见 路由与回退。

安全实践

• 用环境变量保存 Key,不要把 sk-... 硬编码进源码。
• 不要提交进版本库,也不要随客户端代码下发(浏览器、移动端、桌面端都不行)。Key 一旦暴露应立即在控制台轮换。
• 给不同用途的应用配置不同的 Key,便于按用途追踪与吊销。
• 通过你自己的后端代理这些请求,Key 只留在服务端。

# 从环境读取,不要写死在代码里
export SWATO_API_KEY="sk-..."

鉴权失败

缺失或无效的 Key 会返回 401 Unauthorized,响应体大致如下:

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

收到 401 时,请检查:Key 是否拼写完整、是否已在控制台被吊销、以及请求头是否用对了(OpenAI/Anthropic 面用 Authorization: Bearer,Gemini 原生面用 x-goog-api-key)。