身份鉴权
使用 Bearer API Key 访问 Kerox 接口,并安全地轮换 Key。
使用 Bearer API Key
调用 https://api.kerox.ai/v1 时,在请求头中附带 Authorization: Bearer <key>:
curl https://api.kerox.ai/v1/account \
-H "Authorization: Bearer $KEROX_API_KEY"GET /v1/models 和 GET /v1/models/{id} 可以不带 Key 访问(返回公开价格和参数 schema)。带上 Key 后会返回你账户的实际折后价格(单模型折扣优先于账户折扣)。
Key 的安全与轮换
- 仅存哈希:Kerox 服务端只保存 Key 的哈希,完整的 Key 只在控制台 → API → API Keys创建时显示一次。
- 仅限服务端调用:请勿把正式 API Key 写进前端页面或客户端安装包。
- 平滑轮换:先新建一把新 Key 并发布到线上,在控制台确认新 Key 已有正常流量后,再吊销旧 Key。吊销后的 Key 会返回 HTTP
401(invalid_api_key),最多约一分钟后在所有服务器上生效。
提交任务的前提条件
调用 POST /v1/tasks 提交生成任务前,账户需满足以下条件:
- 邮箱已验证:用邮箱验证码或 Google 登录过即已验证(否则返回 HTTP
403email_not_verified)。 - 账户状态正常未被停用(否则返回 HTTP
403account_disabled)。 - 钱包可用余额不低于本次任务的预估费用(否则返回 HTTP
402insufficient_balance)。