Что это такое
Ключ с доступом к управлению аккаунтом может через API почти всё, что доступно в личном кабинете: смотреть баланс, расход и логи, создавать и настраивать ключи, менять режим маршрутизации, получать бонусы и читать уведомления. Это удобно для скриптов, панелей мониторинга и агентов, которым нужно управлять аккаунтом без браузера.
Через API недоступны пополнение баланса и всё, что относится к защите аккаунта: пароль, email, двухфакторная защита и входы в аккаунт. Эти действия остаются на сайте.
Все маршруты находятся под /v1/account на том же Base URL, что и запросы к моделям, и используют тот же заголовок Authorization: Bearer sk-….
Уровни доступа ключа
Уровень задаётся для каждого ключа отдельно. Обычно доступ выключен: существующие ключи и новые ключи без явной настройки не могут обращаться к /v1/account.
- Включить доступ можно в кабинете: API-ключи → создать или изменить ключ → «Доступ к управлению аккаунтом». Изменение действует со следующего запроса.
- Ключ не может выдать уровень выше собственного ни другому ключу, ни самому себе: такая попытка вернёт 403 account_api_escalation.
- Удалить ключ, которым вы подписали запрос, можно только с параметром ?confirm_self=true.
- Изменение, которое закроет ключу его собственный доступ (отключение, срок действия, понижение уровня или IP-фильтр без вашего текущего адреса), требует "confirm_self_lockout": true. Без него вернётся 409 self_lockout_requires_confirmation.
- Отключённые и истёкшие ключи, а также запросы с адреса вне IP-фильтра ключа отклоняются. Ключ с исчерпанным бюджетом сохраняет доступ к управлению аккаунтом.
| Уровень | Значение account_api | Что разрешено |
|---|---|---|
| Нет (по умолчанию) | none | Ничего из /v1/account. Обычные запросы к моделям работают как раньше. |
| Чтение | read | Все GET-маршруты: аккаунт, расход, логи, ключи, настройки, цены, бонусы, уведомления, рефералы, платежи. |
| Управление | manage | Всё из чтения и изменения: ключи, маршрутизация, бонусы, уведомления, перевод реферальных, промокоды. |
Ключ с уровнем «Управление» может создавать и удалять другие ключи и менять настройки аккаунта. Храните его как пароль, выдавайте минимально нужный уровень и по возможности ограничьте IP-фильтром.
Примеры запросов
В примерах используется серверная переменная ELYSIUM_API_KEY со значением sk-…. Ответы сокращены, значения иллюстративные. Метки времени передаются в секундах Unix, суммы в USD.
1curl https://elysiumai.garden/v1/account \2 -H "Authorization: Bearer $ELYSIUM_API_KEY"Полный секрет нового ключа возвращается один раз, в ответе на создание (HTTP 201). Дальше ключи в API всегда маскируются.
Аккаунт, баланс, расход и логи
| Метод | Маршрут | Доступ | Что делает |
|---|---|---|---|
| GET | /v1/account | read | Профиль, группа, баланс, расход, число запросов и уровень текущего ключа. |
| GET | /v1/account/usage | read | Запросы, токены и списания за период с разбивкой по моделям. Параметры start_timestamp и end_timestamp; по умолчанию 30 дней, максимум 90. |
| GET | /v1/account/logs | read | Ваши логи с фильтрами type, model_name, token_name, request_id и периодом; постраничный вывод p и page_size (до 100). |
| GET | /v1/account/logs/{request_id} | read | Записи одного запроса или 404. |
Email, привязки входа и внутренние служебные поля в ответы не попадают. В логах показывается то, что получил ваш клиент.
API-ключи
| Метод | Маршрут | Доступ | Что делает |
|---|---|---|---|
| GET | /v1/account/keys | read | Список ключей (p, page_size). Секреты всегда замаскированы. |
| GET | /v1/account/keys/{id} | read | Один ключ. |
| POST | /v1/account/keys | manage | Создать ключ. Обязательно только name; необязательные поля: expires_at, unlimited_quota, remain_quota, rpm_limit, model_limits_enabled, model_limits, allow_ips, group, cross_group_retry, account_api. |
| PATCH | /v1/account/keys/{id} | manage | Изменить только переданные поля, включая status: enabled или disabled. |
| DELETE | /v1/account/keys/{id} | manage | Удалить ключ. Для ключа, которым подписан запрос, нужен ?confirm_self=true. |
Настройки ключа проверяются так же, как в кабинете: длина названия, RPM, бюджет, списки моделей и IP, доступная группа. Если account_api не указан при создании, ключ получает уровень по умолчанию для вашего аккаунта, обычно none.
Настройки маршрутизации
- routing_mode_default — режим маршрутизации по умолчанию; допустимые значения возвращает available_modes.
- routing_mode_overrides — режимы для отдельных моделей. Поле заменяет все переопределения целиком, максимум 100.
- family_orders — порядок вариантов внутри семейства модели. Объединяется по семействам: пустой список снимает порядок семейства, остальные сохранённые порядки не меняются. Допустимы только включённые варианты этого семейства из GET /v1/account/models.
- Сохранённый порядок строгий: пробуются только перечисленные варианты и именно в этом порядке. Семейства без порядка используют порядок сайта.
- direct_family_fallback_enabled — при прямом обращении к варианту, который недоступен, разрешить переход к другим вариантам того же семейства.
- billing_preference — wallet_only (списывать только с баланса) или wallet_first (сначала с баланса, при нехватке из подписки).
| Метод | Маршрут | Доступ | Что делает |
|---|---|---|---|
| GET | /v1/account/routing | read | Текущие настройки и допустимые значения: available_modes и available_billing_preferences. |
| PATCH | /v1/account/routing | manage | Меняет переданные поля, остальные сохраняют значения. |
Модели и ваши цены
| Метод | Маршрут | Доступ | Что делает |
|---|---|---|---|
| GET | /v1/account/models | read | Те же семейства и варианты, что в GET /v1/model-options, но для всего аккаунта, а не только для моделей текущего ключа. |
Цены уже включают все ваши скидки: личные, бонусные и общие акции. Поля original_* показывают цену без скидки, а discounts — список применённых скидок с процентом и сроком.
Бонусы
| Метод | Маршрут | Доступ | Что делает |
|---|---|---|---|
| GET | /v1/account/bonuses | read | Состояние розыгрыша скидки, личные и общие скидки, бонус новичка: группы, оставшиеся дни и окна. |
| POST | /v1/account/bonuses/discount-roll | manage | Розыгрыш личной скидки на сегодня, условия как в кабинете. Ошибки: already_claimed (409), not_eligible (403), pool_empty (503). |
| POST | /v1/account/bonuses/newbie/allocate | manage | Распределить дни бонуса новичка по группам: массив allocations из объектов group и days. Ошибки: invalid_allocation (400), not_eligible (403), not_enough_days (409), disabled (503). |
Ежедневный бонус, бонус за Telegram и бонус за пополнение остаются на сайте.
Уведомления, рефералы, платежи и промокоды
| Метод | Маршрут | Доступ | Что делает |
|---|---|---|---|
| GET | /v1/account/notifications | read | Уведомления аккаунта (limit, before_id), unread_count и has_more. Картинки не передаются: флаг has_image сообщает, что сайт её показывает. |
| POST | /v1/account/notifications/read | manage | Отметить прочитанным: {"id": 12} или {"all": true}. |
| GET | /v1/account/referral | read | Реферальный код и ссылка, счётчики, доступные и заработанные USD, список наград. |
| POST | /v1/account/referral/transfer | manage | Перевести реферальный заработок на основной баланс: {"amount_usd": "3.30"} или {"all": true}. Ошибки: invalid_amount, below_minimum, insufficient_referral_balance, transfer_failed. |
| GET | /v1/account/topups | read | История пополнений и начислений: статус, тип, сумма, даты. Только чтение (p, page_size). |
| GET | /v1/account/subscriptions | read | Ваши подписки: план, статус, объём и использование, даты периода, а также billing_preference. |
| POST | /v1/account/promo-codes/redeem | manage | Активировать промокод: {"code": "..."}. Те же проверки, что на сайте; ответ содержит amount_usd и new_balance_usd. |
Создание платежей и покупка подписок остаются на сайте: через API можно только читать историю.
Лимиты запросов
| Вызовы | Лимит |
|---|---|
| Чтение (GET) | 120 в минуту на аккаунт |
| Изменения (POST, PATCH, DELETE) | 30 в минуту на аккаунт |
| Промокоды, перевод реферальных, бонусные действия | Дополнительно действует ограничение по IP, как на сайте |
Лимиты общие для всех ключей аккаунта. При превышении вернётся HTTP 429 с кодом rate_limited: подождите до следующей минуты и повторите запрос.
Формат ответов и ошибки
Успешный ответ — HTTP 200 (201 при создании ключа) и JSON вида {"object": "...", "data": ...}. Суммы указаны в USD (поля *_usd). Поля quota — внутренние единицы баланса, а quota_per_usd из GET /v1/account переводит их в доллары.
Ошибка возвращается с HTTP-статусом и телом {"error": {"code": "...", "message": "..."}}. Ориентируйтесь на code: текст сообщения может меняться.
| HTTP | code | Когда возникает |
|---|---|---|
| 401 | invalid_api_key | Ключ не передан, неизвестен, отключён или истёк |
| 403 | account_api_disabled | У ключа уровень «Нет» |
| 403 | account_api_read_only | Ключ с уровнем «Чтение» вызвал изменяющий маршрут |
| 403 | account_api_escalation | Запрошен уровень выше уровня вызывающего ключа |
| 403 | ip_not_allowed, account_disabled | Адрес вне IP-фильтра ключа или аккаунт отключён |
| 404 | not_found | Неизвестный id или объект другого аккаунта |
| 409 | self_lockout_requires_confirmation, self_delete_requires_confirmation | Действие закроет доступ самого ключа: добавьте confirm_self_lockout или confirm_self |
| 409 | key_limit_reached, key_expired, key_exhausted | Достигнут лимит ключей либо ключ истёк или исчерпан и не может быть включён |
| 400 | invalid_request, invalid_group, invalid_routing_mode, invalid_routing_override, invalid_family_order, invalid_billing_preference, invalid_period | Ошибка проверки переданных данных |
| 429 | rate_limited | Превышен лимит запросов |
| 500 | unavailable | Временная ошибка, повторите позже |
1{2 "error": {3 "code": "account_api_read_only",4 "message": "..."5 }6}Термины на этой странице
| Термин | Что означает |
|---|---|
| Base URL | Базовый адрес API, к которому клиент добавляет нужный маршрут. |
| API-ключ | Секрет для авторизации и списания запросов с вашего баланса. |
| Model ID | Точное системное имя модели из каталога Elysium AI. |
| Endpoint | Маршрут конкретной операции после базового адреса API. |
| Request | Один запрос клиента к API вместе с его заголовками и телом. |
| Response | Результат обработки запроса: статус, заголовки и данные. |