# API 金鑰

> 為 API 建立金鑰、設定範圍並加以管理。

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

API 金鑰用來驗證傳送到 Reverie [開放 API](https://reverie.im/zh-TW/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-TW/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-TW/docs/integrations/open-api)——端點、請求格式和錯誤
* [匯入角色](https://reverie.im/zh-TW/docs/characters/import-characters)——匯入用金鑰的用途
* [Reverie 實驗室](https://reverie.im/zh-TW/docs/integrations/labs)——開放 API 和匯入工具的方塊
* [安全性](https://reverie.im/zh-TW/docs/account/security)——你帳號的其他存取設定