认证与 API Key
一套 sk-swx- 开头的 Key 覆盖所有 /v1/* 接口。本章讲生命周期、权限作用域、安全最佳实践。
请求头格式
所有调用（除登录注册）都必须携带 Bearer Token：
http
Authorization: Bearer sk-swx-xxxxxxxxxxxxxxxxxxxxxxxxxxxx如果使用 OpenAI SDK 等成熟库，只需把 api_key 设为 Key 原文，header 会自动带上。
Key 的生命周期
创建
在 Console → API Keys → 新建。创建时可选配置：
| 字段 | 说明 | 默认 |
|---|---|---|
name | Key 标签，仅用于自己识别，比如 "prod-backend" | 必填 |
note | Key 备注，仅用于在控制台识别场景，不参与权限判断 | 空 |
rate_limit_per_minute | 该 Key 独立的 RPM 上限（0 = 使用系统默认值） | 0 |
expires_at | 过期时间戳，到期自动失效 | 永不过期 |
查看 / 重新创建
完整 Key 只在创建成功的瞬间返回一次。之后 UI 里只显示脱敏前缀，平台不会再提供客户 API Key 原文查看接口。忘记或怀疑泄露时，请删除旧 Key 并重新创建。
吊销
点删除按钮立即失效。吊销后：
- Redis 缓存 5 分钟内清理
- 使用该 Key 的在途请求不受影响（已通过认证）
- 吊销不可撤销，误删后只能重新创建
一把 Key 对应一个场景
生产 / 测试 / 本地开发各用独立的 Key。泄露后只吊销对应的一把，其他服务不受影响。 不要跨项目复用同一把 Key。
API Key 作用域
当前版本采用单账户计费与调用模型。API Key 主要承担调用和风控控制：
| 控制项 | 作用 | 建议 |
|---|---|---|
rate_limit_per_minute | 限制单把 Key 的每分钟请求数 | 按服务流量单独设置，避免误调用拖垮余额 |
tpm_limit / quota_monthly_tokens | 限制单把 Key 的每分钟 token 数和月 token 上限 | 按服务重要程度设置，避免异常调用持续消耗余额 |
budget_limit_cny | 限制单把 Key 的月预算 | 测试 Key 建议设置较低预算 |
expires_at | 设置 Key 自动过期时间 | 测试、临时联调 Key 必须设置过期时间 |
| 账户余额 | 所有调用最终从当前账户钱包扣费 | 用低余额告警控制预算风险 |
如需多人协作，现阶段建议为不同服务拆分 API Key，而不是共享同一把 Key。 审计日志会记录当前账号自身的登录、查看密钥、删除密钥和重要设置变更。
速率限制
两个维度同时生效，哪个先到就触发 429：
RPM（每分钟请求数）—— 按 Key 或系统默认值计TPM（每分钟 token 数）—— 按账户计
触发限流时当前返回 429 和 detail。不要依赖 X-RateLimit-*响应头作为生产逻辑；客户端应按 429 做指数退避。
http
HTTP/1.1 429 Too Many Requests
content-type: application/json
x-request-id: req_xxxx
{"detail": "Rate limit exceeded (600/min)"}SDK 客户端收到 429 应做指数退避；不要无脑立即重试。 推荐模式见 重试最佳实践。
Key 泄露怎么办
- 立即去 Console 删除该 Key —— 不要等"先确认一下"。删除 5 分钟内全球所有副本失效。
- 查审计日志（
Console → 审计日志）确认泄露窗口期内的异常请求 - 如果产生了异常扣款，发工单提供请求 ID 列表申诉
- 生成新 Key，在部署系统 / 密钥管理中滚动更新
常见错误
| HTTP | detail 示例 | 原因与修复 |
|---|---|---|
| 401 | Invalid API key | Key 拼错 / 已删除 / 已过期。重新生成。 |
| 401 | Missing API key | 没带 Authorization header，或 Bearer 前缀漏了。 |
| 403 | Model not available | 请求模型未上架、未授权、或未配置平台价格。请到模型列表确认。 |
| 402 | Insufficient wallet balance | 余额不足本次预扣。充值后自动恢复。 |