Перейти к основному содержанию

Ошибки Nano Banana Pro: коды API, что повторять и как исправить

Ошибка Nano Banana Pro в API: 429 и 5xx повторяйте с бэкоффом, 400, 402 и 403 исправляйте, 404 — обычно отключённый ID, HTTP 200 без картинки — блокировка.

LaoZhang AI TeamОпубликованоОбновлено 18 мин чтения
Содержание
Диагностика ошибок Nano Banana Pro по коду ответа, квотам и блокировкам безопасности

Ошибка Nano Banana Pro в Gemini API решается по двум признакам: HTTP-коду и полям ответа. Временные ошибки — 429 (лимит), 408 и 5xx (перегрузка или сбой у Google) — повторяют с экспоненциальной задержкой и ограниченным числом попыток. 400, 401, 402 и 403 повтором не лечатся: нужно исправить запрос, ключ, оплату или права. 404 model_not_found почти всегда означает, что код отправляет отключённый preview-ID. А ответ HTTP 200 без изображения — это блокировка или отказ модели, который виден в finishReason и promptFeedback.blockReason; тот же промпт повторять бессмысленно.

Обновление от 8 октября 2026 года: таблица кодов приведена к странице ошибок Gemini API и разделена по поверхностям (Interactions API и классический generateContent); убраны неверные лимиты «15 RPM на бесплатном уровне» и RPM по подпискам Google AI — у моделей изображений бесплатного уровня нет; правила повторов исправлены с учётом того, что generate_content в Python SDK сам не повторяет запросы; резервной моделью вместо устаревшей Nano Banana 2 стала Nano Banana 2.1; добавлены ошибки 402, 404 для отключённых preview-ID и параметры, которые 2.1 не принимает; убран совет обходить региональные ограничения.

Какие ошибки Nano Banana Pro повторять, а какие исправлять

Короткое правило по данным страницы устранения неполадок Gemini API (по состоянию на 8 октября 2026 года): повторять только временные ошибки — 429, 408 и 5xx — с экспоненциальной задержкой, случайным разбросом (jitter) и максимальным числом попыток. Не повторять 400, 402 и 403: это неверный ключ, исчерпанный предоплаченный баланс или ошибка в запросе.

  • 429 — сработал лимит. Поминутный лимит проходит сам, суточная квота сбрасывается в полночь по тихоокеанскому времени, лимит расходов считается по скользящему окну в 10 минут. Подробности — в разделе про 429 ниже.
  • 503 и другие 5xx — проблема на стороне Google. Повтор с задержкой, затем резервная модель, например Nano Banana 2.1, или очередь.
  • 400, 401, 403 — неверный параметр, ключ или права. Исправить и отправить заново.
  • 402 payment_required — закончился предоплаченный баланс. Google прямо пишет: не повторять, пока не пополнен счёт.
  • 404 model_not_found — неверный или отключённый ID модели. Заменить ID.
  • HTTP 200 без изображения — IMAGE_SAFETY, NO_IMAGE, SAFETY или blockReason: OTHER. Менять промпт, а не повторять его.

Таблица кодов ошибок: Interactions API и generateContent

Схема выбора следующего шага по HTTP-коду и полям ответа Gemini API

Один и тот же сбой выглядит по-разному в зависимости от того, через какую поверхность вы вызываете модель. Страница ошибок Gemini API (обновлена 20 сентября 2026 года) описывает коды Interactions API: в теле ответа приходит {"error": {"code": "invalid_request", "message": "..."}}, где code — строка в snake_case, а HTTP-статус стоит в самом ответе. Классический REST-метод generateContent, который вызывает client.models.generate_content в Python SDK, по-прежнему возвращает числовой code и статус в стиле gRPC в поле status: INVALID_ARGUMENT для 400, RESOURCE_EXHAUSTED для 429, UNAVAILABLE для 503. Например, 8 октября 2026 года запрос к generateContent с недействительным ключом вернул 400 с текстом «API key not valid», а в Interactions API тот же случай описан как authentication 401.

Что вы видитеПоверхностьHTTPПричинаПовторять?Что сделать
invalid_request / INVALID_ARGUMENTобе400Неверный формат запроса или параметрНетСверить параметры с документацией модели
API key not valid (статус INVALID_ARGUMENT)generateContent400Ключ недействителенНетСоздать новый ключ в Google AI Studio
authenticationInteractions API401Ключ отсутствует, недействителен или просроченНетПроверить ключ
failed_preconditionInteractions API400Не выполнено условие, например отключена оплатаНетПроверить статус биллинга проекта
parameter_unknownInteractions API400Неизвестный параметрНетУбрать параметр
payment_requiredInteractions API402Закончился баланс PrepayНетПополнить счёт или включить автопополнение
permission_deniedInteractions API403У ключа нет прав на ресурсНетПроверить права ключа и доступ к проекту
model_not_foundInteractions API404Модель не найдена: опечатка или отключённый IDНетИсправить ID или взять другую модель
rate_limit_exceededInteractions API429Превышен лимит в минуту или секундуДаЖдать и повторять с бэкоффом
quota_exceededInteractions API429Исчерпана суточная квотаТолько после сбросаЖдать сброса или запросить увеличение
too_many_requestsInteractions API429Слишком много запросов за короткое времяДаЖдать и повторять с бэкоффом
RESOURCE_EXHAUSTEDgenerateContent429Любой из лимитов выше или лимит расходов за 10 минутДа, с пределомПрочитать message: какой лимит сработал
api_errorInteractions API500Непредвиденная ошибка сервераДаПовторить; если не проходит — в поддержку
service_unavailable / UNAVAILABLEобе503Сервис перегружен или недоступенДаБэкофф, затем резервная модель
deadline_exceededInteractions API504Запрос не уложился в срокДаУбрать или увеличить таймаут клиента
cancelledInteractions API499Клиент сам разорвал соединение—Действий не нужно
finishReason: IMAGE_SAFETY / image_safetyобе200Изображение заблокировано политикой безопасностиНетПереписать промпт
finishReason: NO_IMAGE / no_imageобе200Модель не смогла сгенерировать изображениеНе тем же промптомУточнить промпт, явно попросить картинку
promptFeedback.blockReason: OTHERgenerateContent200Промпт заблокирован по неуказанной причинеНетУпрощать промпт и искать триггер

Коды, которых нет в таблице Google, по правилу той же страницы превращаются в snake_case-версию HTTP-статуса. 502 в таблице не указан, но страница устранения неполадок относит все 5xx к временным ошибкам, поэтому 502 обрабатывают так же, как 500 и 503. Если вы видите HTTP 200, но картинки нет, разбор полей ответа — в статье Nano Banana не генерирует изображение в API: как найти причину, а полный алгоритм отладки шаг за шагом — в руководстве по устранению неполадок Nano Banana Pro.

503 и другие 5xx: сбой на стороне Google и переход на 2.1

5xx означает, что запрос дошёл до Google и не был обработан там: перегрузка (503), внутренняя ошибка (500), таймаут (504). В коде ничего исправлять не нужно; нужно правильно ждать и иметь запасной путь. Google не публикует ни долю ответов 503, ни типичное время восстановления, поэтому проценты и «обычно 5–15 минут» из сторонних источников стоит считать единичными наблюдениями. Редкие коды, которые здесь не разобраны, описаны в справочнике по кодам ошибок Nano Banana Pro.

503 UNAVAILABLE («The model is overloaded») — самая частая серверная ошибка в часы пик. Рекомендованная Google стратегия — экспоненциальная задержка: подождать около секунды, затем 2, 4, 8 секунд, добавляя случайный разброс, чтобы все клиенты не повторяли одновременно. После двух-трёх неудач разумно переключить запрос на другую модель изображений. Для Nano Banana Pro (gemini-3-pro-image) такой резервной моделью теперь служит Nano Banana 2.1 (gemini-nano-banana-2.1): она стабильна в Gemini API с 6 октября 2026 года, и Google рекомендует её для всех новых проектов вместо Nano Banana 2 (gemini-3.1-flash-image), которая объявлена устаревшей без даты отключения. Что умеет 2.1 и сколько стоит — в обзоре Nano Banana 2.1: цена от $0,0336, а чем она отличается от Pro на задачах с текстом — в сравнении Nano Banana 2.1, Pro и GPT Image 2.5.

Переход на 2.1 при перегрузке ещё и дешевле. Стандартная цена Gemini API на 8 октября 2026 года: Pro — $0,134 за изображение 1K или 2K и $0,24 за 4K, 2.1 — $0,0336 за 1K, $0,0504 за 2K и $0,113 за 4K, плюс токены размышления, которые у 2.1 оплачиваются отдельно (страница цен Gemini API). Компромисс — в качестве: в том же сравнении на девяти промптах (1K, по одной генерации на промпт, 8 октября 2026 года) Pro сохраняла заданный текст на картинке, а 2.1 в трёх текстовых задачах изменила формулировку.

500 api_error — непредвиденная ошибка сервера. Тот же запрос часто проходит со второй попытки, поэтому подходит обычный бэкофф с пределом попыток. Если 500 и 503 идут сериями, проверьте страницу статуса Gemini API в Google AI Studio: возможно, это общий инцидент, а не проблема вашего запроса.

504 deadline_exceeded — запрос не уложился в срок. Генерация 4K или с высоким уровнем размышления занимает десятки секунд, и короткий таймаут клиента обрывает её раньше сервера. Google советует убрать собственный срок или увеличить его, чтобы действовал серверный.

Если в ответе вы видите черновые изображения с пометкой thought: true, это не ошибка, а промежуточные кадры размышления модели; почему они появляются и как их отфильтровать — в статье о временных изображениях Nano Banana.

429 RESOURCE_EXHAUSTED: минутный лимит, суточная квота или расходы

429 означает, что проект упёрся в один из лимитов. В generateContent все варианты приходят как RESOURCE_EXHAUSTED, и различить их можно только по тексту message; Interactions API делит их на три кода. От того, какой лимит сработал, зависит, поможет ли повтор. Подробный разбор с примерами на Python и Node.js — в статье Nano Banana Pro: ошибка RESOURCE_EXHAUSTED и восстановление генерации.

Что известно о лимитах из страницы лимитов Gemini API (обновлена 2 сентября 2026 года):

  • Лимиты считаются на проект, а не на ключ. Второй ключ в том же проекте квоту не добавит.
  • Поминутные лимиты (RPM, TPM, а для моделей изображений ещё IPM — изображений в минуту) снимаются в течение минуты. Это rate_limit_exceeded или too_many_requests: ждать и повторять с бэкоффом.
  • Суточная квота (RPD) сбрасывается в полночь по тихоокеанскому времени. Это quota_exceeded: повтор до сброса не поможет, нужно ждать или запросить увеличение.
  • Лимит расходов за 10 минут — тоже 429 RESOURCE_EXHAUSTED. Для Tier 1 это $10, для Tier 2 — $50, для Tier 3 — $200 по скользящему окну. При $0,24 за кадр 4K у Pro лимит Tier 1 исчерпывается примерно на 41 изображении за 10 минут ($10 / $0,24 ≈ 41,7), без учёта токенов размышления.
  • Конкретные числа RPM и IPM Google не публикует в виде таблицы: актуальные лимиты вашего проекта видны только в Google AI Studio.

Частые повторы без задержки снова упираются в тот же лимит, поэтому начинайте с 1–2 секунд и удваивайте паузу до 60 секунд. Если 429 приходит регулярно при обычной нагрузке, решение — не очередной повтор, а более высокий уровень или Batch API. Как работают уровни и форма запроса лимита — в статье Квота Nano Banana Pro API: как увеличить; какой именно лимит сработал по тексту ошибки — в разборе ошибки 429 Gemini при генерации изображений.

400, 401, 402, 403: ключ, оплата и права — повтор не поможет

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

400 INVALID_ARGUMENT и «API key not valid»

400 — структурная проблема запроса. Сообщение Google обычно называет поле, которое не подошло, поэтому первым делом читайте message. Частые причины для моделей изображений:

  • Недействительный ключ. В generateContent это 400 с текстом «API key not valid», в Interactions API — 401 authentication. Если ключ попал в открытый доступ, Google блокирует его, и ответ звучит так: «Your API key was reported as leaked. Please use another API key.» В обоих случаях нужен новый ключ в Google AI Studio; пошаговая настройка — в руководстве как получить Nano Banana Pro API Key.
  • Слишком длинный контекст. Лимит входа у gemini-3-pro-image — 65 536 токенов (страница модели, обновлена 3 сентября 2026 года), у gemini-nano-banana-2.1 — 131 072. В многоходовом редактировании вся история диалога считается входом, поэтому длинная сессия может получить 400 при коротком текущем промпте.
  • Слишком большой запрос. Встроенные данные (base64 прямо в запросе) ограничены 100 МБ на запрос, для PDF — 50 МБ; файлы крупнее загружают через Files API (до 2 ГБ на файл). Большие референсы лучше заранее уменьшить.
  • Неподдерживаемый параметр модели — например, размер или параметры выборки, которых нет у конкретной модели. Для 2.1 это отдельная тема, разобранная ниже.

failed_precondition (400) в Interactions API означает невыполненное условие, например отключённую оплату проекта: проверьте биллинг, а не промпт.

402 payment_required и лимиты расходов

402 приходит, когда закончился предоплаченный баланс (Prepay). Google пишет прямо: не повторяйте, запрос не пройдёт, пока не пополнен счёт, — пополните баланс или включите автопополнение. Минимальное пополнение Prepay — $5, кредиты сгорают через 12 месяцев (страница биллинга Gemini API, обновлена 28 сентября 2026 года).

С 402 легко спутать месячные потолки расходов. У каждого уровня есть потолок на платёжный аккаунт: $250 для Tier 1, $2 000 для Tier 2, $20 000–$100 000+ для Tier 3; ещё один месячный лимит можно задать на проект в AI Studio (Spend → Monthly spend cap). Эта функция экспериментальная, и Google предупреждает о задержке срабатывания около 10 минут, поэтому небольшой перерасход возможен.

403 и регион: Gemini API в России недоступен

403 permission_denied означает, что у ключа нет прав на ресурс: ключ из другого проекта, ограничения, наложенные на ключ, или нет доступа к проекту. Проверьте, к какому проекту привязан ключ и какие API для него разрешены, затем отправьте простой текстовый запрос к Gemini — так ошибка ключа отделяется от ошибки, связанной с изображениями.

Отдельного кода для неподдерживаемой страны в таблице ошибок Google нет. Нужно смотреть список регионов, где доступны Gemini API и Google AI Studio (обновлён 28 апреля 2026 года): России, материкового Китая и Гонконга в нём нет. Для запросов из России Gemini API и AI Studio официально недоступны, и надёжного способа исправить это на стороне кода нет. Как Google разделяет блокировки контента, лимиты, меры против аккаунта и региональные ограничения — в статье Блокировки Nano Banana Pro: контент, лимиты, аккаунт и регион.

Параметры Nano Banana 2.1: «512», seed и temperature в Vertex AI

Если вы перевели резервную ветку или весь проект на 2.1, часть старых параметров перестаёт работать.

  • Размер 512 у 2.1 не поддерживается. Модель выдаёт только 1K, 2K и 4K; размер 0,5K (512) остался у Nano Banana 2. Что именно ответит Google на 512, в документации не описано, а через LaoZhang API поведение менялось: 7 октября 2026 года такой запрос получал 400 «Image size 512 is not supported for this model» и не оплачивался, 8 октября — возвращал изображение 1K и списывал $0,045. В обоих случаях 512 px вы не получите, поэтому отправляйте 1K.
  • Параметры выборки в Vertex AI. На Vertex AI для gemini-nano-banana-2.1 параметры seed, topK, logprobs, temperature и topP возвращают ошибку API. Уберите их из конфигурации, которую раньше передавали Nano Banana 2 или Pro, и не рассчитывайте на воспроизводимость по seed. Узел ComfyUI для 2.1 по той же причине не отправляет temperature и top_p. Настройка SDK и location для Vertex — в статье Nano Banana API в Vertex AI.
  • Flex. На Vertex AI 2.1 не поддерживает Flex; половинная цена действует для Batch. В документации Flex для Gemini API модели изображений тоже не перечислены, хотя страница цен показывает строки Flex для Pro. Документированный путь к половинной цене для изображений — Batch API.

Примечание: laozhang.ai — наш собственный сервис; его цены — наши тарифы, а не независимое сравнение.

Чем 2.1 отличается от Pro и Nano Banana 2 и когда её выбирать — в статье Nano Banana 2 vs Pro vs 2.1: что выбрать, если NB2 устарела.

404 model_not_found: отключённые preview-ID и чем их заменить

Самая частая причина 404 у моделей изображений в 2026 году — старый preview-ID в коде, туториале или узле ComfyUI. Google советует проверить имя модели или перейти на другую. Отключённые ID по странице прекращения поддержки Gemini API (по состоянию на 8 октября 2026 года):

Старый IDОтключёнЗамена
gemini-3-pro-image-preview25 июня 2026 годаgemini-3-pro-image
gemini-3.1-flash-image-preview25 июня 2026 годаgemini-nano-banana-2.1
gemini-2.5-flash-image-preview15 января 2026 годаgemini-nano-banana-2.1

С исходной Nano Banana (gemini-2.5-flash-image) у Google две разные даты. Таблица прекращения поддержки Gemini API указывает отключение 15 марта 2027 года с заменой на Nano Banana 2 Lite, и Vertex AI называет ту же дату. А страница цен Gemini API всё ещё показывает старое предупреждение о том, что модель «будет отключена 2 октября 2026 года». Если ваш код опирается на эту модель, не полагайтесь ни на одну из дат: переводите вызовы на gemini-3.1-flash-lite-image или gemini-nano-banana-2.1 и держите обработку 404 с переключением на резервную модель.

Nano Banana 2 (gemini-3.1-flash-image) в Gemini API пока отвечает: она устарела, но даты отключения нет. В Vertex AI сроки другие — для Nano Banana 2 и Pro прекращение поддержки намечено не раньше 28 мая 2027 года.

Блокировки SAFETY, IMAGE_SAFETY и OTHER: что документирует Google

Различия между SAFETY, IMAGE_SAFETY и OTHER в ответе API и действия разработчика

Блокировки безопасности — самые запутанные ошибки Nano Banana Pro, потому что ответ приходит с HTTP 200 и редко объясняет причину. Google не публикует «уровневую» схему или список внутренних этапов модерации; он публикует поля и значения, которые возвращает API, и настройки, которые можно менять. Стройте обработку именно на них.

В generateContent finishReason кандидата может быть SAFETY (смотрите safetyRatings), IMAGE_SAFETY, IMAGE_PROHIBITED_CONTENT, IMAGE_RECITATION, IMAGE_OTHER, NO_IMAGE или OTHER, а promptFeedback.blockReason — SAFETY, BLOCKLIST, PROHIBITED_CONTENT, IMAGE_SAFETY или OTHER (справочник API generateContent). В Interactions API те же случаи приходят как коды блокировки генерации — image_safety, image_prohibited_content, image_recitation, image_other — и как ошибка генерации no_image. Для кодов блокировки Google советует изменить вход и отправить заново: повтор того же промпта бесполезен.

Что можно настроить, а что нет, описано на странице настроек безопасности Gemini API (обновлена 17 сентября 2026 года). Настраиваются четыре категории — притеснения, язык вражды, сексуально откровенный и опасный контент; для моделей Gemini 2.5 и 3 порог по умолчанию — Off. Отдельно действует встроенная защита от основных видов вреда, например от контента, угрожающего безопасности детей: она блокирует всегда и не настраивается.

Отсюда практическая разница:

  • finishReason: SAFETY — safetyRatings показывают, какая категория сработала, и порог этой категории можно изменить через safetySettings. BLOCK_NONE ослабляет только эту категорию; снимать OTHER или встроенную защиту он не должен (это вывод из документации, он совпадает с отчётами разработчиков).
  • finishReason: IMAGE_SAFETY или сообщение «generated images may contain unsafe content» — заблокировано сгенерированное изображение. Google не сообщает, какое правило сработало, и не документирует настройку, которая это отключает, поэтому ответ — переписать промпт.
  • blockReason: OTHER — справочник API определяет его одной строкой: промпт заблокирован по неизвестным причинам. Страница устранения неполадок добавляет, что запрос или ответ может нарушать условия использования или просто не поддерживаться. Что проверять и как найти триггер — в руководстве по blockReason OTHER.

Для IMAGE_SAFETY иногда помогают приёмы из практики, которые Google не документирует и успех которых не гарантирован: заменить имена персонажей и отсылки к чужим брендам общими описаниями («принцесса в голубом платье» вместо имени конкретной героини), явно задать стиль («цифровая иллюстрация в акварельной технике») и не сочетать человеческие фигуры с описаниями одежды или поз, которые можно прочитать как изображение несовершеннолетнего. Блокировку определяет собственная защита модели, поэтому шлюз к той же модели Google результат не изменит — менять нужно промпт.

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

Лимиты Gemini API для изображений: уровни Tier 1–3 и где смотреть RPM

Бесплатного уровня у моделей изображений в Gemini API нет: в столбце Free Tier страницы цен у Pro, Nano Banana 2, 2.1 и Lite стоит «Not available». Любая таблица с «15 RPM бесплатно» для генерации изображений неверна. Подписки Google AI Pro и Ultra квоту API не добавляют: это лимиты приложения Gemini, а API работает по уровням проекта.

Уровни зависят от суммарных расходов в Google Cloud на платёжном аккаунте, к которому привязан проект (страница лимитов Gemini API, обновлена 2 сентября 2026 года):

УровеньКак получитьМесячный потолок аккаунтаЛимит расходов за 10 минут
FreeАктивный проект—— (модели изображений недоступны)
Tier 1Привязать активный платёжный аккаунт$250$10
Tier 2Оплачено $100 и прошло 3 дня с первого платежа$2 000$50
Tier 3Оплачено $1 000 и прошло 30 дней с первого платежа$20 000–$100 000+$200

Чего в таблице нет: RPM, TPM и IPM для каждого уровня Google публикует только в интерфейсе — кнопка «View your active rate limits» ведёт в Google AI Studio, где видны лимиты вашего проекта. Для Batch API отдельные лимиты: в Tier 1 в очередь можно поставить до 2 000 000 токенов для Gemini 3 Pro Image (в таблице модель ещё подписана как Preview). Строки для Nano Banana 2.1 на странице лимитов пока нет.

Если лимиты API мешают постоянно, у Batch API цена вдвое ниже: $0,067 за кадр Pro 1K/2K и $0,12 за 4K. Когда Batch выгоднее поштучных вызовов — в статье Nano Banana Pro Batch API: цена $0,067–$0,12 и расчёт счёта; где посмотреть лимиты и как читать 429 и 402 — в обзоре лимитов Gemini API: уровни Tier 1–3 и ошибки 429. Лимиты в самом приложении Gemini, AI Mode и Flow устроены иначе и разобраны в статье Лимиты Nano Banana Pro: Gemini, AI Mode, Workspace, Flow и API.

Код повторов на Python: HttpRetryOptions и резервная модель 2.1

Главная ловушка в Python: client.models.generate_content в SDK google-genai по умолчанию не повторяет запросы. Страница устранения неполадок пишет, что Python SDK повторяет временные ошибки до четырёх раз, но при проверке на локальном сервере, всегда отвечающем 429 (google-genai 2.28.0, 5 октября 2026 года), generate_content на клиенте по умолчанию отправил один запрос и сразу выбросил исключение. Повторы появились только с http_options=types.HttpOptions(retry_options=types.HttpRetryOptions()). client.interactions.create, напротив, повторил запрос три раза без дополнительных настроек. Если вы вызываете REST напрямую, повторов нет вообще — их пишете вы.

Ниже — функция на google-genai, которая включает повторы SDK только для 408, 429 и 5xx, переключается с Pro на Nano Banana 2.1, если Pro всё ещё отвечает 5xx после всех попыток, сразу возвращает 400, 401, 402, 403 и 404 и отдельно разбирает HTTP 200 без изображения.

python
import logging
import os

from google import genai
from google.genai import errors, types

logging.basicConfig(level=logging.INFO)
log = logging.getLogger("nano_banana")

# generate_content сам не повторяет запросы: без retry_options SDK делает одну попытку.
client = genai.Client(
    api_key=os.environ["GEMINI_API_KEY"],
    http_options=types.HttpOptions(
        retry_options=types.HttpRetryOptions(
            attempts=4,  # всего попыток, включая первую
            initial_delay=1.0,  # секунды; дальше пауза растёт экспоненциально со случайным разбросом
            max_delay=60.0,
            http_status_codes=[408, 429, 500, 502, 503, 504],  # 400, 402, 403 не повторяем
        ),
    ),
)

PRIMARY = "gemini-3-pro-image"        # Nano Banana Pro
FALLBACK = "gemini-nano-banana-2.1"   # рекомендованная Flash-модель вместо устаревшей NB2


def generate(prompt: str, size: str = "2K") -> dict:
    """Pro -> 2.1 при перегрузке; 4xx и блокировки возвращаются без повтора."""
    for model in (PRIMARY, FALLBACK):
        try:
            resp = client.models.generate_content(
                model=model,
                contents=prompt,
                config=types.GenerateContentConfig(
                    response_modalities=["IMAGE"],
                    image_config=types.ImageConfig(image_size=size),  # "1K", "2K" или "4K", не "512"
                ),
            )
        except errors.APIError as e:
            log.warning("%s -> %s %s: %s", model, e.code, e.status, e.message)
            if e.code in (500, 502, 503, 504) and model == PRIMARY:
                continue  # повторы SDK исчерпаны, пробуем резервную модель
            # 429 после всех повторов: поставить задание в очередь.
            # 400/401/402/403/404: исправить запрос, ключ, оплату или ID модели.
            return {"status": "error", "model": model, "code": e.code,
                    "grpc_status": e.status, "message": e.message}

        feedback = resp.prompt_feedback
        if feedback and feedback.block_reason:
            return {"status": "prompt_blocked", "model": model,
                    "reason": getattr(feedback.block_reason, "name", feedback.block_reason)}

        cand = resp.candidates[0] if resp.candidates else None
        parts = cand.content.parts if cand and cand.content and cand.content.parts else []
        # черновики размышления помечены thought=True, это не результат
        images = [p.inline_data.data for p in parts if p.inline_data and not p.thought]
        if images:
            return {"status": "ok", "model": model, "images": images}

        reason = getattr(cand.finish_reason, "name", cand.finish_reason) if cand else "NO_CANDIDATE"
        return {"status": "no_image", "model": model, "reason": reason}  # тот же промпт не повторяем

    return {"status": "error", "detail": "резервная модель тоже недоступна"}

Код проверен на google-genai 1.65.0 против локального тестового сервера, без запросов к Google. Pro, отвечающая 503, получила 4 запроса, после чего ушёл один запрос к 2.1. Ответ 400 «API key not valid» и 404 получили ровно по одному запросу, без повторов. blockReason: OTHER и finishReason: IMAGE_SAFETY вернулись как блокировки, а не как ошибки, которые стоит повторять. Учтите, что повторы SDK не читают рекомендованную сервером задержку; если для 429 она важна, обрабатывайте 429 сами, как в статье про RESOURCE_EXHAUSTED.

Поверх этой функции в рабочей системе обычно нужны ещё три вещи. Первая — очередь с отдельным хранилищем для заданий, которые не прошли ни на одной модели, чтобы обработать их позже, а не показывать пользователю ошибку. Вторая — «предохранитель» (circuit breaker): после серии 503 подряд, например пяти за минуту, на время прекратить запросы к Pro и сразу отправлять трафик на резервную модель. Третья — счётчики ошибок по кодам: рост доли 429 говорит, что пора повышать уровень или переходить на Batch, а всплеск 503 — что идёт перегрузка или инцидент.

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

Не у каждой ошибки Nano Banana Pro есть быстрое решение. Если 503 повторяются каждый вечер, IMAGE_SAFETY не уходит после переписывания промпта или суточной квоты не хватает для продакшена, имеет смысл заложить в архитектуру второй маршрут. Это не отказ от Pro, а защита от того, что одна модель или один провайдер оказывается недоступен.

Самый простой вариант остаётся внутри Gemini API: Pro для основных запросов, Nano Banana 2.1 как резерв при перегрузке, Batch API для того, что может подождать. Если нужна другая модель целиком, сравнение по качеству и работе с текстом — в статье FLUX.2 Pro или Nano Banana Pro: что выбрать.

Второй вариант — шлюз с оплатой за вызов, например LaoZhang API. По его документации по Nano Banana 2.1 на 8 октября 2026 года вызов gemini-3-pro-image стоит $0,09 при любом размере, gemini-nano-banana-2.1 — $0,045 при любом размере и уровне размышления, gemini-3.1-flash-image — $0,055, gemini-3.1-flash-lite-image — $0,025. Для Pro это дешевле стандартной цены Google на 32,8 % при 1K/2K (($0,134 − $0,09) / $0,134) и на 62,5 % при 4K (($0,24 − $0,09) / $0,24). Batch у Google при 1K/2K ($0,067) дешевле шлюза, а при 4K ($0,12) шлюз дешевле на 25 %. Сравнение подписки, API и шлюза — в статье Сколько стоит Nano Banana Pro.

Примечание: laozhang.ai — наш собственный сервис; его цены — наши тарифы, а не независимое сравнение.

У шлюза свои правила ошибок. Каждый ответ HTTP 200 оплачивается как один вызов, даже если изображения нет, поэтому слепые повторы стоят денег. Неверные параметры возвращают 400 и не оплачиваются. Соотношение сторон и размер задаются только на нативном маршруте Gemini (generateContent); маршрут, совместимый с OpenAI, возвращает 1K. Блокировку безопасности шлюз не снимет: модель та же, и IMAGE_SAFETY придёт так же.

Частые вопросы об ошибках Nano Banana Pro

Сколько длится ошибка 429 RESOURCE_EXHAUSTED в Nano Banana Pro?

Зависит от лимита. Поминутный лимит снимается примерно через минуту, суточная квота сбрасывается в полночь по тихоокеанскому времени, а лимит расходов считается по скользящему окну в 10 минут. Повторяйте с паузой от 1–2 секунд с удвоением до 60 секунд и ограничьте число попыток; при суточной квоте повтор до сброса не поможет.

Можно ли отключить фильтр IMAGE_SAFETY в Nano Banana Pro?

Нет: Google не документирует настройку, которая отключает IMAGE_SAFETY. safetySettings действуют на четыре настраиваемые категории, а встроенная защита от основных видов вреда блокирует всегда. Для finishReason: SAFETY можно изучить safetyRatings и изменить порог категории; для IMAGE_SAFETY остаётся переписать промпт — убрать имена персонажей, явно задать объект и стиль. Это приёмы из практики, а не гарантированный способ.

Почему Nano Banana Pro выдаёт «generated images may contain unsafe content»?

Это блокировка на уровне изображения, того же семейства, что finishReason: IMAGE_SAFETY. Google не сообщает, какой классификатор сработал, поэтому сообщение не говорит, в чём причина — в персонаже, реальном человеке или композиции. Перепишите промпт с общим описанием и явным стилем, например «акварельная иллюстрация», а если блокировка повторяется, упрощайте промпт по шагам, чтобы найти триггер.

Чем finishReason SAFETY отличается от IMAGE_SAFETY в Gemini API?

SAFETY значит, что ответ остановлен по одной из настраиваемых категорий: safetyRatings покажут, по какой, и порог можно изменить через safetySettings. IMAGE_SAFETY значит, что заблокировано сгенерированное изображение, правило не называется, и настройки для этого нет — меняют промпт. Ни то ни другое не равно promptFeedback.blockReason: OTHER, который Google определяет как «неизвестные причины».

Почему gemini-3-pro-image-preview возвращает 404?

Preview-ID Nano Banana Pro отключён в Gemini API 25 июня 2026 года, и запросы к нему получают 404 model_not_found. Замените ID на gemini-3-pro-image. Так же отключены gemini-3.1-flash-image-preview и gemini-2.5-flash-image-preview; для них Google указывает замену gemini-nano-banana-2.1.

Можно ли использовать Nano Banana Pro в API бесплатно?

Нет. У моделей изображений в Gemini API бесплатного уровня нет, а подписки Google AI Pro и Ultra квоту API не добавляют. В приложении Gemini бесплатные пользователи генерируют картинки с Nano Banana 2, а переделать изображение в Pro можно с платным планом Google AI. Для России есть ещё одно ограничение: Gemini API и AI Studio в ней официально недоступны. Подробнее — в статье Gemini Image API бесплатно? Нет и в разборе что сейчас бесплатно в Gemini, Flow и API.

Как проверить, работает ли сейчас Nano Banana Pro?

Откройте страницу статуса Gemini API в Google AI Studio. Если инцидентов нет, а 503 продолжаются, отправьте короткий тестовый промпт на gemini-3-pro-image и на gemini-nano-banana-2.1: если отвечает только одна модель, это перегрузка конкретной модели, и пора включать резервную ветку. Сообщения других разработчиков о текущих сбоях публикуются на форуме разработчиков Google AI.

Источники11

Внешние страницы, на которые ссылается это руководство, в порядке упоминания. Последнее обновление: 8 окт. 2026 г..

  1. 1.устранения неполадок Gemini APIai.google.dev/gemini-api/docs/troubleshooting
  2. 2.ошибок Gemini APIai.google.dev/gemini-api/docs/api-errors
  3. 3.страница цен Gemini APIai.google.dev/gemini-api/docs/pricing
  4. 4.страницу статуса Gemini API в Google AI Studioaistudio.google.com/status
  5. 5.страницы лимитов Gemini APIai.google.dev/gemini-api/docs/rate-limits
  6. 6.Google AI Studioaistudio.google.com
  7. 7.страница биллинга Gemini APIai.google.dev/gemini-api/docs/billing
  8. 8.список регионов, где доступны Gemini API и Google AI Studioai.google.dev/gemini-api/docs/available-regions
  9. 9.странице прекращения поддержки Gemini APIai.google.dev/gemini-api/docs/deprecations
  10. 10.настроек безопасности Gemini APIai.google.dev/gemini-api/docs/safety-settings
  11. 11.форуме разработчиков Google AIdiscuss.ai.google.dev
Центр устранения неполадок Nano Banana Pro: коды ошибок, временные изображения и сравнение платформ
Генерация изображений

Устранение неполадок Nano Banana Pro: решение всех кодов ошибок с проверенными методами (2026)

Ошибки API Nano Banana Pro могут нарушить работу вашего конвейера генерации изображений. Это руководство охватывает все коды ошибок (429, 503, 400, 403, 500), объясняет механизм «мышления» с временными изображениями, содержит готовый к продакшену Python-код для обработки ошибок и сравнивает стабильность Gemini API и Vertex AI — всё на основе реальных отчётов разработчиков и официальной документации по состоянию на февраль 2026 года.

25 мин
Три маршрута Nano Banana Pro и проверка доступа, обратной связи и изображения при текстовом отказе
Генерация изображений

Nano Banana Pro пишет `RESTRICTED by System Instructions`? Сначала проверьте маршрут

Сообщение RESTRICTED by System Instructions само по себе не объясняет отказ. Проверьте доступный путь Pro, повторите допустимую задачу и убедитесь, что вернулось изображение, а не только текст.

10 мин