# Проверка баланса с помощью ключа API
> Проверяйте остаток квоты текущего ключа с помощью ключа API sk-: GET /v1/user/balance возвращает is_active / balance / unit, а GET /v1/credits — total_credits / total_usage в стиле OpenRouter. Совместимо с периодическими запросами сторонних клиентов, таких как cc-switch.
URL: https://docs.lmuai.com/ru/docs/api/balance
С помощью ключа API, начинающегося с `sk-`, можно напрямую узнать **остаток квоты и доступность этого ключа**. Это подходит сторонним клиентам, показывающим баланс в интерфейсе, и скриптам, которые следят за балансом.
**Эти эндпоинты только для чтения**: они не тарифицируются и не расходуют квоту. Аутентификация проверяет только сам ключ, поэтому остаток квоты можно узнать даже тогда, когда квота исчерпана и рабочие запросы были бы отклонены (в этом случае `is_active` равно `false`).
***
## 1. Обзор эндпоинтов [#1-обзор-эндпоинтов]
| Эндпоинт | Поддерживаемый формат клиента | Возвращает |
| ---------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------- |
| `GET /v1/user/balance` | Универсальный шаблон баланса cc-switch | `is_active` / `balance` / `unit`, а также `used` / `total`, если у ключа есть общая квота |
| `GET /user/balance` | То же, для Base URL без `/v1` | Полностью совпадает со строкой выше |
| `GET /v1/credits` | Стиль OpenRouter | `data.total_credits` / `data.total_usage` |
| Параметр | Значение |
| -------------- | -------------------------------- |
| Base URL | `https://api.lmuai.com` |
| Аутентификация | `Authorization: Bearer ` |
| Формат ответа | JSON |
| Нужен ли вход | Нет, достаточно ключа API |
`/user/balance` — это псевдоним `/v1/user/balance` (используется, когда Base URL клиента задан без `/v1`). У `/v1/credits` **нет** псевдонима в корневом пути, `/v1` обязателен.
***
## 2. Какой баланс возвращается [#2-какой-баланс-возвращается]
`balance` — не обязательно баланс кошелька аккаунта; это **остаток квоты, фактически доступный текущему ключу**, определяемый в следующем порядке:
| Порядок | Ситуация с ключом | Что означает `balance` |
| ------- | -------------------------------------- | -------------------------------------------------------------------------- |
| 1 | У ключа задана собственная общая квота | Остаток квоты этого ключа (`total - used`) |
| 2 | Ключ относится к группе подписки | Остаток квоты подписки (`unit` равен `requests`, если подсчёт по запросам) |
| 3 | Ни то, ни другое | Баланс кошелька аккаунта |
Кроме того, `is_active` показывает, **можно ли сейчас использовать ключ для рабочих запросов**: `true`, если ключ активен, не истёк и его общая квота не исчерпана; также `false`, если ключ относится к группе подписки без действующей подписки.
***
## 3. `GET /v1/user/balance` [#3-get-v1userbalance]
```http
GET /v1/user/balance HTTP/1.1
Host: api.lmuai.com
Authorization: Bearer sk-xxxxxxxx
```
**Ответ — режим баланса кошелька** (у ключа нет квоты и он не в группе подписки):
```json
{
"is_active": true,
"balance": 1575.13,
"unit": "USD"
}
```
**Ответ — у ключа есть общая квота** (в этом случае дополнительно возвращаются `used` и `total`):
```json
{
"is_active": true,
"balance": 6,
"unit": "USD",
"used": 4,
"total": 10
}
```
**Ответ — группа подписки с подсчётом по запросам**:
```json
{
"is_active": true,
"balance": 842,
"unit": "requests"
}
```
### Поля ответа [#поля-ответа]
| Поле | Тип | Описание |
| ----------- | ------ | --------------------------------------------------------------------------------------------- |
| `is_active` | bool | Можно ли сейчас использовать ключ для рабочих запросов |
| `balance` | number | Остаток квоты; единица измерения указана в `unit` |
| `unit` | string | `USD` (по умолчанию) или `requests` для групп подписки с подсчётом по запросам |
| `used` | number | **Присутствует только при наличии общей квоты у ключа**: уже использованная квота этого ключа |
| `total` | number | **Присутствует только при наличии общей квоты у ключа**: общая квота этого ключа |
`used` / `total` имеют осмысленные значения только в режиме квоты по ключу. В режимах баланса кошелька и подписки эти поля не возвращаются — ориентируйтесь на `balance` и не вычисляйте его как `total - used`.
***
## 4. `GET /v1/credits` [#4-get-v1credits]
Формат баланса в стиле OpenRouter; клиенты показывают остаток квоты как `total_credits - total_usage`.
```http
GET /v1/credits HTTP/1.1
Host: api.lmuai.com
Authorization: Bearer sk-xxxxxxxx
```
**Ответ:**
```json
{
"data": {
"total_credits": 20,
"total_usage": 4
}
}
```
| Поле | Тип | Описание |
| -------------------- | ------ | -------------------------------------------------------------------------------------------------- |
| `data.total_credits` | number | **Использовано + остаток**, чтобы `total_credits - total_usage` в точности равнялось остатку квоты |
| `data.total_usage` | number | Уже использованная квота |
`total_credits` — составное значение «использовано + остаток», а **не** буквальное значение лимита квоты. В режиме баланса кошелька `total_usage` равен `0`, и `total_credits` равно балансу; при исчерпании квоты остаток ограничивается нулём, поэтому в этом случае `total_credits` равно использованному объёму.
***
## 5. Настройка в сторонних клиентах [#5-настройка-в-сторонних-клиентах]
| Клиент / сценарий | Как настроить |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Универсальный шаблон баланса cc-switch | Base URL `https://api.lmuai.com` (без `/v1`) или `https://api.lmuai.com/v1` (с `/v1`) — оба варианта работают |
| Клиенты, совместимые с OpenRouter (Kelivo, RikkaHub и др.) | Base URL `https://api.lmuai.com/v1`; клиент запросит `/v1/credits` |
| Собственный скрипт | Вызывайте `/v1/user/balance` напрямую — поля проще для восприятия |
```bash
curl -s https://api.lmuai.com/v1/user/balance \
-H "Authorization: Bearer sk-xxxxxxxx"
```
***
## 6. Ответы об ошибках [#6-ответы-об-ошибках]
Запрос баланса использует стандартную аутентификацию шлюза по API-ключу, поэтому ошибки приходят в том же формате, что и для других вызовов API. Если в запросе нет ключа:
```json
{
"code": "API_KEY_REQUIRED",
"message": "API key is required in Authorization header (Bearer scheme), x-api-key header, or x-goog-api-key header"
}
```
| Код состояния | `code` | Ситуация |
| ------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | — | Обычный ответ; исчерпанная квота, истёкший ключ или отсутствующая подписка тоже возвращают `200`, а `is_active: false` означает, что ключ нельзя использовать |
| `401` | `API_KEY_REQUIRED` | В запросе нет API-ключа |
| `401` | `INVALID_API_KEY` | Ключ не существует или имеет неверный формат |
| `401` | `API_KEY_DISABLED` | Ключ отключён |
| `403` | `ACCESS_DENIED` | Для ключа задан список разрешённых / запрещённых IP, и текущий IP не разрешён |
Общие ошибки см. в разделе [Коды ошибок](/ru/docs/guide/errors).
***
## 7. Отличие от «Экспорта детализации использования» [#7-отличие-от-экспорта-детализации-использования]
| | Эндпоинты баланса на этой странице | [Экспорт детализации использования](/ru/docs/api/usage-export) |
| -------------- | ------------------------------------------- | -------------------------------------------------------------- |
| Аутентификация | Ключ API `sk-` | Аккаунт и пароль в обмен на JWT |
| Детализация | Остаток квоты текущего ключа | Детализация по каждому запросу на уровне аккаунта |
| Назначение | Показ баланса в клиенте, мониторинг баланса | Экспорт счетов, сверка, загрузка в BI |
`GET /v1/usage` находится между ними: он также принимает ключ `sk-` и возвращает статистику использования за сегодня и накопительно, а также информацию о квоте текущего ключа, с более подробными полями.