Массовая генерация изображений через API: очередь и бюджет

Массовая генерация изображений через API начинается с трёх вещей: фиксированного режима модели, очереди заданий и бюджета на принятые, а не просто созданные картинки. Для Nano Banana 2 в API429 выходное изображение 1K стоит $0,0201 по публичному каталогу на 9 сентября 2026 года. Стоимость 10 000 таких результатов — $201 без входных токенов, переделок и дополнительных операций.

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

Как выбрать модель и параметры партии

Начните с одного сценария: например, предметная фотография чашки на трёх фонах. Зафиксируйте модель, размер, число результатов и требования к изображению. Для Nano Banana 2 в этом руководстве используется gemini-3.1-flash-image, размер 1024x1024 и одно изображение на запрос.

Наличие модели в публичном каталоге показывает опубликованное предложение. Доступ именно вашего ключа проверяется отдельно через GET /v1/models. Ключ API429 передаётся в заголовке Authorization, базовый адрес — https://gateway.api429.com/v1. Это отдельный шлюз со своим биллингом. Форматы прямого Google API и его тарифы нельзя автоматически переносить на любой маршрут API429.

Если вы выбираете GPT Image, дополнительно задайте качество. Если используете редактирование, уточните поддержку исходного изображения и формат загрузки: создание по тексту и редактирование — разные операции. Конкретные варианты подключения собраны в руководстве Nano Banana API, а нативное направление Google разобрано на странице Vertex AI API.

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

Бюджет на 10 000 изображений

Ставки ниже относятся только к выходному изображению. Они взяты из публичного каталога API429 9 сентября 2026 года. Перед оплатой большой партии проверьте текущие значения.

Это не окончательная стоимость проекта. Добавьте входной текст, референсы, оплачиваемые дополнительные операции, комиссии пополнения, если они применяются, и переделки. Сопоставление одинаковых режимов у других сервисов вынесено в сравнение цен Nano Banana и GPT Image.

Полезно считать две величины:

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

Допустим, после проверки принимается 80% результатов. Для планирования 10 000 принятых картинок понадобится примерно 12 500 генераций. В режиме Nano Banana 2 1K выходные изображения обойдутся в $251,25 вместо $201. Это расчётный сценарий с постоянной долей приёмки, а не измеренный результат API429 или гарантия количества удачных изображений.

Бюджет нельзя жёстко ограничить одной формулой «количество × цена картинки»: остальные операции тоже могут стоить денег. Запускайте работу порциями и сверяйте фактические списания между ними. Лимит задач в примере ниже ограничивает число отправок, но не является лимитом расходов в долларах.

Очередь вместо 10 000 одновременных запросов

Каждая задача должна иметь собственный ID, неизменяемые параметры и сохранённое состояние. Для трёх вариантов одного товара используйте три ID: например, mug-01-white, mug-01-sand, mug-01-blue. Один ID связывает исходное задание с результатом, а не заменяет ключ идемпотентности на стороне сервера.

Рабочий цикл выглядит так:

1. Сохранить задание и отметить отправку до обращения к API.
2. Отправить запрос с ограничением времени ожидания.
3. Сохранить полученный ответ на диск.
4. Извлечь изображение, проверить формат и сохранить файл.
5. Отметить задачу как сохранённую; при следующем запуске пропустить её.
6. Отдельно проверить соответствие картинки заданию и принять либо отклонить результат.

Параллельность выбирайте по измерениям и доступным лимитам. В примере два воркера — осторожная начальная настройка, а не обещанная пропускная способность аккаунта. Сначала проверьте 3–10 запросов, затем небольшую партию и только после этого увеличивайте объём.

Измеряйте медианное время, p95, долю ошибок и фактическую стоимость. Если очереди растут или появляются ограничения, уменьшите параллельность. Десять тысяч запросов в одном массиве без сохранения состояния трудно остановить, восстановить и сопоставить с оплатой.

Что делать при 429, таймауте и ответе 202

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

Таймаут означает, что клиент не получил ответ вовремя. Работа на сервере могла завершиться. Слепой повтор может создать второе изображение и новое списание. Сохраните исходное задание и сведения об ответе; проверьте историю запросов или состояние серверной задачи, если оно доступно для этого маршрута. При неясном результате сначала уточните его через поддержку.

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

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

Пример на Python: сохранение и продолжение партии

Скачать bulk-images.py. Нужен Python 3.10 или новее на macOS/Linux; сторонние библиотеки не используются. По умолчанию скрипт только проверяет задания и показывает план, без обращения к API.

Создайте jobs.jsonl, одна строка — одно задание:

{"id":"mug-01-white","prompt":"Предметная фотография белой керамической чашки на белом фоне, мягкий студийный свет, без текста"}
{"id":"mug-01-sand","prompt":"Предметная фотография белой керамической чашки на песочном фоне, мягкий студийный свет, без текста"}
{"id":"mug-01-blue","prompt":"Предметная фотография белой керамической чашки на голубом фоне, мягкий студийный свет, без текста"}

Сначала проверьте план:

python3 bulk-images.py jobs.jsonl --limit 3

Для отправки запросов задайте ключ в переменной окружения API429_API_KEY. Не добавляйте ключ в файл заданий или репозиторий. Следующая команда создаёт платные генерации:

python3 bulk-images.py jobs.jsonl --limit 3 --workers 2 --out image-run --execute

Скрипт отправляет POST /v1/images/generations с такими параметрами:

{
  "model": "gemini-3.1-flash-image",
  "prompt": "Текст конкретного задания",
  "n": 1,
  "size": "1024x1024",
  "response_format": "b64_json"
}

В папке каждой задачи остаются параметры, исходный ответ, состояние и полученный файл. PNG, JPEG и WebP определяются по сигнатуре, а не по предполагаемому расширению. SHA-256 помогает убедиться, что вы используете тот же сохранённый файл; это не оценка его визуального качества.

Повторите команду с теми же заданиями и той же папкой: существующие состояния будут пропущены. После завершения первого этапа можно увеличить --limit, сохранив прежний порядок строк. Менять ID, промпт, модель или размер — значит создавать новую задачу. Другая выходная папка также не содержит истории предыдущего запуска. Не удаляйте состояние ради «починки» таймаута: это снимает защиту от повторной отправки.

Блокировка не позволяет двум экземплярам скрипта одновременно работать с одной папкой на одном компьютере. Для нескольких серверов нужна общая очередь с атомарным захватом задач и общей базой состояний. Локальные файлы примера не обеспечивают распределённую идемпотентность.

Как перейти от пилота к большой партии

После первых результатов проверьте не только наличие файлов. Для интернет-магазина важны форма товара, отсутствие лишних предметов, соответствие цвета, фон и пригодность для нужного кадрирования. Для рекламных креативов — читаемость, размещение объектов и соответствие конкретному формату. Фиксируйте причины брака: это помогает улучшить запрос вместо повторения той же ошибки в тысячах заданий.

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

Для рабочего сервиса добавьте лимит расходов, остановку очереди при аномалиях, мониторинг, обработку асинхронных результатов и отдельную очередь задач, требующих проверки. Автоматическая загрузка в каталог должна начинаться после приёмки, а не сразу после любого ответа 200.

Массовая генерация и Batch API — одно и то же?

Нет. В этом руководстве используется клиентская очередь отдельных запросов. Серверный Batch API имеет собственные поддерживаемые методы, формат входа, сроки и тариф. Наличие batch-маршрута не означает, что он принимает любую image-модель или даёт скидку прямого Google Batch.

Если вашему процессу нужна асинхронная обработка большой партии, конкретная image-модель или иной формат интеграции, обсудите сценарий с API429 до запуска. Укажите модель, размер, суточный объём, допустимое ожидание и формат результата. Команда сможет проверить текущую поддержку и обсудить недостающую возможность; её наличие и сроки внедрения нельзя предполагать заранее.

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