Баланс

Баланс один на аккаунт, с него списываются запросы всех ключей. Баланс и историю операций читает ключ управления. Обычный API-ключ баланса не видит и о нехватке узнаёт по ответу 402.

curl https://api.souz.ai/v1/balance \
  -H "Authorization: Bearer $SOUZ_MANAGEMENT_KEY"
JSON
{
  "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"
JSON
{
  "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Ссылка на чек, когда он доступен.
methodcard, 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-ключом.Используйте ключ управления.

Дальше