Баланс
Баланс один на аккаунт, с него списываются запросы всех ключей. Баланс и историю операций
читает ключ управления. Обычный API-ключ баланса не видит и о нехватке
узнаёт по ответу 402.
curl https://api.souz.ai/v1/balance \
-H "Authorization: Bearer $SOUZ_MANAGEMENT_KEY"import os
import httpx
balance = httpx.get(
"https://api.souz.ai/v1/balance",
headers={"Authorization": f"Bearer {os.environ['SOUZ_MANAGEMENT_KEY']}"},
).json()
print(balance["spendable_micro"] / 1_000_000)const res = await fetch("https://api.souz.ai/v1/balance", {
headers: { Authorization: `Bearer ${process.env.SOUZ_MANAGEMENT_KEY}` },
});
const balance = await res.json();
console.log(balance.spendable_micro / 1_000_000);{
"available_micro": 482500000,
"overdraft_limit_micro": 0,
"spendable_micro": 470100000,
"spent_total_micro": 1250000000,
"currency": "RUB",
"mock_topup": false
}Поля баланса
| Поле | Что значит |
|---|---|
available_micro | Зачисленное минус списания за завершённые запросы. |
overdraft_limit_micro | Согласованный лимит овердрафта, 0 если его нет. |
spendable_micro | Доступно для новых запросов: баланс плюс овердрафт минус занятое выполняющимися запросами. |
spent_total_micro | Сумма списаний за всё время, обновляется в течение минуты. |
currency | Валюта сумм, RUB. |
mock_topup | Тестовое пополнение на сервере; в рабочем API всегда false. |
Без овердрафта баланс не становится отрицательным. С овердрафтом available_micro уходит в
минус не дальше overdraft_limit_micro, следующее пополнение гасит долг. Итог больше
остатка описан в Цены и списание.
Пополните баланс
Пополняют владелец и администратор в кабинете, через API баланс не пополняется. Зачисляется вся оплаченная сумма, комиссию платёжной системы платит Союз. Чеки и возврат описаны на странице Команда.
Бонусы списываются первыми. Бонус — объём со скидкой 100%, а не деньги, и он не возвращается.
Прочитайте историю операций
GET /v1/balance/history возвращает операции, новые первыми. ?kind= оставляет один вид
операций, страницы листаются по limit и before (см. Запросы и ответы).
curl "https://api.souz.ai/v1/balance/history?limit=2" \
-H "Authorization: Bearer $SOUZ_MANAGEMENT_KEY"{
"currency": "RUB",
"items": [
{
"id": "job_abc123",
"kind": "charge",
"amount_micro": 3900000,
"created_at": "2026-10-15T12:00:00Z",
"job_id": "job_abc123",
"canonical_model": "nano-banana-2",
"modality": "image",
"api_key_name": "production",
"api_key_kind": "user"
},
{
"id": "dep_42",
"kind": "deposit",
"source": "payment",
"amount_micro": 1000000000,
"created_at": "2026-10-14T09:00:00Z",
"topup": {
"remaining_micro": 482500000,
"refunded_micro": 0,
"refund_pending_micro": 0,
"reversed_micro": 0,
"method": "sbp",
"receipt_url": "https://souz.ai/receipts/dep_42"
}
}
],
"next_before": "1758600000123456.4211"
}Суммы приходят без знака, направление задаёт kind:
kind | Операция | Баланс |
|---|---|---|
deposit | Пополнение. source: payment — оплата, bonus — бонус. | растёт |
charge | Одно списание за успешный запрос по фактической цене, запрос в job_id. | уменьшается |
refund | Возврат остатка через поддержку. | уменьшается |
reversal | Отмена начисления поддержкой, в source что отменено. Баланс не уходит в минус. | уменьшается |
Объект topup пополнения показывает, что стало с деньгами:
| Поле | Что значит |
|---|---|
remaining_micro | Остаток, включая сумму к возврату. |
refunded_micro | Уже возвращено. |
refund_pending_micro | Часть остатка, удержанная для возврата. |
reversed_micro | Отменено поддержкой; это не расход и не возврат. |
receipt_url | Ссылка на чек, когда он доступен. |
method | card, sbp или other, появляется в течение минуты после оплаты. |
Бонус от поддержки подписан label: topup_bonus, compensation (запрос в job_id) или
bonus. Приветственный бонус и бонус по приглашению идут без label.
Посмотрите расходы по запросам
Чтобы разобрать расход по запросам, используйте учёт расходов:
| Метод | Что возвращает |
|---|---|
GET /v1/usage | Запросы, новые первыми, с фильтрами по модели, ключу и статусу. Все фильтры — в справочнике API. |
GET /v1/usage/summary | Расход по дням (days, до 365) или часам (bucket=hour, до 48) и топ моделей. |
GET /v1/usage/{id} | Один запрос: цена, параметры, результат и ошибка. |
Разработчик видит только запросы своих ключей, остальные роли — все запросы аккаунта.
Аккаунт без баланса
Если в GET /v1/auth/me стоит has_balance: false, расход учитывается по факту в
GET /v1/usage, а баланс, история и пополнение недоступны. Лимиты трат ключей и участников
действуют как обычно.
| Код | Когда | Что делать |
|---|---|---|
403 account_without_balance | Баланс, история или пополнение у аккаунта без баланса. | Смотрите расход в GET /v1/usage. |
403 forbidden, reason: requires_management_key | Баланс запрошен обычным API-ключом. | Используйте ключ управления. |
Дальше
- Цены и списание — как считается итог.
- Ключ управления — доступ к балансу из скрипта.
- Команда — пополнение, бонусы и возврат.