认证

所有接口都用同一把 sk- 开头的 API Key。区别只在于凭据放在哪个请求头里。

三种写法

网关在所有协议上都接受 Authorization: Bearer，另外在特定路径上兼容各生态的原生写法。

写法	生效路径	示例
Authorization: Bearer <key>	全部	Authorization: Bearer sk-xxxxxx
x-api-key: <key>	/v1/messages、/v1/models	Anthropic SDK 的默认写法
x-goog-api-key: <key>	/v1beta/models*、/v1/models	Google GenAI SDK 的默认写法
?key=<key> 查询参数	/v1beta/models*、/v1/models	Gemini 的查询参数写法

三种写法等价，不需要同时提供。

# OpenAI 兼容
curl https://ai.roibest.com/v1/chat/completions \
  -H "Authorization: Bearer $ROIBEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-model","messages":[{"role":"user","content":"hello"}]}'

# Anthropic 兼容
curl https://ai.roibest.com/v1/messages \
  -H "x-api-key: $ROIBEST_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-model","max_tokens":64,"messages":[{"role":"user","content":"hello"}]}'

# Gemini 兼容
curl "https://ai.roibest.com/v1beta/models/your-model:generateContent" \
  -H "x-goog-api-key: $ROIBEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"hello"}]}]}'

Realtime WebSocket

WebSocket 不能自定义请求头，凭据放在子协议里：

Sec-WebSocket-Protocol: realtime, openai-insecure-api-key.sk-xxxxxx, openai-beta.realtime-v1

密钥的权限边界

• 密钥属于一个服务分组，分组决定可调用的模型范围与计费口径。
• 密钥可设置额度上限和有效期，超出后请求被拒绝。
• 密钥可设置 IP 允许列表。设置后，来自列表之外的 IP 返回 403，提示 IP 不在令牌允许访问的列表中。

验证

curl -i https://ai.roibest.com/v1/models \
  -H "Authorization: Bearer $ROIBEST_API_KEY"

返回 200 且响应体含 data 数组即认证成功。返回 401 见错误码。

常见问题

能不能把密钥放在查询参数里给 OpenAI 接口用？ 不能。?key= 只在 Gemini 相关路径和 /v1/models 上生效。

Authorization 里要不要保留 sk- 前缀？ 保留即可，网关会自行处理。

面板的 Personal Access Token 能调用这些接口吗？ 不能。面板 PAT 用于管理接口，模型接口只接受 sk- 密钥。