Как узнать цену модели через GET /v1/models

В ответе GET /v1/models у каждой модели лежит три объекта, отвечающих за деньги: pricing, billing и access. Ещё месяц назад разбираться в них было незачем — все позиции считались одинаково, за токены. Сегодня в каталоге сорок моделей и три разные схемы оплаты одновременно: за токены, фиксированно за изображение и с нулевой ставкой после квалифицирующего пополнения. Код, который читает только input_rub_per_million, на половине каталога получит null и посчитает, что модель бесплатная. Разбираем все поля по порядку, чтобы счёт и отказы не оказались неожиданностью.

Три схемы в одном каталоге

Сначала карта, чтобы было понятно, о чём речь.

Ключевое: набор заполненных полей зависит от схемы. Это не «у одних цена больше, у других меньше» — это разные структуры данных в одном массиве.

Поле, с которого надо начинать

pricing.unit — первое, что должен прочитать ваш код. Оно определяет всё остальное.

per_million_tokens — оплата за токены. Заполнены input_rub_per_million и output_rub_per_million, обе в рублях за миллион.

image — оплата за готовое изображение. Полей с ценой за миллион нет вообще, вместо них by_size_and_quality — вложенный объект с ценой за каждую комбинацию размера и качества.

Типичная ошибка выглядит так: код читает pricing.input_rub_per_million, получает undefined, приводит к нулю и показывает пользователю «бесплатно». На моделях изображений это неверно — там цена есть, просто лежит в другом месте.

Как устроена цена за изображение

Разберём на живом примере, потому что структура вложенная.

У gpt-image-2 объект by_size_and_quality содержит три размера, у каждого — три уровня качества:

Разброс внутри одной модели — от 2,5 до 8 ₽. То есть «сколько стоит картинка» без указания размера и качества вопрос бессмысленный.

Проверять, какие комбинации вообще допустимы, надо в capabilities: там лежат массивы sizes и qualities. Запрос с размером, которого нет в списке, вернёт unsupported_parameter. Как считать бюджет на серию изображений, разбирали отдельно в материале про стоимость картинки через API.

Объект billing

Здесь два поля, которые стоит читать.

usage_tokens_required — нужно ли считать токены для счёта. У текстовых моделей true, у моделей изображений false. Удобный признак, если вы строите общий учёт расходов: по нему сразу видно, применима ли токенная арифметика.

source — откуда берётся ставка. Значение qualified_free означает, что модель считается по нулевой ставке при выполнении условия, а само условие описано в access.

Ещё одно поле, formula, содержит человекочитаемое описание вроде «zero charge after confirmed paid top-up». Оно для людей, а не для парсинга: полагаться на его текст в коде не стоит.

Объект access — самое неочевидное

Это новый объект, и именно он чаще всего ломает ожидания.

policy: "balance_required" — нужен положительный баланс, и всё. Так у моделей GPT Image: requires_paid_topup равно false, minimum_paid_topup_rub равно нулю.

policy: "paid_topup_required" — нужны подтверждённые пополнения на сумму не меньше minimum_paid_topup_rub. Так у моделей FLUX: порог 100 ₽.

И самое важное поле во всей конструкции — welcome_bonus_qualifies. У FLUX оно false, и это значит, что приветственные и промоакционные начисления порог не закрывают. Баланс может быть положительным, а доступа не будет.

Отказ в этом случае приходит с кодом paid_topup_required — отдельным, не совпадающим с insufficient_balance. Если ваш обработчик ошибок их не различает, пользователю покажется, что у него кончились деньги, хотя дело в другом. Подробности условий — в разборе бесплатной генерации через FLUX.

Где ещё прячется расход

Три вещи, которые в объект pricing не входят, но на счёт влияют.

Служебный контекст маршрута. Поле billing.estimated_route_context_tokens показывает, сколько токенов добавляется к вашему запросу сверх того, что вы отправили. Разброс по каталогу больше чем на порядок: от 2000 у Gemini до 9500 у линейки Opus, а у gpt-oss-120b там вообще null. На коротких запросах эта надбавка может весить больше самого запроса — механику разбирали в материале про то, почему prompt_tokens больше отправленного.

Асимметрия входа и выхода. У 35 текстовых моделей из 36 ставка одинакова в обе стороны, но исключение есть: у qwen-3-6-35b-a3b выход дороже входа ровно в семь раз. Код, складывающий все токены в одну сумму, на этой позиции ошибётся кратно. Разбор — в статье про асимметричную цену выхода.

Отсутствие кэша. У всех текстовых моделей prompt_cache.status равен unsupported. Если ваш расчёт бюджета опирался на скидку за повторно отправляемый контекст, её тут нет, и структура промпта на цену не влияет.

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

Порядок проверки перед запросом

Четыре шага, которые стоит зашить один раз и не думать о них дальше.

1. Прочитайте protocols для того маршрута, который зовёте. Закрытый протокол отклонит запрос до всякого биллинга — бесплатно, но всё же отклонит.
2. Прочитайте pricing.unit и выберите ветку разбора: токены или изображения.
3. Прочитайте access.policy. Если paid_topup_required, проверьте, что пользователь порог закрыл, до того как отправлять запрос.
4. Обрабатывайте paid_topup_required отдельно от insufficient_balance. Это разные ситуации с разными действиями пользователя.

Эффективные ставки для конкретного аккаунта отдаёт GET /v1/balance — поле effective_pricing_endpoint в pricing прямо на него указывает. Каталог показывает базовые значения.

Чего мы не утверждаем

Схемы могут добавиться. Ещё месяц назад была одна, сейчас три. Код, который жёстко перечисляет варианты unit, придётся править.

Цены в этой статье — на 16 августа. Актуальные всегда в живой выдаче.

Кэш промптов не поддерживается нигде. У всех 36 текстовых моделей prompt_cache стоит unsupported, и скидки за повторный контекст нет.

Мы не описываем поля, которых не проверяли. Если поле встречается в выдаче, но его смысл не документирован в llms.txt, мы его не толкуем.

Каталог показывает базовые ставки, а не ваши. Персональные условия, если они есть, отдаёт GET /v1/balance — на него указывает поле effective_pricing_endpoint.

Одна проверка, которая ловит большинство ошибок

Если делать что-то одно, делайте это.

Возьмите свой код разбора каталога и прогоните через него все модели из живой выдачи, а не те две-три, что вы используете. Затем посмотрите, у скольких получилась цена «ноль» или «не определено».

На сегодняшнем каталоге правильный ответ — ноль позиций с неопределённой ценой. Четыре модели изображений имеют цену в by_size_and_quality, две из них нулевую по условию доступа, остальные тридцать шесть — ставку за миллион. Если ваш разбор показывает что-то другое, он молча ошибается уже сейчас, просто на моделях, которые вы пока не вызываете.

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

Что держать в голове

В каталоге три схемы оплаты одновременно, и набор заполненных полей зависит от pricing.unit. Код, написанный под одну схему, на остальных молча ошибётся — чаще всего в пользу «бесплатно», что хуже всего.

Минимальная защита: читать unit перед разбором цены, читать access.policy перед отправкой запроса и различать paid_topup_required и insufficient_balance в обработчике ошибок.

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

Как мы проверяем факты и почему у каждого стоит дата — на странице о проекте. Полный контракт API — в документации, ключ заводится за минуту: keydealer.ru/login.