# 身份鉴权

> 使用 Bearer API Key 访问 Kerox 接口，并安全地轮换 Key。

## 使用 Bearer API Key

调用 `https://api.kerox.ai/v1` 时，在请求头中附带 `Authorization: Bearer <key>`：

```bash
curl https://api.kerox.ai/v1/account \
  -H "Authorization: Bearer $KEROX_API_KEY"
```
```python
import os
import requests

resp = requests.get(
    "https://api.kerox.ai/v1/account",
    headers={"Authorization": f"Bearer {os.environ['KEROX_API_KEY']}"},
    timeout=30,
)
print(resp.json())
```
```javascript
const res = await fetch('https://api.kerox.ai/v1/account', {
  headers: { Authorization: `Bearer ${process.env.KEROX_API_KEY}` },
});
console.log(await res.json());
```

`GET /v1/models` 和 `GET /v1/models/{id}` 可以不带 Key 访问（返回公开价格和参数 schema）。带上 Key 后会返回你账户的实际折后价格（单模型折扣优先于账户折扣）。

## Key 的安全与轮换

- **仅存哈希**：Kerox 服务端只保存 Key 的哈希，完整的 Key 只在[控制台 → API → API Keys](/console/api-keys)创建时显示一次。
- **仅限服务端调用**：请勿把正式 API Key 写进前端页面或客户端安装包。
- **平滑轮换**：先新建一把新 Key 并发布到线上，在控制台确认新 Key 已有正常流量后，再吊销旧 Key。吊销后的 Key 会返回 HTTP `401`（`invalid_api_key`），最多约一分钟后在所有服务器上生效。

## 提交任务的前提条件

调用 `POST /v1/tasks` 提交生成任务前，账户需满足以下条件：

1. 邮箱已验证：用邮箱验证码或 Google 登录过即已验证（否则返回 HTTP `403` `email_not_verified`）。
2. 账户状态正常未被停用（否则返回 HTTP `403` `account_disabled`）。
3. 钱包可用余额不低于本次任务的预估费用（否则返回 HTTP `402` `insufficient_balance`）。
