> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API баланса: запрос /api/user/self через AccessToken

> Следите за балансом LaoZhang API: получите системный AccessToken, вызовите /api/user/self, прочитайте поля квоты и пересчитайте её в доллары США для оповещений.

| Параметр | Значение |
| - | - |
| Эндпоинт | `GET https://api.laozhang.ai/api/user/self` |
| Аутентификация | Системный AccessToken в заголовке `Authorization` |
| Основные поля | Остаток квоты, использованная квота, число запросов и группа аккаунта |
| Пересчёт | Разделите `quota` на 500 000, чтобы получить остаток в долларах США; см. раздел «Пересчёт квоты в доллары США» ниже |

> [!NOTE]
>
> **AccessToken — это не API-ключ для запросов к моделям, и права у него шире.**
>
> * Храните его на сервере, в переменной окружения или в хранилище секретов.
> * Никогда не передавайте его в браузер или клиентское приложение.

## Получение AccessToken

**1. Откройте настройки аккаунта**

Войдите в консоль и откройте [настройки аккаунта](https://api.laozhang.ai/account/profile).

**2. Откройте диалог системного токена**

Выберите **System Token** и введите пароль от аккаунта, когда консоль его запросит.

**3. Скопируйте AccessToken**

Скопируйте AccessToken сразу после появления и надёжно сохраните. Новый AccessToken может сделать прежний недействительным, поэтому обновите его во всех сервисах, где он используется.

Не помещайте AccessToken в исходный код, браузерные приложения, логи, скриншоты и обращения в поддержку. Обращаясь в поддержку, указывайте время запроса, HTTP-статус, текст ответа и команду с закрытыми секретами.

## Эндпоинт

```text theme={null}
GET https://api.laozhang.ai/api/user/self
Authorization: <your AccessToken>
```

У запроса нет параметров запроса и тела, ответ приходит в JSON. Передавайте в `Authorization` сам AccessToken, как в примерах ниже. Заголовки `Accept: application/json` и `Content-Type: application/json` необязательны. В cURL рекомендуем флаг `--compressed`, чтобы ответ распаковывался.

## Ответ

Успешный запрос возвращает:

```json theme={null}
{
  "success": true,
  "message": null,
  "data": {
    "id": 12345,
    "username": "demo_user",
    "display_name": "demo_user",
    "role": 1,
    "status": 1,
    "email": "",
    "quota": 24997909,
    "used_quota": 10027091,
    "request_count": 339,
    "group": "default",
    "ModelFixedPrice": []
  }
}
```

| Поле | Тип | Описание |
| - | - | - |
| `success` | Boolean | Выполнен ли запрос успешно. |
| `message` | String или null | Сообщение об ошибке; при успехе обычно `null`. |
| `data.quota` | Integer | Остаток квоты; используйте его для порогов оповещений. |
| `data.used_quota` | Integer | Использованная квота. |
| `data.request_count` | Integer | Общее число запросов. |
| `data.group` | String | Группа аккаунта. |
| `data.username` | String | Имя пользователя. |
| `data.display_name` | String | Отображаемое имя. |
| `data.ModelFixedPrice` | Array | Данные о ценах моделей; если нужен только баланс, игнорируйте. |
| `data.access_token` | String | Конфиденциальное поле; если оно вернулось, не записывайте его в логи. |

В зависимости от аккаунта ответ может содержать и другие поля. Читайте только нужные поля и позвольте парсеру игнорировать неизвестные.

## Пересчёт квоты в доллары США

`quota` и `used_quota` возвращаются в единицах квоты, а не в долларах. 500 000 единиц квоты — это примерно 1 USD.

| Значение | Формула | Пример из ответа |
| - | - | - |
| Остаток баланса | `quota ÷ 500 000` | `24997909 ÷ 500 000` ≈ 50.00 USD |
| Израсходовано | `used_quota ÷ 500 000` | `10027091 ÷ 500 000` ≈ 20.05 USD |
| Остаток плюс израсходованное | `(quota + used_quota) ÷ 500 000` | ≈ 70.05 USD |

Используйте пересчёт для отображения. Фактическая стоимость запроса зависит от цены модели, группы токена и суммы, указанной в журнале вызовов. Для оповещений храните исходное значение `quota` вместе с пересчитанной суммой, чтобы не терять точность.

## Примеры кода

Один раз задайте AccessToken в терминале, заменив заглушку:

```bash theme={null}
export LAOZHANG_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
```

> [tab] cURL
>
> ```bash theme={null}
> curl --compressed -s "https://api.laozhang.ai/api/user/self" \
>   -H "Accept: application/json" \
>   -H "Authorization: $LAOZHANG_ACCESS_TOKEN" \
>   -H "Content-Type: application/json"
> ```
>
> Без `--compressed` терминал может показать нечитаемые символы, а `jq` — ошибку `Invalid numeric literal`.

> [tab] cURL с jq
>
> ```bash theme={null}
> curl --compressed -s "https://api.laozhang.ai/api/user/self" \
>   -H "Accept: application/json" \
>   -H "Authorization: $LAOZHANG_ACCESS_TOKEN" \
>   -H "Content-Type: application/json" |
>   jq '.data | {
>     quota,
>     remaining_usd: (.quota / 500000),
>     used_quota,
>     used_usd: (.used_quota / 500000),
>     request_count,
>     group
>   }'
> ```

> [tab] Python
>
> Установите `requests` командой `python -m pip install requests` и запустите:
>
> ```python theme={null}
> import os
> import requests
>
> response = requests.get(
>     "https://api.laozhang.ai/api/user/self",
>     headers={
>         "Accept": "application/json",
>         "Authorization": os.environ["LAOZHANG_ACCESS_TOKEN"],
>         "Content-Type": "application/json",
>     },
>     timeout=10,
> )
> response.raise_for_status()
> payload = response.json()
> if not payload.get("success"):
>     raise SystemExit(f"Не удалось получить баланс: {payload.get('message')}")
>
> account = payload["data"]
> quota_per_usd = 500_000
> print("quota:", account["quota"])
> print("remaining_usd:", round(account["quota"] / quota_per_usd, 2))
> print("used_quota:", account["used_quota"])
> print("used_usd:", round(account["used_quota"] / quota_per_usd, 2))
> print("request_count:", account["request_count"])
> print("group:", account.get("group"))
> ```
>
> `requests` автоматически распаковывает ответы gzip.

> [tab] Node.js
>
> Сохраните код в файл `.mjs` и запустите в Node.js 18 или новее:
>
> ```javascript theme={null}
> const response = await fetch("https://api.laozhang.ai/api/user/self", {
>   headers: {
>     Accept: "application/json",
>     Authorization: process.env.LAOZHANG_ACCESS_TOKEN,
>     "Content-Type": "application/json",
>   },
>   signal: AbortSignal.timeout(10_000),
> });
> if (!response.ok) {
>   throw new Error(`Не удалось получить баланс: HTTP ${response.status}`);
> }
>
> const payload = await response.json();
> if (!payload.success) {
>   throw new Error(`Не удалось получить баланс: ${payload.message}`);
> }
>
> const account = payload.data;
> const quotaPerUsd = 500_000;
> console.log({
>   quota: account.quota,
>   remaining_usd: Number((account.quota / quotaPerUsd).toFixed(2)),
>   used_quota: account.used_quota,
>   used_usd: Number((account.used_quota / quotaPerUsd).toFixed(2)),
>   request_count: account.request_count,
>   group: account.group,
> });
> ```

## Ошибки

### 401 Unauthorized

```json theme={null}
{
  "success": false,
  "message": "Unauthorized"
}
```

Заголовок `Authorization` пуст, AccessToken неполный или уже недействителен, либо вместо AccessToken отправлен API-ключ для запросов к моделям. Каждую причину разбирает материал [Как исправить ошибку 401 в API баланса](https://docs.laozhang.ai/en/faq/balance-query-api.md).

Смотрите на код статуса вместе с телом ответа:

* Если заголовка `Authorization` нет совсем, API возвращает HTTP 401 с `code`, равным `AUTH_REQUIRED`.
* Если AccessToken неверен или просрочен, возвращается **HTTP 200** с `success: false` и сообщением о недействительном токене доступа.

Проверяйте `success` в скрипте, а не только код статуса.

### 403 Forbidden

```json theme={null}
{
  "success": false,
  "message": "Forbidden"
}
```

У учётных данных нет прав на этот эндпоинт, либо аккаунтом должна заняться поддержка.

### Нечитаемый вывод или ошибка jq

Если cURL печатает нечитаемые символы, а `jq` сообщает `Invalid numeric literal`, сжатый ответ не был распакован. Добавьте к команде cURL флаг `--compressed`.

## Рекомендации по мониторингу

Чтобы узнавать о низком балансе заранее, запускайте проверку этого эндпоинта по расписанию. Скрипт завершается со статусом 1, если остаток баланса ниже порога:

```python theme={null}
import os
import sys
import requests

THRESHOLD_USD = float(os.environ.get("LAOZHANG_ALERT_USD", "20"))

response = requests.get(
    "https://api.laozhang.ai/api/user/self",
    headers={"Authorization": os.environ["LAOZHANG_ACCESS_TOKEN"]},
    timeout=10,
)
response.raise_for_status()
remaining_usd = response.json()["data"]["quota"] / 500000

if remaining_usd < THRESHOLD_USD:
    print(f"Баланс ${remaining_usd:.2f} ниже порога ${THRESHOLD_USD}")
    sys.exit(1)
```

Запускайте его из cron или системы мониторинга каждые 10–30 минут и отправляйте уведомление при ненулевом коде завершения, например:

```bash theme={null}
*/10 * * * * /usr/bin/python3 /opt/check_balance.py || /opt/notify.sh
```

Cron не загружает окружение вашей оболочки, поэтому задайте `LAOZHANG_ACCESS_TOKEN` в скрипте или в crontab. При настройке:

* храните `LAOZHANG_ACCESS_TOKEN` в переменной окружения или в хранилище секретов;
* задайте таймаут запроса, например 10 секунд;
* опрашивайте с умеренным интервалом: для оповещений о балансе почти никогда не нужны проверки каждую секунду;
* включайте в оповещение `quota`, пересчитанный баланс, `used_quota`, `request_count`, время запроса и HTTP-статус;
* никогда не пишите в логи заголовок `Authorization`, `access_token` и другие конфиденциальные поля аккаунта.

## Связанные материалы

* [FAQ по API баланса: нечитаемый вывод, ошибки 401, AccessToken и API-ключ](https://docs.laozhang.ai/en/faq/balance-query-api.md)
* [Сбой при положительном балансе](https://docs.laozhang.ai/ru/faq/balance-insufficient.md)
* [Как читать журнал вызовов](https://docs.laozhang.ai/en/faq/call-logs.md)
* [API журнала вызовов: выгрузка записей и списаний из кода](https://docs.laozhang.ai/ru/api-capabilities/log-query.md)
* [API управления токенами: создание, отключение и удаление API-ключей из кода](https://docs.laozhang.ai/ru/api-capabilities/token-management.md)
* [Тарификация, группы токенов и счета](https://docs.laozhang.ai/ru/pricing.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.