认证
所有请求都用 ThetaIO API Key 认证。网关接受三种请求头,按协议习惯任选一种。
请求头
| 请求头 | 格式 | 常见于 |
|---|---|---|
Authorization | Bearer sk-... | OpenAI SDK、Codex CLI |
x-api-key | sk-... | Anthropic SDK、Claude Code |
x-goog-api-key | sk-... | Gemini SDK、Gemini CLI |
bash
curl https://api.thetaio.tech/v1/models \
-H "Authorization: Bearer $THETAIO_API_KEY"bash
curl https://api.thetaio.tech/v1/models \
-H "x-api-key: $THETAIO_API_KEY"bash
curl https://api.thetaio.tech/v1beta/models \
-H "x-goog-api-key: $THETAIO_API_KEY"查询参数
/v1 下的接口不接受把 Key 放在 URL 查询参数里,传 ?key= 或 ?api_key= 会返回 400 api_key_in_query_deprecated。
Gemini 原生接口 /v1beta/* 为兼容 Google 客户端,仍接受 ?key=。优先使用请求头:URL 会出现在代理日志和浏览器历史里。
Key 的状态
| 状态 | 表现 |
|---|---|
| 正常 | 请求放行 |
| 已禁用 | 401 API_KEY_DISABLED |
| 已过期 | 403 API_KEY_EXPIRED |
| 额度耗尽 | 请求被拒绝,GET /v1/usage 仍可查询 |
| 未分配分组 | 请求被拒绝,需要在控制台给 Key 选择分组 |
安全建议
- 每个应用、每个环境使用独立的 Key,并给它设置额度上限。
- Key 只放在服务端或本机环境变量中,不要下发到浏览器或移动端。
- 连续使用无效 Key 会触发限流,返回
429 INVALID_AUTH_RATE_LIMITED,稍后再试。