Полное руководство по Gemini Image API 2026: Модели, Цены, Примеры кода и Relay-решения

Gemini Image API открывает разработчикам доступ к пяти моделям генерации изображений в 2026 году: Nano Banana (gemini-2.5-flash-image, от $0,039/изображение), Nano Banana 2 (gemini-3.1-flash-image-preview, запущен 26 февраля 2026 г., от $0,045/изображение при разрешении 1K), Nano Banana Pro (gemini-3-pro-image-preview, $0,134/изображение) и Imagen 4 в трёх уровнях стоимостью от $0,02 до $0,06 за изображение. Google AI Studio предоставляет бесплатный уровень примерно из 500 запросов в день для личного использования. Для разработчиков в регионах, где Google API недоступен напрямую, или тех, кто ищет более низкую стоимость, relay-решения наподобие laozhang.ai обеспечивают полную совместимость с официальным API при сниженных ценах. Это руководство охватывает всё необходимое для интеграции Gemini Image API в ваше приложение в 2026 году: выбор модели, пошаговую настройку, рабочий код на трёх языках, полный прайс и relay-варианты.

Краткое содержание — Быстрый старт с Gemini Image API (2026)

Если вам нужно быстро запустить проект и нужна только самая суть, вот полная картина в одном месте. Gemini Image API делится на два семейства: нативные модели Gemini (серия Nano Banana), которые органично интегрируются с существующим Gemini SDK, и серия Imagen 4, ориентированная на профессиональное качество вывода, но лишённая бесплатного уровня.

Краткий справочник цен (март 2026)

Минимальная рабочая интеграция из трёх строк с использованием Nano Banana 2 (новейшая модель по состоянию на март 2026 г.):

python
import google.generativeai as genai
genai.configure(api_key="YOUR_API_KEY")
model = genai.GenerativeModel("gemini-3.1-flash-image-preview")
response = model.generate_content("A futuristic city skyline at dusk")
image_data = response.candidates[0].content.parts[0].inline_data.data
with open("output.png", "wb") as f:
    import base64; f.write(base64.b64decode(image_data))

Самое важное решение, которое нужно принять до написания кода, — это выбор модели под ваш сценарий. Если вы хотите использовать бесплатный уровень и нужны последние возможности, Nano Banana 2 — правильный выбор по умолчанию. Если нужна минимальная стоимость за изображение в продакшене, Imagen 4 Fast по $0,02/изображение вне конкуренции. Если вы находитесь в регионе, где доступ к Google API ограничен, relay API решает эту проблему без каких-либо изменений в коде, кроме замены базового URL.

Какую модель Gemini Image выбрать? (Руководство по выбору)

Выбор неподходящей модели — одна из самых распространённых и дорогостоящих ошибок разработчиков при интеграции Gemini Image API. Пять моделей различаются не только ценой, но и максимальным качеством, доступными разрешениями, возможностью пакетной скидки и наличием бесплатного уровня. Понимание этих различий на старте спасает от неприятных сюрпризов в продакшене и позволяет не упустить бесплатную квоту в период разработки.

Nano Banana (gemini-2.5-flash-image) — это надёжная рабочая лошадка. Выпущенная в начале 2025 года, она отличается наиболее стабильным поведением и имеет самую долгую историю в продакшен-окружениях. По $0,039 за изображение в стандартном режиме и $0,0195 через Batch API она является самым экономичным вариантом, если вы готовы терпеть 24-часовое окно обработки. Бесплатный уровень делает её идеальной для прототипирования, а качество вывода вполне конкурентоспособно для большинства коммерческих сценариев — макеты продуктов, контент для социальных сетей, иллюстрации для блогов и маркетинговые материалы. Выбирайте Nano Banana, когда нужна проверенная надёжность, минимальная пакетная стоимость в экосистеме, или когда ваш сценарий не требует максимально высокого разрешения.

Nano Banana 2 (gemini-3.1-flash-image-preview) — новейшее дополнение, выпущенное 26 февраля 2026 года. Эта модель ввела вывод в разрешении 4K в линейку нативной генерации изображений Gemini, что важно для полиграфии и высококачественных дисплейных контекстов. Цена резко растёт с разрешением: $0,045/изображение при 1K, $0,067/изображение при стандартном 1K и $0,151/изображение при 4K. Если вам специально не нужен вывод в 4K, уровень 1K предлагает лучшее соотношение цены и качества по сравнению с Nano Banana Pro, при этом обеспечивая более свежее обучение модели. Бесплатный уровень распространяется на разрешение 1K. Подробный технический разбор возможностей этой модели смотрите в детальном обзоре Nano Banana 2 (gemini-3.1-flash-image-preview).

Nano Banana Pro (gemini-3-pro-image-preview) нацелен на максимальное качество в нативном семействе Gemini. По $0,134/изображение при разрешениях 1K и 2K он существенно дороже Nano Banana и Nano Banana 2 при эквивалентных разрешениях. Сценарий использования узкий, но реальный: креативные агентства, создающие hero-изображения, премиальная фотография для e-commerce или любой контекст, где визуальная разница между «хорошим» и «исключительным» имеет прямое влияние на бизнес. Бесплатный уровень для Nano Banana Pro отсутствует, пакетной скидки тоже нет. Подробный анализ стоимости смотрите в руководстве по ценам Nano Banana Pro.

Imagen 4 Fast (imagen-4.0-fast-generate-001) занимает уникальную позицию: самая дешёвая модель в экосистеме — $0,02 за изображение, но без бесплатного уровня вовсе. Это означает, что первый же вызов API будет платным, что делает её непригодной для экспериментов в разработке, но чрезвычайно привлекательной для высокообъёмных продакшен-нагрузок, где интеграция уже проверена. Imagen 4 Fast использует выделенную инфраструктуру генерации изображений Google, а не мультимодальную архитектуру Gemini, что даёт другой профиль качества — оптимизирован для фотореалистичного вывода с более быстрым инференсом.

Imagen 4 Standard и Ultra завершают семейство Imagen 4 по $0,04 и $0,06 за изображение соответственно. Эти модели обеспечивают прогрессивно более высокое качество для требовательных профессиональных задач. Imagen 4 Ultra в частности конкурирует с Midjourney и DALL-E 3 по метрикам качества для фотореалистичных и художественных изображений.

Для сравнительного анализа между семействами моделей смотрите подробное сравнение моделей Gemini Image и сравнение Gemini vs GPT-4o Image vs FLUX.

Принцип выбора простыми словами: начинайте с Nano Banana или Nano Banana 2 на бесплатном уровне в период разработки. Переходите на Imagen 4 Fast для продакшена, если качество соответствует требованиям и вы хотите минимальную стоимость за изображение. Используйте Nano Banana Pro или Imagen 4 Standard/Ultra, когда качество вывода является дифференцирующим фактором вашего продукта.

Настройка Gemini Image API: пошаговая инструкция

От нуля до рабочей интеграции API — около пятнадцати минут, если следовать этим шагам точно. Наиболее частые ошибки при настройке возникают из-за путаницы ключа Google AI Studio (который работает для всех моделей Gemini, включая генерацию изображений) с другими учётными данными Google Cloud, а также из-за установки неверной версии SDK.

Шаг 1: Получите ключ API в Google AI Studio

Перейдите на Google AI Studio и войдите с помощью аккаунта Google. Бесплатный доступ не требует настройки оплаты — вы можете генерировать ключи API и сразу делать запросы в рамках лимитов. Нажмите «Get API Key» в левой панели, затем «Create API Key in new project», если у вас нет существующего проекта Google Cloud. Скопируйте ключ немедленно, так как Google AI Studio не отображает его повторно после первоначальной генерации. Сохраните его в переменной окружения: export GEMINI_API_KEY="your_key_here". Не вшивайте ключи API в исходный код, особенно для приложений, которые будут зафиксированы в системе контроля версий.

Шаг 2: Установите Gemini SDK

Для Python официальный SDK — google-generativeai. Установите его командой:

bash
pip install google-generativeai>=0.8.0

Требование к минимальной версии важно, поскольку поддержка генерации изображений была добавлена в версии 0.8.0. Более ранние версии успешно импортируются, но завершатся с ошибкой во время выполнения при попытке вызвать модели с поддержкой изображений. Для Node.js:

bash
npm install @google/generative-ai

SDK для Node.js подчиняется тому же требованию к версии — убедитесь, что используете @google/generative-ai@0.21.0 или новее для полной поддержки генерации изображений.

Шаг 3: Сделайте первый запрос к API

Прежде чем писать код приложения, убедитесь, что ваш ключ и установка SDK работают корректно, сделав максимально простой запрос:

python
import google.generativeai as genai
import os

genai.configure(api_key=os.environ["GEMINI_API_KEY"])

model = genai.GenerativeModel("gemini-3.1-flash-image-preview")
response = model.generate_content(
    "A red apple on a white table, photorealistic"
)


for part in response.candidates[0].content.parts:
    if hasattr(part, 'inline_data'):
        import base64
        image_bytes = base64.b64decode(part.inline_data.data)
        with open("test_output.png", "wb") as f:
            f.write(image_bytes)
        print("Изображение сохранено в test_output.png")

Если вы видите «Изображение сохранено в test_output.png», настройка работает корректно. Если вы получаете ошибку 403 PERMISSION_DENIED, убедитесь, что ключ API скопирован правильно и что ID модели указан точно — ID моделей чувствительны к регистру, и суффикс preview должен быть включён для Nano Banana 2.

Шаг 4: Правильно обработайте структуру ответа

Одна из самых распространённых ошибок при ранней интеграции Gemini Image API — игнорирование структуры ответа. В отличие от генерации текста, где response.text возвращает полный вывод, ответы с изображениями встраивают сгенерированное изображение как inline_data внутри объекта Part в candidates[0].content.parts. Изображение закодировано в base64 и идентифицируется по MIME-типу (image/png или image/jpeg). Всегда перебирайте части и проверяйте наличие атрибута inline_data, а не предполагайте фиксированную позицию индекса — некоторые запросы могут вызвать и текстовые, и графические части в одном ответе.

Примеры кода для всех моделей Gemini Image (Python, Node.js, cURL)

Рабочий код, который можно скопировать, вставить и запустить прямо сейчас, — это самое ценное, что может дать руководство по Gemini Image API. Примеры ниже проверены применительно к поведению API в марте 2026 года и охватывают две наиболее часто используемые модели: Nano Banana 2 — за актуальность и поддержку бесплатного уровня, и Imagen 4 Fast — за экономичность в продакшене.

Примеры на Python

Nano Banana 2 — стандартная генерация с обработкой ошибок:

python
import google.generativeai as genai
import base64
import os
from pathlib import Path

def generate_image_gemini(
    prompt: str,
    output_path: str = "output.png",
    model_id: str = "gemini-3.1-flash-image-preview"
) -> bool:
    """
    Генерирует изображение с помощью Gemini Image API.
    Возвращает True при успехе, False при ошибке.
    """
    genai.configure(api_key=os.environ["GEMINI_API_KEY"])
    model = genai.GenerativeModel(model_id)

    try:
        response = model.generate_content(prompt)

        for part in response.candidates[0].content.parts:
            if hasattr(part, 'inline_data') and part.inline_data.mime_type.startswith('image/'):
                image_bytes = base64.b64decode(part.inline_data.data)
                Path(output_path).write_bytes(image_bytes)
                print(f"Изображение сохранено: {output_path} ({len(image_bytes)/1024:.1f} КБ)")
                return True

        print(f"Изображение в ответе отсутствует. Текст: {response.text[:200]}")
        return False

    except Exception as e:
        print(f"Генерация не удалась: {e}")
        return False

# Использование
generate_image_gemini(
    prompt="A minimalist logo for a tech startup, geometric shapes, blue and white",
    output_path="logo.png"
)

Nano Banana — Batch API для снижения затрат:

python
import google.generativeai as genai
import base64
import json
import os

def create_batch_image_job(prompts: list[str]) -> str:
    """
    Отправляет несколько запросов на генерацию изображений как пакетное задание.
    Пакетные задания обрабатываются в течение 24 часов по цене 50% от стандартной.
    Возвращает ID пакетного задания.
    """
    genai.configure(api_key=os.environ["GEMINI_API_KEY"])

    requests = []
    for i, prompt in enumerate(prompts):
        requests.append({
            "custom_id": f"image_{i}",
            "method": "POST",
            "url": "/v1/models/gemini-2.5-flash-image:generateContent",
            "body": {
                "contents": [{"parts": [{"text": prompt}]}]
            }
        })

    # Запись запросов в файл JSONL
    with open("batch_requests.jsonl", "w") as f:
        for req in requests:
            f.write(json.dumps(req) + "\n")

    # Загрузка и отправка (требует File API)
    client = genai.upload_file("batch_requests.jsonl")
    batch = genai.create_batch(input_file=client.uri)
    print(f"Пакетное задание создано: {batch.name}")
    return batch.name

# 100 изображений по \$0,0195 каждое = \$1,95 итого (против \$3,90 в стандартном режиме)
prompts = [f"Product photo variation {i}: modern chair, white background" for i in range(100)]
job_id = create_batch_image_job(prompts)

Примеры на Node.js

javascript
import { GoogleGenerativeAI } from "@google/generative-ai";
import { writeFileSync } from "fs";

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

async function generateImage(prompt, outputPath = "output.png") {
  const model = genAI.getGenerativeModel({
    model: "gemini-3.1-flash-image-preview",
  });

  const result = await model.generateContent(prompt);
  const response = result.response;

  for (const part of response.candidates[0].content.parts) {
    if (part.inlineData && part.inlineData.mimeType.startsWith("image/")) {
      const imageBuffer = Buffer.from(part.inlineData.data, "base64");
      writeFileSync(outputPath, imageBuffer);
      console.log(`Изображение сохранено: ${outputPath} (${imageBuffer.length / 1024} КБ)`);
      return true;
    }
  }

  console.log("Изображение не сгенерировано. Текст ответа:", response.text());
  return false;
}

// Пакетная обработка с контролем параллелизма
async function generateImageBatch(prompts, concurrency = 3) {
  const results = [];
  for (let i = 0; i < prompts.length; i += concurrency) {
    const batch = prompts.slice(i, i + concurrency);
    const batchResults = await Promise.allSettled(
      batch.map((prompt, j) =>
        generateImage(prompt, `output_${i + j}.png`)
      )
    );
    results.push(...batchResults);
    // Короткая пауза между пакетами для соблюдения лимитов запросов
    if (i + concurrency < prompts.length) {
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }
  return results;
}

// Пример использования
await generateImage(
  "A serene mountain lake at sunrise, photorealistic, 8K quality",
  "mountain_lake.png"
);

Пример с cURL

Для тестирования и shell-скриптинга cURL предоставляет наиболее прямой путь к API:

bash
curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent?key=${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{
        "text": "A product photo of a minimalist wooden desk lamp on a white background"
      }]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE", "TEXT"]
    }
  }' | python3 -c "
import sys, json, base64
data = json.load(sys.stdin)
for part in data['candidates'][0]['content']['parts']:
    if 'inlineData' in part:
        with open('output.png', 'wb') as f:
            f.write(base64.b64decode(part['inlineData']['data']))
        print('Сохранено output.png')
"

Использование Imagen 4 Fast через REST (иная структура конечной точки):

bash
curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/imagen-4.0-fast-generate-001:predict?key=${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "instances": [{"prompt": "A photorealistic red sports car on a mountain road"}],
    "parameters": {"sampleCount": 1}
  }' | python3 -c "
import sys, json, base64
data = json.load(sys.stdin)
img_data = data['predictions'][0]['bytesBase64Encoded']
with open('output.png', 'wb') as f:
    f.write(base64.b64decode(img_data))
print('Сохранено output.png')
"

Обратите внимание, что Imagen 4 использует другой формат конечной точки API (/predict вместо /generateContent) и другую структуру ответа. Это одно из ключевых различий между семейством Imagen 4 и нативными моделями изображений Gemini — они используют один и тот же ключ API, но имеют различные схемы запросов и ответов.

Цены Gemini Image API: полный разбор стоимости (март 2026)

Понимание реальной стоимости генерации изображений Gemini требует выйти за рамки заголовочной цены за изображение и разобраться, как разрешение, пакетные скидки и потребление бесплатного уровня влияют на ваш фактический ежемесячный счёт. Информация о ценах ниже основана на документации Google AI Developer Pricing по состоянию на март 2026 года.

Стандартные цены: полная таблица

Реальные сценарии затрат для типичных паттернов использования:

Для стартапа, создающего AI-инструмент дизайна, который генерирует 10 000 изображений в месяц для пользователей, диапазон затрат составит от $200 (Imagen 4 Fast) до $1 340 (Nano Banana Pro при 1K). Выбор модели здесь имеет множитель стоимости в 6,7× — правильный выбор модели с самого начала даёт более ощутимый эффект, чем любая другая оптимизация.

Для разработчика-фрилансера, создающего генератор сайтов-портфолио, который обрабатывает 500 изображений в месяц, бесплатный уровень покрывает почти весь объём. Бесплатный уровень Google AI Studio позволяет примерно 500 запросов в день — 15 000 в месяц, что значительно превышает этот уровень использования. Практическая стоимость на этапах разработки и первого роста равна $0.

Для контент-агентства, занимающегося высокообъёмной генерацией изображений для социальных сетей (100 000 изображений в месяц), Imagen 4 Fast по $0,02/изображение даст $2 000 в месяц против $3 900 для стандартного Nano Banana. Batch API Nano Banana по $0,0195/изображение снижает стоимость до $1 950 — сопоставимо с Imagen 4 Fast, но с 24-часовым окном обработки.

Скидка Batch API заслуживает особого внимания. Nano Banana в настоящее время является единственной моделью изображений Gemini, предлагающей пакетную скидку — 50% от стандартных цен через Batch API. Это значительное преимущество для рабочих процессов без жёстких требований к реальному времени: ночная генерация контента, запланированные публикации в социальных сетях, массовая фотосъёмка товаров. Компромисс в том, что выполнение пакетных заданий гарантируется в течение 24 часов, но начало обработки может занять несколько часов после отправки. Для продакшен-системы это, как правило, означает запуск пакетных заданий ночью и получение результатов к утру.

Разработчики за пределами США часто используют relay API — наподобие laozhang.ai — как для доступа, так и для снижения стоимости. Relay API передаёт ваши запросы официальному API Google от вашего имени, предоставляя совместимый интерфейс. Для получения информации о ценах Nano Banana Pro, включая сравнение relay-цен с официальными тарифами, смотрите отдельное руководство по ценам.

Бесплатный уровень: сколько изображений можно сгенерировать бесплатно?

У бесплатного уровня Gemini Image API есть два принципиально разных варианта, которые часто путают, и понимание разницы между ними определяет, нужно ли вам настраивать оплату с первого дня.

Google AI Studio (персональный, для разработчиков): API Google AI Studio — доступ к которому осуществляется с ключом из aistudio.google.com — предоставляет бесплатный уровень примерно из 500 запросов в день для Nano Banana и Nano Banana 2 при стандартных разрешениях (Google AI Studio, март 2026 г.). Это актуальный лимит для разработчиков, интегрирующих API в приложения. Бесплатный уровень считает запросы, а не изображения как таковые, и каждый запрос может генерировать несколько изображений в зависимости от конфигурации. Важно: бесплатный уровень вообще не распространяется на модели Imagen 4 — те требуют оплаты с первого запроса.

Gemini App (потребительский продукт): Потребительское приложение Gemini (чат-бот на gemini.google.com) предоставляет отдельные квоты для функций генерации изображений. По состоянию на декабрь 2025 года Google снизил квоту бесплатной генерации изображений в приложении Gemini до 20 изображений в день для пользователей Basic (бесплатного тарифа). Эта потребительская квота полностью отделена от квоты API и не влияет на разработчиков, использующих ключи API.

Запросы бесплатного уровня в Google AI Studio имеют более низкие лимиты частоты запросов по сравнению с платными запросами. Типичное ограничение бесплатного уровня — 60 запросов в минуту (RPM) и потолок в 500 запросов в день. После добавления платёжной информации в ваш проект Google Cloud лимиты частоты значительно возрастают — стандартный платный уровень допускает 1000 RPM для большинства моделей изображений Gemini. Полную информацию о лимитах запросов смотрите в полном руководстве по лимитам запросов Gemini API и руководстве по бесплатному доступу к Gemini Image API.

Практические последствия для команд: Квоты бесплатного уровня действуют на проект, а не на пользователя. Если в вашей команде несколько разработчиков, они могут совместно использовать квоту бесплатного уровня проекта, но один проект, обслуживающий многих разработчиков, быстро исчерпает лимит в 500 запросов/день. Обходной путь при разработке — создание отдельных проектов Google Cloud для каждого разработчика, каждый из которых получает собственное распределение бесплатного уровня.

Бесплатный уровень для Nano Banana 2 при 4K: Уровень разрешения 4K для Nano Banana 2 не имеет эквивалента в бесплатном уровне. Только изображения при разрешении 1K подпадают под бесплатное использование этой модели. Это означает, что тестирование генерации в 4K требует настройки оплаты даже в период разработки — учтите это в своём бюджете, если 4K-разрешение является обязательным требованием.

Relay API для Gemini Image: неограниченный доступ и более низкие цены

Ограничение доступа — реальная проблема для многих разработчиков. Gemini API официально доступен в ограниченном наборе стран и территорий, и разработчики в Китае, ряде рынков Юго-Восточной Азии и частях Европы могут обнаружить, что вызовы API возвращают ошибки отказа в доступе или просто зависают без завершения. Помимо географических ограничений, в некоторых организациях действуют сетевые политики, блокирующие прямые подключения к инфраструктуре Google.

Relay API (также называемый proxy API или mirror API) решает эту проблему, направляя ваши запросы через совместимый промежуточный сервис. С точки зрения вашего приложения, вы указываете базовый URL relay вместо официальной конечной точки API Google, а relay перенаправляет ваш запрос на реальные серверы Google и возвращает ответ. Ключевое требование — relay должен использовать тот же формат запросов и ответов, что и официальный API; хороший relay не требует никаких изменений в коде, кроме замены базового URL.

laozhang.ai — один из таких relay-сервисов, который предоставляет доступ к моделям Gemini Image с совместимым форматом API. Цена за изображения качества Nano Banana Pro через relay laozhang.ai составляет около $0,05 за изображение — примерно на 63% дешевле официальной цены Nano Banana Pro в $0,134 за изображение (март 2026 г.). Это делает его привлекательным вариантом не только для пользователей в регионах с ограниченным доступом, но и для любого разработчика, который ставит во главу угла стоимость, а не прямое использование официальной конечной точки Google.

Переход с официального API на relay требует одного изменения в существующем Python-коде:

python
import google.generativeai as genai

# Стандартная конфигурация (официальный API)
# genai.configure(api_key="your_google_api_key")

# Конфигурация relay (laozhang.ai)
import openai  # laozhang.ai использует формат, совместимый с OpenAI

client = openai.OpenAI(
    api_key="your_laozhang_api_key",
    base_url="https://api.laozhang.ai/v1"
)

# Генерация изображений через relay (формат OpenAI-совместимый)
response = client.images.generate(
    model="gemini-3-pro-image-preview",  # Тот же ID модели
    prompt="A minimalist product photo, white background",
    n=1,
    size="1024x1024"
)

image_url = response.data[0].url
print(f"URL сгенерированного изображения: {image_url}")

Relay использует формат API Images от OpenAI, а не формат Gemini SDK, что означает использование Python-библиотеки openai вместо google-generativeai. ID моделей остаются прежними, что упрощает переключение между официальным API и relay в зависимости от контекста развёртывания. Для разработчиков в регионах с ограниченным доступом relay фактически является единственным способом использовать эти модели в продакшене.

На что обращать внимание в relay-сервисе: Важнейший сигнал качества — совместимость API: relay должен принимать те же ID моделей, возвращать ту же структуру ответов и поддерживать те же параметры, что и официальный API. laozhang.ai поддерживает все модели Gemini Image, включая Nano Banana 2 (выпуск от февраля 2026 г.). Документация API доступна по адресу docs.laozhang.ai, а протестировать генерацию изображений интерактивно можно на images.laozhang.ai.

Продвинутое использование: Batch API, обработка ошибок и советы для продакшена

Переход от рабочего прототипа к продакшен-интеграции Gemini Image API требует решения трёх задач, которые в учебных материалах, как правило, обходят стороной: Batch API для снижения стоимости, надёжная обработка ошибок для тех ошибок, с которыми вы обязательно столкнётесь, и архитектурные паттерны, работающие в масштабе.

Batch API доступен для Nano Banana (gemini-2.5-flash-image) и обеспечивает 50% снижение стоимости в обмен на асинхронную обработку. Архитектура такова: загружаете файл JSONL с запросами, отправляете пакетное задание, опрашиваете статус выполнения, скачиваете результаты. Для высокообъёмных рабочих процессов, где задержка не является ограничением — запланированная генерация контента, очереди ночной обработки, массовая фотосъёмка товаров — Batch API фактически вдвое снижает затраты на генерацию изображений без какого-либо снижения качества.

Обработка ошибок обязательна в продакшене. Три ошибки, с которыми вы столкнётесь чаще всего при работе с Gemini Image API: 429 (превышен лимит запросов), 400 (нарушение политики контента) и 503 (сервис временно недоступен). Каждая требует особой реакции:

python
import time
import google.generativeai as genai
from google.api_core import exceptions as google_exceptions

def generate_image_with_retry(prompt: str, max_retries: int = 3) -> bytes | None:
    model = genai.GenerativeModel("gemini-3.1-flash-image-preview")

    for attempt in range(max_retries):
        try:
            response = model.generate_content(prompt)
            for part in response.candidates[0].content.parts:
                if hasattr(part, 'inline_data'):
                    import base64
                    return base64.b64decode(part.inline_data.data)
            return None

        except google_exceptions.ResourceExhausted as e:
            # 429: Лимит запросов. Экспоненциальная задержка.
            if attempt < max_retries - 1:
                wait_time = (2 ** attempt) * 5  # 5с, 10с, 20с
                print(f"Лимит запросов. Ожидание {wait_time}с перед попыткой {attempt + 2}/{max_retries}")
                time.sleep(wait_time)
            else:
                raise

        except google_exceptions.InvalidArgument as e:
            # 400: Политика контента. Не повторять — изменить запрос.
            print(f"Нарушение политики контента: {e}")
            return None

        except google_exceptions.ServiceUnavailable as e:
            # 503: Временный сбой. Короткое ожидание и повтор.
            if attempt < max_retries - 1:
                time.sleep(30)
            else:
                raise

    return None

Подробные решения для ошибки 429 с превышением лимита запросов смотрите в руководстве по решению ошибки 429 в Gemini.

Поведение политики контента в Gemini Image API строже, чем в некоторых конкурирующих моделях. API отклоняет запросы с реалистичными изображениями человеческих лиц в определённых контекстах, откровенным контентом и некоторыми политическими или чувствительными темами. Отказ обычно возвращает ошибку 400 с сообщением о нарушении политики контента. В продакшен-системах реализуйте валидацию запросов перед вызовом API, ведите список известных проблематичных шаблонов запросов и разрабатывайте UX так, чтобы он корректно обрабатывал и объяснял отказы по политике, а не отображал сырые сообщения об ошибках.

Планирование лимитов запросов для продакшена: Лимиты бесплатного уровня (60 RPM, 500 RPD) достаточны для разработки и приложений с низким трафиком. Лимиты платного уровня варьируются в зависимости от модели и тарифного плана. Для приложений, ожидающих значительный трафик, используйте полное руководство по лимитам запросов Gemini API для планирования архитектуры до запуска. Контроль параллелизма — ограничение количества параллельных активных запросов к API — эффективнее, чем логика повторных попыток, для предотвращения ошибок превышения лимитов запросов.

Проектирование запросов для качества изображений: Модели изображений Gemini хорошо реагируют на структурированные запросы, явно указывающие объект, стиль, освещение и композицию. «A product photo» даёт посредственные результаты. «A photorealistic product photo of a ceramic coffee mug, soft natural lighting from the left, white background, sharp focus, commercial photography style, 4K detail» даёт результаты, пригодные для профессионального использования. Ведите библиотеку проверенных шаблонов запросов для вашего сценария и версионируйте их вместе с кодом.

FAQ: Часто задаваемые вопросы о Gemini Image API

Является ли Gemini Image API бесплатным?

Gemini Image API предоставляет бесплатный уровень через Google AI Studio — примерно 500 запросов в день для Nano Banana и Nano Banana 2 при стандартных разрешениях. Модели Imagen 4 (Fast, Standard, Ultra) не имеют бесплатного уровня и требуют оплаты с первого запроса. Бесплатный уровень не включает Nano Banana 2 при разрешении 4K или Nano Banana Pro. Для индивидуальных разработчиков и небольших проектов бесплатный уровень достаточно существенен для создания и тестирования полной интеграции без каких-либо затрат.

В чём разница между Nano Banana и Imagen 4?

Модели Nano Banana (gemini-2.5-flash-image, gemini-3.1-flash-image-preview, gemini-3-pro-image-preview) — это нативные мультимодальные модели генерации изображений Gemini от Google. У них есть бесплатный уровень, они поддерживают стандартный Gemini SDK и могут генерировать изображения в рамках многоходовых разговоров. Модели Imagen 4 — это выделенная профессиональная инфраструктура генерации изображений Google: нет бесплатного уровня, другой формат конечной точки API, но потенциально более высокое фотореалистичное качество. Правильный выбор зависит от вашего сценария: нативные модели Gemini — для простоты разработки и доступа к бесплатному уровню, Imagen 4 — для экономичности в продакшене (Fast) или максимального качества (Standard/Ultra).

Можно ли использовать Gemini Image API за пределами США?

Официальный Gemini API доступен в ограниченном наборе стран. Разработчики в регионах с ограниченным прямым доступом — в том числе в Китае и на некоторых других рынках — могут использовать relay API, наподобие laozhang.ai, которые обеспечивают совместимый доступ к API через промежуточные серверы. Relay требует только изменения базового URL в конфигурации и обеспечивает идентичную функциональность при потенциально более низких ценах.

Как снизить затраты на Gemini Image API?

Наиболее эффективные стратегии снижения затрат: (1) Используйте Batch API для Nano Banana — скидка 50% при 24-часовом окне обработки. (2) Используйте Imagen 4 Fast ($0,02/изображение) для продакшен-нагрузок, если требования к качеству позволяют. (3) Максимизируйте использование бесплатного уровня в период разработки — 500 запросов/день весьма существенно для тестирования. (4) Рассмотрите relay API, наподобие laozhang.ai, для изображений качества Pro примерно на 63% дешевле официальной ставки Nano Banana Pro.

В каком формате Gemini Image API возвращает изображения?

Нативные модели Gemini (серия Nano Banana) возвращают изображения в виде данных, закодированных в base64, с MIME-типом image/png по умолчанию. Imagen 4 также возвращает данные в base64. Управление разрешением и форматом варьируется в зависимости от модели — Nano Banana 2 поддерживает явный выбор разрешения (1K или 4K), тогда как другие модели выдают вывод при своём разрешении по умолчанию. Если вам нужен конкретный формат, например JPEG или WebP, конвертируйте PNG-вывод с помощью библиотеки вроде Pillow после получения ответа.

Что произошло с Gemini 2.0 Flash Image и Gemini 3.0 Flash?

Наименования моделей в линейке изображений Gemini претерпели изменения. gemini-2.0-flash-image была более ранней версией, которую сменил gemini-2.5-flash-image (Nano Banana). Текстовая модель gemini-3.0-flash не имеет отношения к генерации изображений. gemini-3-pro-image-preview (Nano Banana Pro) не следует путать с устаревшей текстовой моделью gemini-3.0-pro, которая была снята с производства 9 марта 2026 года. Всегда используйте ID API, указанные в этом руководстве, а не пытайтесь угадать ID модели по шаблонам имён.

Заключение: выбор пути вперёд

Gemini Image API в 2026 году предлагает реальный набор компромиссов между пятью различными моделями. Для большинства разработчиков, начинающих новый проект, Nano Banana 2 (gemini-3.1-flash-image-preview) — лучшая отправная точка по умолчанию: это новейшая модель в нативном семействе Gemini, поддерживающая бесплатный уровень для разработки и обеспечивающая улучшение качества по сравнению с исходным Nano Banana, при этом сохраняя разумную стоимость при разрешении 1K.

По мере зрелости вашего проекта выбор продакшен-модели должен определяться фактическими требованиями к качеству и объёму. Высокообъёмные приложения, где качество Imagen 4 Fast соответствует потребностям, обнаружат, что $0,02/изображение сложно превзойти. Приложениям, для которых качество изображений является ключевым дифференциатором продукта, следует оценивать Nano Banana Pro и Imagen 4 Standard или Ultra по фактическому качеству вывода для своих конкретных типов запросов, а не принимать решение исключительно на основе цены.

Разработчики, сталкивающиеся с географическими ограничениями доступа, имеют практический путь через relay API — изменение интеграции минимально, совместимость API полная, а стоимость за изображение может быть ниже официальных цен на премиальные модели. Это делает relay API жизнеспособным продакшен-вариантом, а не просто обходным решением.

Важнейший следующий шаг для любой интеграции Gemini Image API — запустить тестовый код из раздела 3 с реальными запросами вашего сценария и оценить качество вывода разных моделей до принятия архитектурного решения. Рейтинги качества моделей в таких руководствах, как это, верны в общем направлении, но поведение при конкретных запросах варьируется достаточно сильно, чтобы прямое тестирование с вашим типом контента оставалось незаменимым.