*更新日期: 2026-11-07*

# 鉴权与限流

所有 `/v1` 请求都要带：

```http
Authorization: Bearer sk_live_...
Content-Type: application/json
```

SSE 对话请求同样带 JSON body 和 Bearer；响应才是 `text/event-stream`。

Key 无效、已吊销、或所属租户停用，一律 `401` + `invalid_api_key`。不要依赖 `OpenAI-Organization`，该请求头会被忽略。

> **不要把 Key 放进浏览器**
>
> 客户集成走服务端 SDK 或后端转发。CORS 面向管理台；请勿从任意前端域名直连 `/v1`。

## 额度

租户余额 ≤ 0 时，**非 GET** 请求返回 `429` + `insufficient_quota`。列模型、查询任务（`GET /v1/tasks/{id}`）、查询余额（`GET /v1/balance`）仍可访问。

`GET /v1/balance` 返回当前这把 Key 还能花的余额。主账户 Key 是租户余额；子账户 Key 是该子账户额度，看不到主账户余额。进行中的占用已经从返回值里扣掉。`balance` 固定两位小数并向下取整，账上仍按最多 6 位小数判断能否发起生成。字段、示例和 `0.009` 显示成 `"0.00"` 的情况见 [计费与产物](/docs/usage)。

充值记在租户上，不按 Key 分账。子账户额度由主账户划拨。

## 限流

按 **Key × 能力 × 自然分钟** 计数。默认（可被运营改成 Key 自己的 RPM，空则继承租户）：

| 能力 | 默认 RPM | 作用接口 |
|------|----------|----------|
| chat | 120 | `POST /v1/chat/completions`、`POST /v1/responses` |
| image | 60 | `POST /v1/images/generations` |
| video | 20 | `POST /v1/videos` |

`GET /v1/models`、`GET /v1/balance` 与任务查询（`GET /v1/tasks/{id}` 及其别名）不走这套 RPM。子账户管理（`/v1/sub-accounts`）使用单独的 management RPM（默认 60），且必须用**主账户** API Key；详见 [子账户](/docs/sub-accounts)。触发 chat/image/video 限流后 HTTP `429`：

```json
{
  "error": {
    "message": "触发限流",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}
```

`insufficient_quota` 同样是 `429`、`type` 为 `rate_limit_error`，用 `code` 区分。响应**不包含** `Retry-After`；限流等到下一自然分钟，余额不足等充值。

## 探针

**GET** `/healthz`

无需鉴权，不在 `/v1` 下。正常返回 `{ "status": "ok" }`。负载均衡探活用这个，不要拿带 Key 的生成接口探活。
