# Цены и баланс

Списывается только успешный запрос, после завершения; неуспешный
бесплатен.

## Деньги в API

Суммы — целые микроединицы: `1 000 000` = 1 ₽, рядом всегда `currency` (`RUB`). Например,
`"price": 5000000` — 5 ₽. Цена нового запроса округляется только вверх до целого
микро-рубля, без дополнительного округления до копейки: `"price": 426299` —
0.426299 ₽. Тысяча таких запросов стоит 426.299 ₽. Уже принятые запросы
сохраняют условия, действовавшие при приёме.

## Цена до запроса и итог

- **До запроса** — цена «от», цены опций пресетов и каналов в карточке модели
  ([Модели и каталог](https://souz.ai/docs/models.md)); цена своего сценария — бесплатное
  [превью роутинга](https://souz.ai/docs/channels.md). Сумма сценария — оценка; она может уточняться по
  выполненным запросам сопоставимого объёма. Ставки за токены, секунды или символы
  описывают цену единицы объёма, а оценка сценария — ожидаемую сумму запроса.
- **Итог** — **фактический объём × цены сработавшего канала на момент приёма запроса**:
  токены (из кэша — по цене кэша, если она есть, иначе как обычный вход), секунды, символы —
  столько, сколько вызов действительно потребовал. Итог есть в каждом ответе: `usage.cost`
  у чата, `price` у завершённой задачи. Пока задача не завершена, `price` — `null`.

> [!IMPORTANT]
> Итог может быть выше цены «от» и цены пресета: первым не всегда идёт самый дешёвый канал,
> а следующий после отказа может стоить дороже. Предел — [потолок цены](https://souz.ai/docs/routing.md#потолок-цены--max_price_multiplier).

## Динамическая цена

Часть каналов считает стоимость по фактическому расходу, который известен только после
вызова (у изображений — текст промпта и референсы на входе, изображение на выходе; у
синтеза речи — токены текста и звука). У такого канала `dynamic: true` (в `rates` каталога
каналов, в `pricing.channels[]`, у опции пресета и у карточки модели), а сумма — оценка для
параметров по умолчанию. Итог — фактический расход × цены канала и может отличаться от
оценки; цены, по которым он считается, — `rates.tokens` в каталоге каналов. Верх
`max_amount_micro` у такой модели — `null`. Оценку своего сценария показывает
[превью роутинга](https://souz.ai/docs/channels.md). Оно учитывает параметры запроса и число референсов;
при достаточном числе сопоставимых выполнений оценка уточняется по их расходу.
Изменение оценки не меняет ставки `rates.tokens` или условия уже принятого запроса.

## Приём запроса

Запрос принимается, если баланса хватает на самый дешёвый канал с учётом запросов, которые
ещё выполняются; иначе `402 insufficient_balance`. У чата длину ответа определяет доступная сумма с учётом овердрафта:
хватает на весь ответ (`max_tokens` или предел модели) — запрос уходит как есть; хватает
меньше, но не меньше чем на 1000 токенов, — модели передаётся граница ответа по
оплачиваемому (ответ может закончиться `finish_reason: "length"`); не хватает и на это —
`402`.

## Баланс и согласованный овердрафт

Без согласованного овердрафта баланс не становится отрицательным. При подключённом
овердрафте можно продолжать работу до его исчерпания; пополнение погашает использованную
сумму. Итог выше доступной суммы — разницу покрывает Союз. В `price` и `usage.cost` — фактически
списанная сумма. Закрытое соединение вызов не отменяет: ответ дочитывается и списывается по
факту.

## Баланс и пополнение

`GET /v1/balance` возвращает `available_micro` (баланс), `overdraft_limit_micro`
(согласованный лимит), `spendable_micro` (доступно для новых запросов) и
`spent_total_micro` (потрачено за всё время: сумма списаний за успешные запросы, обновляется
в течение минуты).
`GET /v1/balance` и `GET /v1/balance/history` — ключом управления. Пополняют владелец и
администратор в кабинете; бонус расходуется первым и не возвращается
([Аккаунт и команда](https://souz.ai/docs/account.md)).

У аккаунта без баланса (`has_balance: false` в `GET /v1/auth/me`) расход учитывается по факту
в `GET /v1/usage` и `GET /v1/usage/summary`; баланс, его история, пополнение и оплата отвечают
`403 account_without_balance`. Лимиты ключей и участников действуют.

---

Оглавление документации: https://souz.ai/llms.txt. Всё руководство одним файлом: https://souz.ai/llms-full.txt. Справочник методов: https://souz.ai/docs/api-reference.md.