# Ключи API

> Как создавать ключи для API, ограничивать их и управлять ими.

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

Ключ API подтверждает запросы к [Открытому API](https://reverie.im/ru/docs/integrations/open-api) Reverie. Ключи живут в **Настройки → Ещё → Ключи 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]

У ключей есть разрешения, но окно создания их не показывает. Ключ, сделанный в настройках, может вызывать эндпоинты чата — и только их.

Эндпоинту импорта персонажей нужно другое разрешение, и получить такой ключ можно единственным способом: открыть **Лабораторию → Навык импорта персонажей**, который создаст вам ключ с именем **Reverie Character Importer (Skill)**. Вызов импорта обычным ключом из настроек вернёт 403. [Импорт персонажей →](https://reverie.im/ru/docs/characters/import-characters)

## Статистика использования \[#usage-statistics]

Панель **Статистика использования** на той же странице показывает **Запросы**, **Токены**, **Кредиты** и **Активные ключи** с разбивкой по суткам UTC, а под заголовком **Использование по ключам** — детализацию по каждому ключу. Можно отфильтровать по одному ключу или выбрать **Все ключи**, за период от 7 до 90 дней — по умолчанию 30. Считаются только чаты, созданные через API.

Это единственное место, где вообще существует расход по ключам. В истории кредитов записано, сколько стоило каждое сообщение, но не указано, каким ключом оно отправлено, так что сравнивать интеграции нужно именно здесь.

## Создать запрос \[#build-a-request]

**Создать запрос** открывает генератор: выберите один из активных ключей, выберите персонажа или сценарий из списка, который виден этому ключу, наберите сообщение, задайте потоковую передачу и temperature — и скопируйте рабочий cURL, TypeScript или Python.

Ключ используется в браузере только для загрузки списка персонажей. Сгенерированный код читает `REVERIE_API_KEY` из окружения, а не зашивает секрет внутрь.

## Ограничения \[#limits]

| Ограничение                           | Значение                                      |
| ------------------------------------- | --------------------------------------------- |
| Ключей на аккаунт                     | Без предела                                   |
| Лимит частоты на ключ                 | Нет                                           |
| Потолок параллельных запросов на ключ | Нет                                           |
| Что на самом деле ограничивает        | Ваш баланс кредитов и окно бесплатных моделей |

## Смежное \[#related]

* [Открытый API](https://reverie.im/ru/docs/integrations/open-api) — эндпоинты, вид запроса и ошибки
* [Импорт персонажей](https://reverie.im/ru/docs/characters/import-characters) — для чего нужен ключ импорта
* [Reverie Лаборатория](https://reverie.im/ru/docs/integrations/labs) — плитки открытого API и импорта
* [Безопасность](https://reverie.im/ru/docs/account/security) — остальные настройки доступа к аккаунту