Учёт расходов

Как проверить запросы, токены и списания, сопоставить данные по ключу и модели и сверить расход.

AI Gateway учитывает фактические вызовы через собственный журнал операций и события списания. Проверять расход нужно в двух разделах кабинета: Использование показывает отдельные учтённые запросы, а Аналитика собирает их в графики и сводки. Финансовый итог подтверждается проведённым списанием с баланса, а не самостоятельным пересчётом токенов из ответа модели.

Формат ответа API зависит от пути, модели и поставщика. Поэтому приложение не должно ожидать, что каждый обычный или потоковый ответ обязательно содержит единый объект usage, поля cost, cost_details, сведения о кэше или итоговую статистику в последнем SSE-событии. Для проверки расходов используйте кабинет AI Gateway.

Данные об использовании

После вызова модели AI Gateway получает фактические данные операции от шлюза, связывает их с организацией и API-ключом, применяет тариф модели и формирует событие использования. Учитываться могут следующие составляющие:

input_uncached — входные токены без чтения и записи кэша;
output — обычные выходные токены;
reasoning — токены рассуждения, если поставщик и модель передали их отдельно;
cache_read — токены, прочитанные из кэша;
cache_write — токены, записанные в кэш.

Не каждая модель и не каждый вызов дают все пять составляющих. Нулевое или отсутствующее значение не следует трактовать как ошибку: поставщик мог не поддерживать эту составляющую или не передать её для конкретной операции.

В данных поставщика итоговый выход иногда уже включает токены рассуждения, а итоговый вход — токены кэша. При внутреннем сопоставлении AI Gateway разделяет такие значения, чтобы не посчитать одну и ту же часть дважды. Пользователю для контроля достаточно сравнивать итог кабинета и доступную разбивку, а не повторять внутреннее преобразование самостоятельно.

Формат данных

В журнале использования одна строка соответствует учтённой операции. В текущем интерфейсе видны:

Поле в кабинете	Что означает
Время	время создания строки журнала, показанное в часовом поясе браузера
Модель	публичный `model_id` и поставщик
API-ключ	название и безопасный префикс ключа либо сокращённый ID
Токены	общий объём и видимая разбивка на `input`, `output`, `reasoning`
Стоимость	учтённая стоимость операции в рублях
Ledger	идентификатор связанного финансового списания или отметка, что его нет

Над таблицей находятся итоговый расход, число токенов и событий, текущий баланс и лимиты расходов по ключам. Там же есть сводки по датам, ключам и моделям. В блоке разбивки отдельно показаны Input uncached, Output и Reasoning.

Внутренний контракт строки содержит больше технических полей, включая external_operation_id, billing_status, ledger_entry_id, снимок тарифа и наблюдаемые составляющие кэша. Но текущая таблица не выводит все эти поля пользователю. Не стройте рабочий процесс на скрытых полях и не ожидайте, что ID операции всегда можно скопировать из кабинета.

Журнал и аналитика: в чём разница

Использование — операционный журнал. Он нужен, когда требуется найти конкретный вызов и проверить его модель, ключ, токены, стоимость и связь со списанием. Доступные фильтры интерфейса:

даты «С» и «По»;
точный api_key_id;
точный model_id.

Страница загружает до 50 последних строк выбранного набора. Границы дат для этого журнала передаются в UTC, что прямо отмечено в интерфейсе. Если вызов произошёл около полуночи, учитывайте разницу между UTC и местным временем.

Аналитика — агрегированная картина расходов. Она использует часовой пояс Europe/Moscow и позволяет выбрать 7, 30, 90 дней или собственный период, а также отфильтровать данные по API-ключу. В разделе доступны:

затраты, число запросов и токенов;
доля входных токенов из кэша и средняя цена на 1 млн токенов;
сравнение с предыдущим периодом;
ведущие API-ключи и поставщики;
динамика по моделям и ключам;
разбивка токенов на вход, выход и рассуждение;
соотношение кэшированных и некэшированных входных токенов.

Текущий кабинет не предоставляет выгрузку этого журнала или аналитики в CSV. Для исторической проверки используйте фильтры страниц; не рассчитывайте на отдельный пользовательский Analytics API, Data API или маршрут /generation.

Оба раздела организации доступны администратору. Обычный участник организации не получает доступ ко всей организационной статистике. Управление ролями описано в руководстве по организациям.

Разбивка стоимости

Стоимость начисляется в рублях по опубликованному тарифу конкретной модели и поставщика. Актуальные варианты моделей и цены смотрите в каталоге кабинета и на странице цен.

Для каждой учтённой операции AI Gateway сохраняет снимок применённых ставок на момент расчёта. Стоимость складывается из наблюдаемых тарифицируемых составляющих: input_uncached, output, reasoning, cache_read и cache_write. Составляющая попадает в расчёт только тогда, когда она поддерживается выбранной моделью и фактически присутствует в операции.

Поля ответа модели могут быть полезны для технической телеметрии приложения, но не являются самостоятельным финансовым документом. Нельзя получить авторитетную сумму простым умножением prompt_tokens и completion_tokens на сегодняшнюю цену: тариф мог отличаться в момент запроса, а вход, кэш и рассуждение могли учитываться отдельными классами.

Фактическая стоимость поставщика — внутренняя часть маршрутизации. Она не равна списанию клиента и не должна выводиться или использоваться вместо тарифа AI Gateway.

Небольшие суммы рассчитываются с точностью выше копейки, а финансовое списание проводится в рублях и копейках. Поэтому отдельная очень короткая операция может не совпасть с ручным округлением каждого класса. Для финансовой сверки ориентируйтесь на проведённые записи расхода.

Исторические данные в кабинете

Для проверки прошлой операции не нужен отдельный запрос по ID генерации:

Откройте Использование.
Укажите диапазон дат с запасом вокруг времени вызова.
Введите точный ID API-ключа и model_id, если они известны.
Найдите строку по времени, модели, ключу и близкому объёму токенов.
Проверьте стоимость и наличие связанного Ledger.
Откройте Аналитику, выберите соответствующий московский период и тот же ключ.

Если строка появилась недавно, данные агрегатов могут обновиться не одновременно с завершением клиентского ответа. На странице аналитики есть кнопка «Обновить»: она запускает получение доступных данных использования по ключам организации. Это не обещание мгновенной синхронизации и не фиксированный срок обновления.

Сверка расхода

Надёжная сверка начинается с собственных безопасных метаданных запроса. Записывайте:

время с часовым поясом;
публичный model из тела запроса;
путь API;
название или ID ключа без его секретного значения;
HTTP-статус;
request ID или внешний ID операции, только если он действительно присутствует в доступном ответе или заголовке.

Затем выполните проверку по порядку:

Найдите строку в журнале по периоду, ключу и модели.
Сопоставьте время, путь из своей телеметрии, модель и доступные токены. Одного совпадения времени недостаточно, чтобы доказать связь двух событий.
Проверьте стоимость и наличие проведённого списания Ledger.
В аналитике выберите тот же ключ и период в московском времени.
Проверьте общий расход и баланс в разделе Биллинг.

Если значения не совпали, сначала исключите разницу часовых поясов, неверный ID ключа, другой вариант модели и задержку получения или обновления данных. Не складывайте повторные попытки только по близким временным меткам: каждая фактическая операция проверяется отдельно.

Запрос, отклонённый до обращения к поставщику, может не появиться как оплаченный вызов. Ошибки 400, 401 и другие отказы нельзя автоматически считать списанными. И наоборот, если поставщик уже принял операцию, а клиент не получил ответ из-за сетевого сбоя или обрыва потока, отсутствие результата у клиента само по себе не доказывает отсутствие расхода. Авторитетны учтённая операция и проведённое списание. Подробнее о диагностике читайте в руководствах по ошибкам API и потоковым ответам.

Если после обновления данные всё ещё не находятся, обратитесь в поддержку. Передайте время с часовым поясом, путь, публичный model, HTTP-статус, название или ID ключа и доступный идентификатор операции. Не отправляйте полный API-ключ, заголовок Authorization, тело с чувствительными данными или секреты поставщика.

Примеры

Базовый контроль после запроса

Выберите точный model_id в разделе моделей и подставьте его в переменную. Пример не рассчитывает на наличие usage или стоимости в теле ответа:

export AI_GATEWAY_API_KEY="<ВАШ_API-КЛЮЧ>"
export AI_GATEWAY_MODEL_ID="<MODEL_ID_ИЗ_КАБИНЕТА>"

date -u +"%Y-%m-%dT%H:%M:%SZ"

curl https://route.smartaipack.ru/v1/chat/completions \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$AI_GATEWAY_MODEL_ID\",
    \"messages\": [
      {\"role\": \"user\", \"content\": \"Ответь одним коротким предложением.\"}
    ]
  }"

date -u +"%Y-%m-%dT%H:%M:%SZ"

После ответа сохраните HTTP-статус и границы времени теста, затем:

найдите операцию в Использовании по датам и модели;
при нескольких похожих строках добавьте фильтр по api_key_id;
сравните токены и стоимость строки;
убедитесь, что для платной операции указан связанный Ledger;
проверьте изменение сводки за тот же период в Аналитике.

Если вы только начинаете работу с API, сначала пройдите быстрый старт. Для безопасной эксплуатации также полезны инструкции по лимитам и смене API-ключей.

Проверка потока и агрегации

Для потокового запроса фиксируйте отдельно время начала, время получения первого фрагмента и завершение или обрыв соединения. Не ожидайте обязательный объект usage в последнем SSE-событии. После завершения:

Найдите одну фактическую операцию в журнале.
Проверьте модель, ключ, токены, стоимость и Ledger.
В аналитике выберите тот же ключ и период.
Убедитесь, что операция учтена в числе запросов и сумме затрат.

Повтор после обрыва может создать вторую фактическую операцию и дополнительный расход. Учитывайте каждую попытку отдельно и следуйте правилам из статьи о потоковых ответах.

Польза

Разделение журнала и аналитики помогает решать разные задачи:

находить конкретный дорогой или необычный запрос;
сравнивать расход моделей и API-ключей;
видеть изменение числа запросов, токенов и затрат;
оценивать влияние кэша по доступным данным;
сверять техническую активность с балансом организации;
замечать повторные попытки и неожиданные источники расхода.

Такой подход полезен и при разработке, и после запуска: сначала видна отдельная операция, затем её вклад в общий период.