GET /v1/balance

Этот эндпоинт только для чтения возвращает баланс кошелька и наиболее ограничивающий настроенный Usage Limit для предъявленного ключа. Нужны активный API-ключ с неистёкшим сроком действия и действующие права аккаунта, домена и IP. Нулевой баланс и исчерпанный Usage Limit не запрещают этот запрос.

Запрос

curl https://api.model-gate.com/v1/balance \
  -H "Authorization: Bearer mg_live_..."

Ответ

{
  "object": "balance",
  "currency": "USD",
  "balance": "12.34",
  "key": {
    "limit": "100.0000000000",
    "usage": "30.0000000000",
    "remaining": "70.0000000000",
    "limit_source": "key"
  }
}

Существующие поля object, currency и balance сохраняют свой смысл. balance — кошелёк расчётного владельца в USD, представленный десятичной строкой; незначащие конечные нули могут отсутствовать. Новый объект key описывает квоту, а не отдельный кошелёк или гарантированно доступную сумму расходов. Его значения сумм, отличные от null, передаются десятичными строками с десятью знаками после точки. В финансовом коде сохраняйте точные строки, не преобразуя их в двоичные числа с плавающей точкой.

Выбор Usage Limit

Участвуют только положительные настроенные лимиты ключа и группы. Для каждого такого счётчика остаток равен max(0, limit - usage):

Все три числа относятся к одному выбранному источнику. Когда limit_source равен "group", поле usage содержит совокупное использование группы, а не отдельного ключа. Например, при остатке ключа 6 и остатке группы 3 возвращаются значения группы. Источник выбирается по остатку квоты, а не по меньшему настроенному лимиту.

Исчерпанный или превышенный настроенный лимит возвращает "0.0000000000"; переключения на другой счётчик или кошелёк не происходит. Фактическое использование сохраняется и при превышении лимита. Если лимитов нет, ответ может содержать:

{
  "key": {
    "limit": null,
    "usage": "3.5000000000",
    "remaining": null,
    "limit_source": null
  }
}

Здесь null означает, что ни один Usage Limit не настроен. Это не нулевой баланс и не неограниченный кредит аккаунта. У ключей и групп независимые сбрасываемые счётчики использования; расходы за всё время не подставляются вместо usage. Разрешённый сброс использования может изменить выбранный источник при следующем запросе.

Кошелёк и квота независимы

Кошелёк не ограничивает key.remaining. Оценка использования может рассчитываться по пользовательской или официальной цене с настроенным множителем, отдельно от фактического списания с кошелька. Эндпоинт показывает сохранённые счётчики без пересчёта между этими оценками. Поэтому в первом примере остаток квоты 70 остаётся равным 70, хотя в кошельке находится 12.34 USD.

Ответ отражает записанные значения кошелька и использования. Незавершённая работа и завершённые запросы, ожидающие расчёта, могут ещё не учитываться. Этот GET-запрос не резервирует деньги, а возвращённые числа не гарантируют выполнение будущего запроса. Для API продолжают действовать обычные проверки кошелька, ключа/группы, модели, частоты запросов и доступа.

Видимость Business

Для ключа Individual кошелёк принадлежит владельцу ключа. Для Business списания идут из кошелька владельца компании. Общий баланс возвращается только пользователю ключа с финансовым правом уровня компании: владельцу организации, администратору или разрешённой роли billing. Ключи сотрудников без такого права получают HTTP 403 от всего эндпоинта, включая объект key. Проектная роль или знание ключа не предоставляют право видеть кошелёк компании.

Ошибка аутентификации

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key."
  }
}

Недостаточно прав Business

{
  "error": {
    "type": "permission_error",
    "code": "balance_not_permitted",
    "message": "Company balance is not available for this credential principal."
  }
}