# API key

URL: https://docs.router.ezat.io/zh/api-keys

> 创建、命名、复制和吊销 API key，并设置 key 的消费上限、可用模型和有效期。

## 何时阅读本页

用本页创建或吊销 key、限制 key 能花多少钱或能调用哪些模型，以及了解 key 达到限制后会发生什么。

## Key 属于组织

API key 在控制台的 **API Key** 页面创建，属于顶栏中当前选中的组织。每个 key 都从该组织的余额中扣费。创建 key 的人离开后，key 仍然有效，直到有人吊销它。

| 角色 | 可以 |
| --- | --- |
| 所有者和管理员 | 创建 key，吊销任何 key |
| 成员 | 创建 key，吊销自己创建的 key |
| 财务 | 查看 key 列表，但不能创建 key |

组织里的每个人都能看到这个列表：每个 key 的名称、key 的开头和结尾（`ezat_sk_a1b2…wxyz`）、消费上限、最近使用时间、创建时间和状态。key 创建之后，任何人都看不到完整的 key。一个组织最多可以有 50 个可用的 key。

## 创建 key

1. 打开 **API Key**，选择**创建 key**。
2. 填写表单：

   | 字段 | 作用 | 默认值 |
   | --- | --- | --- |
   | **名称** | 给你自己看的标签，例如 `Production`、`Laptop` 或 `CI`。用会使用这个 key 的应用、机器或人来命名。 | 必填 |
   | **消费上限** | 打开后，key 在一个**周期**内花费达到设定金额（美元）就会停用。周期可选**天**、**月**或**总计**。见[消费上限](#消费上限)。 | 不限 |
   | **可用模型** | **所有模型**，或者选择**仅限选中的模型**并勾选 key 可以调用的模型。见[限制 key 可用的模型](#限制-key-可用的模型)。 | 所有模型 |
   | **有效期** | **永久有效**、**30 天**、**90 天**或 **1 年**。到期后 key 会被拒绝。 | 永久有效 |

3. 选择**创建 key**。
4. **保存你的 key** 对话框会显示完整的 key。现在就复制它，并保存在安全的地方，例如密码管理器或你的密钥存储。对话框中的**在 Claude Code 中使用**部分还会显示用这个 key 启动 Claude Code 的命令。
5. 选择**我已保存这个 key**。

<Callout type="warn" title="关闭对话框之前先复制 key">
这是完整的 key 唯一一次显示。EZAT Router 只保存哈希值，所以丢失的 key 无法找回：请创建一个新的。
</Callout>

控制台无法修改已经创建的 key。要更改 key 的限制，请按你想要的设置创建一个新 key，把应用切换到新 key，再吊销旧 key。

## 消费上限

设置消费上限后，key 在当前周期内被计费的金额达到上限时就会停用：

| 周期 | 统计 key 哪段时间的花费 | 何时重新计算 |
| --- | --- | --- |
| **天** | 今天 00:00 UTC 起 | 每天 00:00 UTC |
| **月** | 本月 1 日 00:00 UTC 起 | 每月 1 日 00:00 UTC |
| **总计** | key 创建起 | 从不 |

- 每个请求开始前，都会用 key 截至当时的计费金额检查上限。开始时未达上限的请求一定会执行完，所以 key 的花费可能略微超过上限。
- 达到上限后，使用该 key 的请求会失败，返回 `402` 和错误类型 `billing_error`（OpenAI 格式中为 `insufficient_quota`）。消息会写明周期和上限，例如 `This API key reached its monthly spend limit of $<amount>`。
- **天**或**月**周期的 key 会在下一个周期开始时恢复可用。**总计**周期的 key 会一直停用：请创建一个新 key。
- 组织余额的限制仍然适用。即使 key 没有达到上限，余额用完后请求也会被拒绝。

## 限制 key 可用的模型

选择**仅限选中的模型**后，key 只能调用你勾选的模型：

- 用这个 key 调用 `GET /v1/models`（以及 `GET /openai/v1/models`），只会列出这些模型。
- 请求其他任何模型都会失败，返回 `403` 和错误类型 `permission_error`：`This API key is not allowed to use …`。
- 模型的其他名称也可以用。允许一个模型，就同时允许了它的 `author/model` id 和所有别名（见[模型](https://docs.router.ezat.io/zh/models.md)）。

### 预览模型

模型在正式发布前可能处于预览阶段。预览模型不会出现在 `GET /v1/models` 中，并且会返回 `404`（`not_found_error`），除非 key 拥有预览权限。预览权限不是控制台里的选项；如有需要，请联系 support@ezat.io。

## 每分钟请求数

每个 key 每分钟最多可以发出 1,000 个请求，按自然分钟计数。token 计数请求也算在内。超过后，请求会失败，返回 `429` 和错误类型 `rate_limit_error`（`This API key exceeded its requests-per-minute limit`），并带有 `retry-after: 30` 响应头。等待相应的秒数后再重试。这个限制不能在控制台中设置；如果对你来说太低，请联系 support@ezat.io。见[速率限制](https://docs.router.ezat.io/zh/reference/rate-limits.md)。

## 吊销 key

1. 打开 **API Key**。
2. 在该 key 所在行打开操作菜单（**…**），选择**吊销**。
3. 选择**吊销 key** 进行确认。

使用该 key 的请求会立即失败，返回 `401`（`This API key has been revoked`），而且吊销无法撤回。这个 key 会以**已吊销**状态留在列表中，它的用量也仍保留在**用量**中。

超过有效期的 key 显示为**已过期**状态，使用它的请求会失败，返回 `401`（`This API key has expired`）。

## 给 AI agent 的说明

1. 只有用户本人能在控制台 `https://router.ezat.io/zh/keys` 中创建或吊销 key。请用户创建一个 key 并放进环境变量（`EZAT_API_KEY`）；不要让用户把 key 粘贴到对话里。
2. key 创建后无法修改它的限制。如果 key 的限制太严格，由用户创建一个新的。
3. 遇到 `402` 且消息与 key 的消费上限有关时，停止：在周期重置之前，重试都没有用。告诉用户触发了哪个上限。
4. 遇到 `403` `This API key is not allowed to use …` 时，用同一个 key 调用 `GET https://api.router.ezat.io/v1/models`，从中选一个模型；这个列表只包含该 key 可以调用的模型。
5. 遇到 `429` 时，等待 `retry-after` 中的秒数，然后重试。