# API 密钥

> 为 API 创建密钥、设定范围并管理它们。

Source: https://reverie.im/zh/docs/integrations/api-keys
Language: zh

API 密钥用来对发往 Reverie [开放 API](https://reverie.im/zh/docs/integrations/open-api) 的请求做鉴权。密钥都在**设置 → 更多 → API 密钥**里，实验室的 **开放 API** 方块指向的也是这里。任何账号都能创建——没有档位要求，也不限制你能持有多少个。

## 创建一个密钥 \[#create-a-key]

### 按下「创建新的 API 密钥」 \[#press-create-new-api-key]

页面还空着的时候，这个按钮上写的是**创建第一个 API 密钥**。

### 给它起个名字 \[#name-it]

**名称**是必填的，1–100 个字符。它决定了这个密钥在列表和使用统计里怎么标注——比如「客厅音箱」「staging worker」。

### 选择全局还是指定角色 \[#choose-global-or-a-specific-character]

**角色选择**是在**全局**（所有角色）和**指定角色**之间二选一，而不是一个可有可无的附加项。选中的那个角色会成为这把密钥绑定的角色。

### 可以顺便设置设备类型和有效期 \[#optionally-set-a-device-type-and-an-expiry]

**设备类型**是自由文本（`speaker`、`phone`、`iot`）。**有效期**同时要填日期**和**时间；到了那一刻，密钥会自动失效。

密钥会立刻显示出来，形如 `rk_` 加上 64 个十六进制字符。

## 密钥随时可以取回 \[#keys-stay-retrievable]

密钥不是只显示一次。只要这把密钥还在，它的卡片上随时都有**显示 API 密钥**、**隐藏 API 密钥**和**复制 API 密钥**。

> 既然完整的密钥随时能从你的设置里读出来，那就把账号的访问权当成密钥的访问权来对待。把密钥放在服务器上或密钥管理器里，永远别放进代码仓库或浏览器代码里。

## 全局密钥和绑定角色的密钥 \[#global-keys-and-pinned-keys]

|                  | **全局（所有角色）** | **指定角色**                 |
| ---------------- | ------------ | ------------------------ |
| `GET /models` 返回 | 你最近的角色       | 那个角色的情景，如果它一个都没有，就返回角色本身 |
| 不填 `model`       | 落到你最近的那次聊天   | 用绑定的那个角色                 |
| 短情景 ID           | 永远解析不出来      | 会在绑定的角色下解析               |

## 停用、删除、轮换 \[#disable-delete-rotate]

| 操作       | 效果                  | 可否撤销 |
| -------- | ------------------- | ---- |
| **启用**开关 | 关掉之后，带这把密钥的请求会被拒绝   | 可以   |
| **删除**   | 密钥被销毁，正在用它的应用会失去访问权 | 不可以  |

没有单独的吊销操作——停用和删除就是全部的两个选项。

> 删除密钥无法撤销，而且会把这把密钥的归属一并带走：它过去的流量会挪进使用统计里的**已删除的密钥**那一栏，到那时你就分不清是哪个集成花掉了多少。如果你可能还想要这段历史，就先停用它。

要轮换密钥，先创建替代的那把、部署上去，然后再停用或删除旧的。这里没有自动轮换，过期之后也没有宽限期——过期的密钥会在下一次请求时被拒绝，并返回 `api_key_expired`。

## 权限范围 \[#scopes]

密钥带有权限范围，而创建对话框并不会把它们露出来。你在设置里做的密钥只能调用聊天相关的接口，仅此而已。

角色导入接口需要另一种权限范围，而拿到这种密钥的唯一办法，就是打开**实验室 → 角色导入 Skill**，它会替你创建一把，名字叫 **Reverie Character Importer (Skill)**。拿设置页里的普通密钥去调导入接口会返回 403。[导入角色 →](https://reverie.im/zh/docs/characters/import-characters)

## 使用统计 \[#usage-statistics]

同一个页面上的**使用统计**面板会报告**请求数**、**Token**、**积分**和**活跃密钥**，按 UTC 日分桶，并在**按密钥统计**下给出每把密钥的明细。你可以按某一把密钥或**全部密钥**筛选，时间窗口从 7 天到 90 天——默认 30 天。只有通过 API 创建的聊天会被统计进来。

这个面板是唯一能看到「每把密钥各花了多少」的地方。你的积分历史会记录每条消息花了多少，但它不会标注这笔交易是哪把密钥发起的，所以要比较各个集成，就用这里的统计。

## 生成请求 \[#build-a-request]

**生成请求**会打开一个生成器：挑一把你启用中的密钥，从这把密钥能看到的列表里挑一个角色或情景，输入一条消息，选好是否流式以及 temperature，然后就能复制可以直接跑的 cURL、TypeScript 或 Python 代码。

这把密钥只在你的浏览器里被用来加载角色列表。生成出来的代码是从环境变量里读 `REVERIE_API_KEY`，而不是把密钥写死进去。

## 限制 \[#limits]

| 限制         | 数值                 |
| ---------- | ------------------ |
| 每个账号的密钥数   | 不限                 |
| 每把密钥的速率限制  | 没有                 |
| 每把密钥的并发上限  | 没有                 |
| 真正约束用量的是什么 | 你的积分余额，以及免费模型的时段配额 |

## 相关 \[#related]

* [开放 API](https://reverie.im/zh/docs/integrations/open-api) — 接口、请求结构和报错
* [导入角色](https://reverie.im/zh/docs/characters/import-characters) — 导入用的那把密钥是做什么的
* [Reverie 实验室](https://reverie.im/zh/docs/integrations/labs) — 开放 API 和导入这两个方块
* [安全](https://reverie.im/zh/docs/account/security) — 你账号其余的访问设置