Баланс ключа
/v1/balanceСколько денег на аккаунте ключа: начислено, потрачено, остаток.
Ответы
Response
{
"object": "balance",
"granted": 100.0,
"spend": 37.42,
"balance": 62.58,
"currency": "USD"
}Подробности
Нужен ключ в заголовке Authorization: Bearer или x-api-key.
Баланс считается по одной формуле: начислено − расход по тексту − эффективный расход по медиа. Поэтому в ответе три числа и валюта:
granted — сумма всех начислений на аккаунт; spend — суммарный расход, текст и медиа одним числом; balance — остаток, то есть granted минус spend; currency — всегда USD.
Важное про spend: в медийную часть входит не только списанное, но и зарезервированное под генерации, которые ещё идут. Резерв освобождается, когда джоба завершилась (и превращается в списание) или провалилась (и деньги вернулись). Из-за этого balance после постановки генерации в очередь падает сразу, а не в конце — иначе можно было бы поставить десять генераций на деньги, которых хватает на одну.
Деградация, о которой лучше знать заранее. Если наше хранилище недоступно, форма ответа не меняется, но granted берётся из бюджета аккаунта, в котором медиа уже вычтено; пока бюджет синхронизирован, balance получается тот же. Если недоступна сама проверка ключа и остатка, ручка отвечает 502 и не отдаёт никакого числа: отсутствие ответа честнее выдуманного остатка.