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

Ошибка 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

Один и тот же сбой выглядит по-разному в зависимости от того, через какую поверхность вы вызываете модель. Страница ошибок 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) | generateContent | 400 | Ключ недействителен | Нет | Создать новый ключ в Google AI Studio |
authentication | Interactions API | 401 | Ключ отсутствует, недействителен или просрочен | Нет | Проверить ключ |
failed_precondition | Interactions API | 400 | Не выполнено условие, например отключена оплата | Нет | Проверить статус биллинга проекта |
parameter_unknown | Interactions API | 400 | Неизвестный параметр | Нет | Убрать параметр |
payment_required | Interactions API | 402 | Закончился баланс Prepay | Нет | Пополнить счёт или включить автопополнение |
permission_denied | Interactions API | 403 | У ключа нет прав на ресурс | Нет | Проверить права ключа и доступ к проекту |
model_not_found | Interactions API | 404 | Модель не найдена: опечатка или отключённый ID | Нет | Исправить ID или взять другую модель |
rate_limit_exceeded | Interactions API | 429 | Превышен лимит в минуту или секунду | Да | Ждать и повторять с бэкоффом |
quota_exceeded | Interactions API | 429 | Исчерпана суточная квота | Только после сброса | Ждать сброса или запросить увеличение |
too_many_requests | Interactions API | 429 | Слишком много запросов за короткое время | Да | Ждать и повторять с бэкоффом |
RESOURCE_EXHAUSTED | generateContent | 429 | Любой из лимитов выше или лимит расходов за 10 минут | Да, с пределом | Прочитать message: какой лимит сработал |
api_error | Interactions API | 500 | Непредвиденная ошибка сервера | Да | Повторить; если не проходит — в поддержку |
service_unavailable / UNAVAILABLE | обе | 503 | Сервис перегружен или недоступен | Да | Бэкофф, затем резервная модель |
deadline_exceeded | Interactions API | 504 | Запрос не уложился в срок | Да | Убрать или увеличить таймаут клиента |
cancelled | Interactions API | 499 | Клиент сам разорвал соединение | — | Действий не нужно |
finishReason: IMAGE_SAFETY / image_safety | обе | 200 | Изображение заблокировано политикой безопасности | Нет | Переписать промпт |
finishReason: NO_IMAGE / no_image | обе | 200 | Модель не смогла сгенерировать изображение | Не тем же промптом | Уточнить промпт, явно попросить картинку |
promptFeedback.blockReason: OTHER | generateContent | 200 | Промпт заблокирован по неуказанной причине | Нет | Упрощать промпт и искать триггер |
Коды, которых нет в таблице 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 — 401authentication. Если ключ попал в открытый доступ, 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-preview | 25 июня 2026 года | gemini-3-pro-image |
gemini-3.1-flash-image-preview | 25 июня 2026 года | gemini-nano-banana-2.1 |
gemini-2.5-flash-image-preview | 15 января 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

Блокировки безопасности — самые запутанные ошибки 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 без изображения.
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 г..
Источники11
Внешние страницы, на которые ссылается это руководство, в порядке упоминания. Последнее обновление: 8 окт. 2026 г..
- 1.устранения неполадок Gemini APIai.google.dev/gemini-api/docs/troubleshooting
- 2.ошибок Gemini APIai.google.dev/gemini-api/docs/api-errors
- 3.страница цен Gemini APIai.google.dev/gemini-api/docs/pricing
- 4.страницу статуса Gemini API в Google AI Studioaistudio.google.com/status
- 5.страницы лимитов Gemini APIai.google.dev/gemini-api/docs/rate-limits
- 6.Google AI Studioaistudio.google.com
- 7.страница биллинга Gemini APIai.google.dev/gemini-api/docs/billing
- 8.список регионов, где доступны Gemini API и Google AI Studioai.google.dev/gemini-api/docs/available-regions
- 9.странице прекращения поддержки Gemini APIai.google.dev/gemini-api/docs/deprecations
- 10.настроек безопасности Gemini APIai.google.dev/gemini-api/docs/safety-settings
- 11.форуме разработчиков Google AIdiscuss.ai.google.dev





