Баланс и списание в API

Как идёт расчёт

Списание устроено так же, как в чате на сайте. Баланс общий, запросы по ключу и запросы из чата тратят одни и те же TOK.

1. Перед обращением к модели epicai оценивает худший случай. Берутся входные токены, оценённые по длине текста с запасом, плюс max_tokens на ответ, и всё умножается на цены модели. Получается сумма резерва.
2. Если доступных TOK меньше этой суммы, запрос получает 402 insufficient_funds. К модели он не уходит, и ничего не списывается.
3. Резерв держится на балансе, пока запрос выполняется. Доступный остаток на сайте уменьшается так же, как при вопросе в чате.
4. Когда ответ готов, epicai считает сумму по числам из usage и списывает её. Остаток резерва освобождается.

Если процесс на стороне epicai оборвался, резерв снимается автоматически, при следующем запросе этого аккаунта или общей очисткой резервов сайта.

Резерв и max_tokens

Сумма резерва зависит от того, сколько ответа вы разрешили. Без max_tokens epicai закладывает 8192 токена ответа, а для моделей с рассуждениями 16384. При цене ответа 1 200 000 TOK за миллион это почти 9 830 TOK только под ответ, хотя реальный ответ может стоить копейки. Если на балансе меньше, придёт 402. Для короткого ответа задайте max_tokens с запасом, и резерв сократится в разы, например 300 токенов дают около 360 TOK под ответ.

Совет

Картинка во входе закладывается в резерв как 2000 токенов. У Claude запас на вход больше. Оценка грубая и всегда с запасом, а итог считается по факту.

Сколько списано

Сумма лежит в ответе, в поле epic.cost_tok и в заголовке x-epic-cost-tok. В потоковом ответе заголовка нет, число приходит в последнем кадре при include_usage. Сумма округляется вверх до целого TOK, ценовая акция модели, если она есть, уже учтена. Если вендор не прислал расход (например, поток оборвался), epicai считает токены сам по тексту, и в этом случае сумма приблизительная.

У моделей со встроенным платным поиском вендор берёт отдельную плату за поисковые запросы. Она входит в сумму, и поэтому итог таких запросов бывает выше, чем следует из токенов.

Задачи с медиа

Картинки, видео, музыка, озвучка, расшифровка и документы оплачиваются иначе, чем текст. Цена задачи известна до запуска, её даёт POST /v1/quote (подробнее о цене задач). При создании epicai резервирует эту сумму целиком. Если задача завершилась успешно, резерв становится списанием, если нет, резерв снимается. Окончательная сумма лежит в price.charged задачи и в заголовке x-epic-cost-tok адресов формы OpenAI. В отчёте GET /v1/usage такие задачи учитываются по моделям и дням, а счётчики токенов модели (input_tokens, output_tokens) у них нулевые.

Что оплачивается при сбое

Ситуация	Списание
Запрос отклонён до модели (ключ, лимиты, ошибка в теле, нехватка TOK)	Нет
Вендор вернул ошибку или не ответил, поток не начался	Нет
Ответ получен целиком	Да, по фактическому расходу
Поток начался и прервался ошибкой	Да, за уже отданную часть
Вы закрыли соединение в потоке	Да, за доставленную часть
Вы закрыли соединение в потоке до первого токена ответа	Нет
Вы закрыли соединение, не дожидаясь обычного ответа без потока	Да, запрос доводится до конца
Задача с медиа завершилась статусом failed	Нет, резерв снят
Задача с медиа принята, а вы перестали её опрашивать	Да, при успехе: задача доводится до конца, файлы ждут 7 суток

Баланс и состояние ключа

Запрос GET /v1/account отдаёт баланс источника, из которого платит ключ, и сведения о самом ключе.

{
  "object": "account",
  "balance": {"tokens": 125000, "reserved": 0, "available": 125000, "source": "personal"},
  "key": {
    "id": 7,
    "name": "Бот поддержки",
    "prefix": "sk-epic-AbCdEf",
    "created": 1793092837,
    "expires_at": null,
    "rate_limit_rpm": 60,
    "cap_day": 0,
    "cap_month": 0,
    "spent_today": 629,
    "spent_month": 629,
    "webhook_secret": "whsec_…"
  }
}

В balance лежат tokens (весь баланс), reserved (зарезервированная часть) и available (доступное для новых запросов). Поле source равно personal у личного ключа и organization у ключа организации, тогда рядом есть organization_id. В key время создания дано в секундах Unix, а spent_today и spent_month считаются в TOK по Москве. Нулевые cap_day и cap_month означают отсутствие потолка. Поле webhook_secret нужно для проверки подписи вебхуков, работу с ним разбирает статья Вебхуки. Храните его так же бережно, как сам ключ.

Расход за период

Запрос GET /v1/usage суммирует расход всех ключей аккаунта в том же пространстве, личном или организации. Параметры необязательны.

Параметр	Значение
from, to	Даты вида 2026-10-25 включительно, по Москве. По умолчанию последние 30 дней до сегодняшнего. Период не длиннее 92 дней
group_by	day (по умолчанию), model или key

{
  "object": "usage",
  "from": "2026-10-25",
  "to": "2026-10-27",
  "group_by": "model",
  "total": {"calls": 43, "errors": 7, "input_tokens": 3231, "output_tokens": 1421, "cached_tokens": 0, "cost_tok": 629},
  "data": [
    {"model": "vendor/model-name", "model_id": 107, "calls": 16, "errors": 3, "input_tokens": 1760, "output_tokens": 924, "cached_tokens": 0, "cost_tok": 354}
  ]
}

Токены в input_tokens, output_tokens и cached_tokens принадлежат модели, а cost_tok выражен в TOK. Статистика считает запросы, дошедшие до резервирования. Отказы раньше (неверный ключ, ошибка в теле, предел запросов) в неё не попадают. Неверная дата или группировка даёт 400 invalid_parameter с именем поля в param.

На сайте списания видны в истории операций со строкой «API» и названием модели.