Gemini Image API: ключ, предоплата $5, модели и код на Python

На 5 октября 2026 года в Gemini API картинки делают три модели: Nano Banana 2 Lite (gemini-3.1-flash-lite-image), Nano Banana 2 (gemini-3.1-flash-image) и Nano Banana Pro (gemini-3-pro-image). Ключ в Google AI Studio создаётся бесплатно, но бесплатного вывода изображений нет ни у одной из них: генерация работает только на платном уровне, а для него нужна предоплата не меньше $5. Самая дешёвая картинка стоит $0,0336 (Lite, 1K), картинка Pro в 4K — $0,24.

Прежде чем подключать оплату, проверьте регион. Россия не входит в список стран, где доступны Gemini API и Google AI Studio, а пользоваться AI Studio можно только с 18 лет. Официального пути из России у Google нет.

Код ниже повторяет формы запросов из руководства Google по генерации изображений (обновлено 23 сентября 2026 года) и при подготовке материала не запускался. Прогоните его на своём ключе, прежде чем встраивать в продакшен. Если же нужно не создавать картинки, а распознавать или описывать готовые, это другая функция — «понимание изображений» (image understanding) с отдельной документацией.

Модели Gemini для картинок на октябрь 2026: три ID и что уже отключено

Google советует начинать с Nano Banana 2: это основная модель с балансом цены, скорости и качества. Lite берите, когда важнее всего цена и задержка, а Pro — для сложных инструкций, локализации текста на картинке и точного соблюдения фирменного стиля.

Цены — со страницы тарифов Gemini API по состоянию на 4 октября 2026 года.

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

• gemini-3-pro-image-preview и gemini-3.1-flash-image-preview отключены 25 июня 2026 года; замена — те же ID без -preview.
• gemini-2.5-flash-image, первая Nano Banana за $0,039, отключена 2 октября 2026 года.
• Все модели Imagen 4 (imagen-4.0-generate-001, -ultra- и -fast-) отключены 17 августа 2026 года; Google предлагает вместо них gemini-3.1-flash-image. Вместе с Imagen ушёл и параметр personGeneration: у моделей Gemini такого переключателя нет.

Если вы раньше работали с Imagen 4 и хотите понять, на что переходить, подробности — в разборе замены Imagen 4 на Nano Banana 2 или Pro.

Как получить ключ Gemini API и включить оплату для картинок

Ключ бесплатный, оплачивается использование. Порядок такой:

1. Войдите в Google AI Studio и создайте ключ API; при создании он привязывается к проекту Google Cloud.
2. Откройте раздел оплаты в AI Studio и привяжите к проекту платёжный аккаунт. Новые аккаунты с 23 марта 2026 года по умолчанию работают по предоплате (Prepay): Google попросит внести минимум $5.
3. Сохраните ключ в переменной окружения, а не в коде: export GEMINI_API_KEY="...". SDK google-genai подхватывает её сам.

Когда баланс предоплаты доходит до нуля, перестают работать все ключи во всех проектах этого платёжного аккаунта, а запросы возвращают HTTP 402 Payment Required, пока вы не пополните счёт. Неиспользованные кредиты сгорают через 12 месяцев и не возвращаются, кроме случая перехода на постоплату (документация по оплате).

Три частых заблуждения:

• Песочница AI Studio бесплатно картинки не рисует. При выборе Nano Banana 2 или Lite без ключа AI Studio просит перейти на оплату по запросам или на подписку Google AI.
• Пробные $300 Google Cloud не подходят. С марта 2026 года расходы на Gemini API из программы Free Trial исключены.
• На платном уровне ваши запросы не используются для улучшения продуктов Google — в отличие от бесплатного, где в таблице тарифов стоит «Yes».

Подробнее о том, что осталось бесплатным, а что нет, — в статье «Gemini Image API бесплатно? Нет: картинки от $0,0336 за штуку».

Первая картинка на Python: google-genai и Interactions API

Сейчас для Python нужен пакет google-genai (from google import genai). Старый google-generativeai с genai.configure() и genai.GenerativeModel() в текущей документации Google не используется, и примеры на нём — главный признак устаревшего руководства.

pip install google-genai
export GEMINI_API_KEY="ваш_ключ"

Руководство Google пишет примеры для Interactions API: модель получает input, а картинка приходит в interaction.output_image в виде base64.

import base64
from google import genai

client = genai.Client()  # ключ берётся из GEMINI_API_KEY

interaction = client.interactions.create(
    model="gemini-3.1-flash-image",
    input="Фотография керамической кружки на деревянном столе, мягкий свет из окна",
)

if interaction.output_image is None:
    print("Картинки в ответе нет:", interaction.output_text)
else:
    with open("mug.png", "wb") as f:
        f.write(base64.b64decode(interaction.output_image.data))

Чтобы переключиться на другую модель, достаточно поменять model. Для Pro цена выше и в счёт попадают токены размышления, поэтому для черновиков удобнее Nano Banana 2.

Редактирование по фото: текст и изображение в одном запросе

Для правки готовой картинки передайте во input список из текстовой части и изображения в base64. Google напоминает, что у вас должны быть права на загружаемые фото, а результат не должен вводить в заблуждение, преследовать или причинять вред — это часть политики запрещённого использования.

import base64
from google import genai

client = genai.Client()

with open("room.png", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode("utf-8")

interaction = client.interactions.create(
    model="gemini-3.1-flash-image",
    input=[
        {"type": "text", "text": "Замени только диван на зелёный бархатный. Остальное оставь без изменений."},
        {"type": "image", "data": image_b64, "mime_type": "image/png"},
    ],
)

with open("room-edited.png", "wb") as f:
    f.write(base64.b64decode(interaction.output_image.data))

Следующую правку можно делать в том же диалоге: передайте previous_interaction_id=interaction.id и новую инструкцию, и модель будет работать с предыдущим результатом. Google называет многошаговый диалог рекомендуемым способом доводить картинку. У Lite эта возможность слабее: модель не оптимизирована под пошаговое редактирование.

Размер и пропорции картинки: response_format и imageConfig

По умолчанию модель выдаёт 1K. Пропорции совпадают с входным изображением, а без него получается квадрат 1:1. Размер пишется с заглавной K (1K, 2K, 4K): строчное 1k API отклоняет.

В Interactions API размер и пропорции задаются в response_format:

interaction = client.interactions.create(
    model="gemini-3-pro-image",
    input="Постер джазового фестиваля, крупная надпись JAZZ NIGHT",
    response_format={"type": "image", "aspect_ratio": "16:9", "image_size": "4K"},
)

Привычный метод generateContent тоже описан в справочнике API: там те же настройки лежат в generationConfig.imageConfig (aspectRatio, imageSize), а нужные типы ответа — в responseModalities. Пример через curl:

curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Иконка приложения погоды, плоский стиль"}]}],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "1:1", "imageSize": "2K"}
    }
  }' > response.json

Картинка в таком ответе лежит в candidates[0].content.parts[] — в части с полем inlineData.data (base64). Если нужны собственные настройки фильтров безопасности (safetySettings), берите generateContent: в Interactions API их нельзя задать.

Что поддерживает каждая модель:

• Pro: 10 пропорций — 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9; размеры 1K, 2K, 4K.
• Nano Banana 2: те же 10 пропорций плюс 1:4, 4:1, 1:8, 8:1; размеры 512 px (в generateContent значение 512), 1K, 2K, 4K.
• Lite: 10 пропорций, только 1K.

Точные пиксели у Pro по таблице Google:

4096×4096 бывает только у квадрата. Полная таблица всех пропорций и разбор, когда 4K стоит своих денег, — в материале Nano Banana Pro 4K: точные размеры и цена.

Сколько референсов можно передать: до 14 изображений

Модели Gemini 3 принимают до 14 референсных изображений в одном запросе, но лимиты по типам отличаются:

В анонсе Nano Banana 2 Google писал о «пяти персонажах и 14 объектах»; для кода ориентируйтесь на таблицу из руководства для разработчиков, приведённую выше. Каждый референс оплачивается как входные токены: у Pro одно изображение — 560 токенов, примерно $0,0011.

Цена за картинку в Gemini API и Batch: от $0,0336 до $0,24

Цена зависит от модели и размера. Batch API обрабатывает задания асинхронно (целевой срок — до 24 часов) и стоит вдвое дешевле. Ниже цены по состоянию на 4 октября 2026 года.

В таблице только выходная картинка. Сверху добавляются входной текст и референсы, а у Pro ещё и текст с размышлениями ($12 за 1 млн токенов). Поиск Google внутри генерации даёт 5 000 бесплатных запросов в месяц на все модели Gemini 3.x, дальше — $14 за 1 000.

Сколько картинок даёт минимальная предоплата $5 (делим $5 на цену и округляем вниз): 148 картинок Lite, 74 картинки Nano Banana 2 в 1K, 37 картинок Pro в 1K/2K или 20 картинок Pro в 4K.

Batch-задание собирается из обычных запросов в форме generateContent, только с актуальным ID модели:

from google import genai

client = genai.Client()

requests = [
    {"contents": [{"parts": [{"text": f"Товарное фото стула, вариант {i}, белый фон"}]}],
     "config": {"response_modalities": ["TEXT", "IMAGE"]}}
    for i in range(1, 4)
]

job = client.batches.create(
    model="gemini-3-pro-image",
    src=requests,
    config={"display_name": "chairs-batch"},
)
print(job.name)  # статус проверяйте через client.batches.get(name=job.name)

Встроенные запросы подходят для небольших пакетов до 20 МБ; для больших Google рекомендует файл JSONL. Как считать счёт за пакет и где Batch проигрывает, разобрано в материале о стоимости Nano Banana Pro Batch API. Цены Nano Banana 2 по всем разрешениям собраны в статье о ценах Nano Banana 2 API, а тарифы Pro — в обзоре стоимости Gemini 3 Pro Image API.

Если нужна фиксированная цена за вызов вместо оплаты по токенам, есть сторонний шлюз LaoZhang API: по его публичному прайсу на 24 сентября 2026 года gemini-3-pro-image стоит $0,09 за вызов при любом размере от 1K до 4K, а gemini-3.1-flash-image — $0,055. Для Pro в 4K это на 62,5 % дешевле Standard ((0,24 − 0,09) / 0,24), но Pro в 1K/2K через Batch ($0,067) всё равно дешевле. Учтите условия шлюза: ответ HTTP 200 без картинки тоже списывается как вызов, размер и пропорции задаются только через маршрут в формате Gemini (OpenAI-совместимый маршрут отдаёт 1:1 в 1K). Запросы уходят в модель Google, поэтому её правила безопасности действуют так же.

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

Те же модели доступны и через Vertex AI с теми же ставками за токены, но с авторизацией через Google Cloud. Чем отличается настройка, описано в статье Nano Banana API в Vertex AI.

Лимиты запросов для картинок: на проект, IPM и уровни оплаты

Лимиты Gemini API считаются на проект, а не на ключ: второй ключ в том же проекте квоту не увеличит. Для моделей изображений есть отдельное измерение — изображения в минуту (IPM), оно работает вместе с запросами в минуту и в день. Дневной счётчик обнуляется в полночь по тихоокеанскому времени.

Уровень проекта зависит от оплаты (страница лимитов):

Лимит расходов применяется не ко всем аккаунтам: это зависит от истории оплаты. Переход на Tier 1 происходит сразу после настройки оплаты, на следующие уровни — в течение примерно 10 минут после выполнения условий. Конкретные числа RPM и IPM для текущих моделей изображений на странице лимитов не напечатаны (в её таблице остались preview-модели). Смотрите свои значения в AI Studio. Как читать эти лимиты и искать причину ошибки 429, разобрано в статье о лимитах Gemini API.

Ошибки 402, 429 и ответ без картинки: что проверить

402 Payment Required. Закончилась предоплата на платёжном аккаунте. Пополните баланс; до этого ключи всех связанных проектов не работают.

429 RESOURCE_EXHAUSTED. Превышен один из лимитов проекта (RPM, RPD, IPM) или лимит расходов за 10 минут. Подождите и повторите с нарастающей паузой, снизьте параллельность; если упираетесь постоянно, запросите повышение лимита.

400 и «модель не найдена». Проверьте ID: preview-версии, gemini-2.5-flash-image и Imagen 4 отключены. Частая мелочь — строчная k в размере. Неудачные запросы с ошибками 400 и 500 не оплачиваются, но расходуют квоту.

Ответ пришёл, а картинки нет. Тогда смотрите причину в ответе generateContent:

• promptFeedback.blockReason — заблокирован сам промпт: SAFETY, OTHER, BLOCKLIST, PROHIBITED_CONTENT, IMAGE_SAFETY;
• finishReason у кандидата — остановлена генерация: IMAGE_SAFETY, IMAGE_PROHIBITED_CONTENT, IMAGE_OTHER, NO_IMAGE, SPII, SAFETY, PROHIBITED_CONTENT, OTHER.

Настраиваемые фильтры (safetySettings) у текущих моделей по умолчанию и так выключены, а встроенная защита от тяжёлого вреда не настраивается вовсе. Поэтому BLOCK_NONE не снимает блокировки IMAGE_SAFETY или PROHIBITED_CONTENT — это вывод из документации Google по настройкам безопасности. Попытки обойти фильтры сами нарушают политику Google и могут привести к ограничению доступа. Разбор по шагам: blockReason OTHER в Nano Banana 2, что настраивается в фильтрах Nano Banana Pro и почему API не возвращает изображение.

Помните про водяной знак: во все сгенерированные изображения встраивается невидимый SynthID. Видимый значок Gemini — настройка приложения Gemini, к API он не относится.

Частые вопросы о Gemini Image API

Можно ли получить Gemini API key бесплатно? Да, ключ в Google AI Studio бесплатный, а у части текстовых моделей есть бесплатный уровень с ограниченными лимитами. Генерация изображений этим ключом заработает только после привязки оплаты и предоплаты от $5.

Как оплатить Gemini API для генерации картинок? Через раздел оплаты в Google AI Studio: привяжите платёжный аккаунт Google Cloud к проекту и внесите предоплату. Оплата идёт по факту использования, по ценам из таблицы выше. Россия в список поддерживаемых регионов Gemini API не входит.

Работает ли ещё gemini-2.5-flash-image? Нет, эта модель отключена 2 октября 2026 года. Ближайшая замена по цене — Nano Banana 2 Lite (gemini-3.1-flash-lite-image, $0,0336 за 1K), по возможностям — Nano Banana 2 (gemini-3.1-flash-image).

Чем Interactions API отличается от generateContent для картинок? Это два интерфейса к одним и тем же моделям. Новое руководство Google написано для Interactions API (input, response_format, output_image, диалог через previous_interaction_id). generateContent остаётся в справочнике, используется в Batch API и позволяет задать safetySettings.

Обзор всех способов получить картинки от Gemini, включая приложение без API, — в статье «Генерация изображений в Gemini: инструкция для приложения и API».