> For AI agents: the complete documentation index is available at https://docs.reelway.ai/llms.txt, the full documentation bundle is available at https://docs.reelway.ai/llms-full.txt.

# API Keys

API Key 让你的代码代表你的 Reelway 账户行动。每个账户最多同时持有 **99 把在用的 Key**,每把有自己的名称与用量,因此每个应用、智能体、服务器或节点车队都可以拥有独立的 Key;吊销其中一把,其余不受影响。

在[控制台 → API Keys](https://dashboard.reelway.ai/console/keys)页面管理 Key(需登录会话)。只有登录会话可以创建或吊销 Key;**API Key 本身不能管理 Key,包括它自己**。

## Key 的两类

| 类型        | 说明                                                                       |
| --------- | ------------------------------------------------------------------------ |
| **主 Key** | 每个账户自动持有一把。可随时在控制台**再次查看与复制**明文;不可吊销(吊销请求返回 404 语义)。适合个人开发与控制台内的快捷调用     |
| **子 Key** | 通过「创建 Key」按钮生成。明文**仅在创建时弹窗显示一次**,之后无法再取回;可随时吊销。生产环境、智能体、节点与第三方集成请使用子 Key |

已吊销的 Key 仍保留在列表中(带吊销标记)便于审计,但不再占用 99 把的在用配额。

:::tip 节点请使用独立 Key
GPU 节点(worker)在 WebSocket 握手时同样使用账户 API Key。为每台节点或每个车队单独创建一把子 Key,便于按节点吊销与排障。连接前可用 `POST /v1/client/key` 预检 Key 是否有效(见[节点协议](https://docs.reelway.ai/run-a-worker/worker-protocol.md))。
:::

## 创建 Key


### 登录控制台
前往 [reelway.ai/console/keys](https://dashboard.reelway.ai/console/keys)。登录由 `auth.reelway.ai` 统一鉴权完成。
### 创建并命名
点击「创建 Key」,填写名称(建议以用途命名,如 `agent-prod`、`worker-5090-01`)。
### 立即保存明文
Key 明文仅显示一次。立即放入密钥管理器或环境变量;关闭弹窗后只能重新创建。

## 发送 Key

在请求头中发送 Key,**绝不要放在 URL 里**:

```bash
curl --fail-with-body https://rcn.reelway.ai/v4/account/balance \
  -H "api-key: $REELWAY_API_KEY"
```

REST 端点接受 `api-key: <key>` 或 `Authorization: Bearer <key>` 两种写法;OpenAI 兼容推理面(`api.reelway.ai/v1`)推荐 `Authorization: Bearer`,以便与 OpenAI SDK 的默认行为一致。`@reelway/client` SDK 以 `apiKey` 参数接收 Key 并代为放入请求头与 WebSocket 握手头。

URL 会进入浏览器历史、代理日志与分析系统,因此 WebSocket 连接也请使用 `api-key` **握手头**而非 `?apiKey=` 查询串。

把 Key 留在服务端。不要放进浏览器打包产物、移动端二进制、提示词、代码仓库、截图或支持消息。

## 限额与用量

- **单 Key 限额**:平台可为 Key 设置消费配额;提交的预估费用超过剩余配额时,请求在扣费前被拒绝,返回 `402`(错误码 `1013`),与账户余额不足(`1005`)区分。
- **用量查看**:控制台的 Key 列表展示每把 Key 的用量;账户维度的余额与流水见[余额与用量](https://docs.reelway.ai/api-reference/account-and-usage.md)。
- Key 的限额与用量仅在控制台可见;API Key 自身不能读取这些信息。

:::info 当前未提供的能力
按 Key 的模型白名单、IP 白名单、到期时间与暂停/恢复,当前版本**未提供**。需要隔离时请使用独立的子 Key 并按需吊销。
:::

## 吊销与轮换

- **吊销**是永久的。Key 立即失效,使用它的 SDK 会话与节点连接在下一次鉴权时被拒绝(WebSocket 关闭码 `4021`)。其余 Key 不受影响。
- **轮换**采用「先建后吊」:创建新 Key → 部署到使用处 → 确认流量切换 → 吊销旧 Key。两把 Key 并存期间没有数量之外的限制。

**如果 Key 泄露**,立即吊销,创建新 Key 替换,然后在控制台检查该 Key 的用量是否存在陌生记录。

## 错误

| 场景              | HTTP | 错误码    | 说明                                                          |
| --------------- | ---- | ------ | ----------------------------------------------------------- |
| Key 缺失、格式错误、已吊销 | 401  | `101`  | 响应信封 `message` 说明原因;WebSocket 以 `4021` 关闭                   |
| 单 Key 限额触顶      | 402  | `1013` | 调整限额或换用其他 Key                                               |
| 账户余额不足          | 402  | `1005` | 与 Key 无关,见[方案与定价](https://docs.reelway.ai/pricing/index.md) |

OpenAI 兼容推理面上,鉴权失败返回 OpenAI 形状的 `401` 错误对象(`error.type` / `error.message`),而非标准信封。

另见[快速开始](https://docs.reelway.ai/api-reference/getting-started.md#%E8%AE%A4%E8%AF%81)了解认证在整个 API 中如何工作,以及[生产集成](https://docs.reelway.ai/api-reference/production-integrations.md#%E5%BF%85%E9%A1%BB%E5%A4%84%E7%90%86%E7%9A%84%E9%94%99%E8%AF%AF)了解其他需要处理的错误。