nano banana pro api image config no size parameter ru image 0 图示

Избегаем ошибок при вызове API Nano Banana Pro: imageConfig определяет разрешение, не добавляйте параметр size

от

Многие разработчики при первом вызове API Nano Banana Pro (соответствует модели Google gemini-3-pro-image-preview) наступают на одни и те же грабли: по инерции используют параметр size: "1024x1024" из эпохи OpenAI / DALL-E. В результате разрешение изображения либо не меняется, либо API выдает ошибку 400, либо сервер просто игнорирует этот параметр.

Это самый частый «баг» при работе с API Nano Banana Pro. Правильный подход: разрешение определяется двумя параметрами — imageConfig.imageSize (четкость: 1K/2K/4K) и imageConfig.aspectRatio (соотношение сторон: 1:1/16:9/…). Забудьте про поле size. В этой статье мы разберем всё по полочкам и предоставим готовый код на curl, Python и Node.js, который можно сразу копировать и запускать.

nano-banana-pro-api-image-config-no-size-parameter-ru 图示

Основные моменты вызова API Nano Banana Pro

Прежде чем переходить к коду, запомните три «золотых правила». Если вы их усвоите, 90% материала станет очевидным:

  1. Имя модели: Nano Banana Pro = gemini-3-pro-image-preview (также известная как Gemini 3 Pro Image). Это модель для генерации и редактирования изображений из серии Google Gemini 3. Некоторые называют её Nano Banana 2 — по сути, это одно и то же.
  2. Протокол Gemini: Это не совместимый с OpenAI Chat Completions протокол. Путь запроса — :generateContent, поля верхнего уровня в теле запроса — contents и generationConfig. Здесь нет messages и нет параметров size в стиле OpenAI.
  3. Разрешение = imageSize × aspectRatio: imageSize управляет уровнем четкости (512 / 1K / 2K / 4K), а aspectRatio — соотношением сторон (1:1 / 16:9 / 9:16 / …). Эти два параметра вместе определяют итоговое разрешение в пикселях.

📌 Краткий итог: При вызове Nano Banana Pro через протокол Gemini забудьте про привычку использовать size: "1024x1024". APIYI (apiyi.com) полностью поддерживает оригинальный протокол Gemini, поэтому любые настройки imageConfig, работающие в официальном API Google, будут корректно работать и в APIYI.

Краткий обзор ключевых параметров Nano Banana Pro

Параметр Расположение Назначение Пример значения
imageSize generationConfig.imageConfig Уровень четкости "512" / "1K" / "2K" / "4K"
aspectRatio generationConfig.imageConfig Соотношение сторон "1:1" / "16:9" / "9:16" / "4:3" и т.д.
responseModalities generationConfig Модальность вывода ["IMAGE"] (обязательно)
contents[].parts[].text contents Текстовый промпт Произвольный текст
contents[].parts[].inline_data contents Входное изображение (base64) Включает mime_type и data

⚠️ Почему нет поля size?: Потому что это не является допустимым параметром в протоколе Gemini. Не передавайте его.

Почему не стоит добавлять параметр size? Причины на уровне протокола

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

Уровень протокола: Gemini и OpenAI — это два разных стандарта

API для генерации изображений от OpenAI (DALL-E 2/3, gpt-image-1) использует строковый параметр верхнего уровня size: "1024x1024". В то же время API для изображений Google Gemini 3 спроектировано с использованием вложенного объекта imageConfig. Эти два стандарта никак не связаны друг с другом. Nano Banana Pro работает на базе нативного протокола Gemini, поэтому:

  • ❌ size: "1024x1024" — в протоколе Gemini нет такого поля.
  • ❌ size: "1K" — такого поля тоже нет.
  • ❌ n: 4 — нет поля для генерации N изображений за раз, как у OpenAI.
  • ✅ imageConfig.imageSize: "1K" — правильно.
  • ✅ imageConfig.aspectRatio: "16:9" — правильно.

Уровень поведения: что будет, если передать лишний size?

Сервер обычно реагирует одним из трех способов, и ни один из них вам не понравится:

  1. Тихое игнорирование: шлюз (gateway) просто отбрасывает неизвестные поля. Вы думаете, что параметр сработал, но на выходе получаете стандартные 1K 1:1.
  2. Ошибка 400: шлюз со строгой проверкой схемы отклонит запрос из-за наличия неизвестного поля.
  3. Влияние на биллинг/маршрутизацию: некоторые прокси-слои могут принять size за сигнал маршрутизации и отправить запрос на неверную версию эндпоинта.

Инженерный уровень: технический долг и бардак в коде

Многие команды упаковывают API от OpenAI, Gemini, Stability и других в один слой вызова, по привычке переиспользуя «универсальное поле size». На первый взгляд это кажется элегантным решением, но на деле — это рассадник багов. Рекомендую при вызове нативных интерфейсов Gemini, таких как Nano Banana Pro, использовать отдельную цепочку преобразования. Явно отображайте size в imageConfig.imageSize + imageConfig.aspectRatio, вместо того чтобы просто пробрасывать исходный size дальше.

💡 Совет: при использовании APIYI (apiyi.com) для вызова Nano Banana Pro напишите небольшую функцию преобразования параметров. Она должна разбивать привычную вам строку вроде "1024x1024" на imageSize: "1K" + aspectRatio: "1:1", чтобы исключить путаницу на корню.

Полная таблица соответствия imageSize × aspectRatio

nano-banana-pro-api-image-config-no-size-parameter-ru 图示

Уровни imageSize и тарификация

imageSize Прибл. разрешение Выходные токены Цена (справочно) Рекомендуемые сценарии
"512" 512×512 Низкое Самый дешевый Миниатюры / черновики
"1K" 1024×1024 ~1120 ≈ $0.134 Рекомендуемый стандарт
"2K" 2048×2048 ~1120 ≈ $0.134 HD-постеры
"4K" 4096×4096 ~2000 ≈ $0.24 (дороже на ~80%) Полиграфия

💰 Совет по затратам: 4K стоит примерно на 80% дороже, чем 1K/2K, поэтому не стоит бездумно использовать 4K везде. В большинстве веб- и мобильных сценариев 1K вполне достаточно, переходите на 4K только при необходимости сверхвысокой четкости. Актуальные цены уточняйте на сайте APIYI (apiyi.com).

Полный список поддерживаемых aspectRatio

Соотношение Использование
"1:1" Аватары / Квадратные фото
"16:9" Обложки видео / Обои для рабочего стола
"9:16" Вертикальные видео / Обои для смартфона
"4:3" Классический горизонтальный формат
"3:4" Классический вертикальный формат
"3:2" / "2:3" Стандарт DSLR
"4:5" / "5:4" Instagram-посты
"21:9" Кинематографичный формат
"1:4" / "4:1" Длинные баннеры
"1:8" / "8:1" Экстремально длинные форматы

Типовые комбинации → Итоговое разрешение

imageSize aspectRatio Прибл. пиксели
1K 1:1 1024 × 1024
1K 16:9 1024 × 576
1K 9:16 576 × 1024
2K 1:1 2048 × 2048
2K 16:9 2048 × 1152
4K 1:1 4096 × 4096
4K 9:16 2304 × 4096
4K 21:9 4096 × 1728

Примечание: фактическое разрешение может незначительно отличаться (на ±N пикселей) из-за внутренних правил выравнивания модели, но это не влияет на визуальную четкость.

Правильный код для вызова API Nano Banana Pro

Ниже приведены минимально рабочие примеры на трех языках программирования. Все три примера выполняют одну и ту же задачу: отправляют исходное изображение + промпт и получают на выходе изображение 1K в формате 1:1.

Версия cURL (самая наглядная, удобно для отладки)

curl -X POST \
  "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer ВАШ-API-КЛЮЧ-APIYI" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {
          "inline_data": {
            "mime_type": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAA...(base64 исходного изображения)"
          }
        },
        {
          "text": "Измени стиль этой картинки на киберпанк, сохранив позу персонажа"
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }'

Версия на Python (рекомендуется использовать requests, без зависимостей от SDK)

import base64
import requests

with open("input.png", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode()

resp = requests.post(
    "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
    headers={
        "Authorization": "Bearer ВАШ-API-КЛЮЧ-APIYI",
        "Content-Type": "application/json",
    },
    json={
        "contents": [{
            "parts": [
                {"inline_data": {"mime_type": "image/png", "data": img_b64}},
                {"text": "Измени стиль этой картинки на киберпанк, сохранив позу персонажа"},
            ]
        }],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {
                "aspectRatio": "1:1",
                "imageSize": "1K",
            },
        },
    },
    timeout=120,
)

data = resp.json()
out_b64 = data["candidates"][0]["content"]["parts"][0]["inline_data"]["data"]
with open("output.png", "wb") as f:
    f.write(base64.b64decode(out_b64))

Версия на Node.js (используем нативный fetch, чтобы SDK не «съел» imageConfig)

import fs from "node:fs";

const imgB64 = fs.readFileSync("input.png").toString("base64");

const resp = await fetch(
  "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer ВАШ-API-КЛЮЧ-APIYI",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      contents: [{
        parts: [
          { inline_data: { mime_type: "image/png", data: imgB64 } },
          { text: "Измени стиль этой картинки на киберпанк, сохранив позу персонажа" },
        ],
      }],
      generationConfig: {
        responseModalities: ["IMAGE"],
        imageConfig: {
          aspectRatio: "1:1",
          imageSize: "1K",
        },
      },
    }),
  },
);

const data = await resp.json();
const outB64 = data.candidates[0].content.parts[0].inline_data.data;
fs.writeFileSync("output.png", Buffer.from(outB64, "base64"));

🔧 Почему мы настоятельно рекомендуем использовать нативный fetch или requests: известно, что некоторые SDK (включая ранние версии LiteLLM и некоторые версии Google Node SDK) отфильтровывают imageConfig как неизвестное поле, из-за чего параметры imageSize/aspectRatio просто игнорируются. Прямое формирование тела JSON-запроса гарантированно избавляет от этой проблемы. Если вы все же хотите использовать SDK, сначала обновитесь до последней версии и проверьте итоговое тело запроса через логгер.

Чек-лист: 6 самых частых ошибок при вызове

nano-banana-pro-api-image-config-no-size-parameter-ru 图示

Ошибка 1: Передача параметра size в стиле OpenAI

// ❌ Ошибка: size не является допустимым полем протокола Gemini
{
  "contents": [...],
  "size": "1024x1024",
  "generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" } }
}

// ✅ Правильно: удалите size, оставьте только imageConfig
{
  "contents": [...],
  "generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" }, "responseModalities": ["IMAGE"] }
}

Ошибка 2: Использование snake_case вместо camelCase

Поля imageConfig в интерфейсе Gemini 3 должны быть в формате camelCase: imageSize, aspectRatio, responseModalities. Частые ошибки:

  • ❌ image_size / aspect_ratio / response_modalities
  • ✅ imageSize / aspectRatio / responseModalities

Ошибка 3: imageConfig "съедается" SDK

Как упоминалось ранее, некоторые версии SDK отфильтровывают неизвестные поля. Как проверить:

  1. Выведите реальное тело HTTP-запроса до и после вызова SDK.
  2. Используйте mitmproxy или Charles для перехвата реального исходящего трафика.
  3. Если обнаружили, что imageConfig исчез, переходите на нативный fetch или requests.

Ошибка 4: Забыли про responseModalities

// ❌ Если не указать responseModalities, может вернуться текст вместо изображения
{ "generationConfig": { "imageConfig": {...} } }

// ✅ Нужно явно указать, что ожидается IMAGE
{ "generationConfig": { "imageConfig": {...}, "responseModalities": ["IMAGE"] } }

Ошибка 5: Нет экспоненциальной задержки при ошибке 429

При перегрузке вышестоящего сервера вы можете получить ответ:

{ "error": { "message": "Текущая нагрузка на группу серверов превышена, попробуйте позже", "type": "upstream_error", "code": 429 } }

Правильный подход — повторные попытки с экспоненциальной задержкой (3с → 6с → 12с). Не пытайтесь повторить запрос мгновенно, это только усугубит проблему:

import time

for attempt in range(3):
    resp = requests.post(url, json=body, headers=headers, timeout=120)
    if resp.status_code != 429:
        break
    time.sleep(3 * (2 ** attempt))   # 3с, 6с, 12с

Ошибка 6: Неправильное размещение нескольких эталонных изображений

Nano Banana Pro поддерживает ввод нескольких изображений (исходное + несколько эталонных). Все изображения должны быть переданы как отдельные элементы inline_data в массиве parts, а текстовый промпт должен идти в самом конце:

// ✅ Правильно: изображения в начале, текст в конце
"parts": [
  { "inline_data": { "mime_type": "image/png", "data": "base64 исходного" } },
  { "inline_data": { "mime_type": "image/png", "data": "base64 эталона 1" } },
  { "inline_data": { "mime_type": "image/png", "data": "base64 эталона 2" } },
  { "text": "Перенеси стиль с эталона 1 на исходное изображение, композицию возьми с эталона 2" }
]

🧰 Итог: создайте внутренний "Чек-лист Nano Banana Pro" на основе этих 6 пунктов и проверяйте его перед каждым новым внедрением — это позволит избежать 90% глупых ошибок. Эндпоинт Nano Banana Pro на APIYI (apiyi.com) полностью следует протоколу Gemini, поэтому все эти советы универсальны.

Разбор процесса вызова пользователем: на каком этапе чаще всего возникают ошибки

nano-banana-pro-api-image-config-no-size-parameter-ru 图示

Логи вызовов, которые присылают многие пользователи, почти всегда выглядят так:

Frontend POST /api/generate
  → server.js извлекает параметры
  → проверка modelKey.startsWith('nano-banana')
  → _generateViaGemini() формирует тело запроса
  → POST https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent
  → возврат результата / повторная попытка

Давайте разберем каждый узел и отметим, где чаще всего возникают ошибки:

Этап Типичная проблема Рекомендация
Параметры фронтенда Привычка передавать size: "1024x1024" Разделите на два поля: imageSize + aspectRatio
Сборка body в server.js Случайная передача поля size в Gemini Явно удаляйте size в функции сборки (delete)
Маршрутизация модели nano-banana уходит на 1.5 вместо 3 Pro Указывайте точное имя gemini-3-pro-image-preview
Отправка запроса Использование SDK с жесткой схемой валидации Перейдите на нативный fetch или обновите SDK
Обработка ошибок Ошибка 429 сразу отдается пользователю Используйте экспоненциальную задержку (3 попытки)
Парсинг ответа Попытка взять text, хотя пришел IMAGE Правильный путь: candidates[0].content.parts[0].inline_data.data

📋 Коротко: структура вашего процесса верна. Просто уберите лишнее поле size на этапе извлечения параметров и убедитесь, что server.js не добавляет его обратно вне generationConfig. После этого вся цепочка будет работать чисто.

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

Q1: Nano Banana Pro и Nano Banana 2 — это одно и то же?
Да. В сообществе многие называют Gemini 3 Pro Image (gemini-3-pro-image-preview) как Nano Banana 2 или Nano Banana Pro. Все три названия относятся к одной модели. На APIYI (apiyi.com) ориентируйтесь на названия моделей из официальной документации.

Q2: Что будет, если не передать imageConfig?
Модель выдаст результат согласно внутренним настройкам по умолчанию (обычно 1K + 1:1). Если разрешение не критично, можно пропустить; если нужны конкретные параметры кадра — обязательно передавайте imageConfig.

Q3: Можно ли использовать протокол Gemini, но передавать size как в OpenAI?
Надежно — нет. В протоколе Gemini нет поля size, смешивание параметров приведет к непредсказуемому поведению. Использование imageConfig.imageSize + imageConfig.aspectRatio — самый безопасный путь.

Q4: Будет ли качество картинки лучше при выборе 4K?
Детализация будет выше, но стоимость почти удвоится (~$0.24 против $0.134), а время генерации увеличится. Для веба или мобильных приложений 1K или 2K обычно достаточно. Рекомендую протестировать на реальных задачах и сравнить результат визуально.

Q5: В чем разница между вызовом Nano Banana Pro через APIYI (apiyi.com) и напрямую через Google API?
APIYI предоставляет унифицированную аутентификацию в стиле OpenAI (Bearer Token), доступ из РФ и единую систему биллинга, при этом сам протокол вызова полностью соответствует нативному формату Gemini. Это значит, что параметры imageConfig, aspectRatio и responseModalities из документации Google полностью эквивалентны при работе через APIYI.

Q6: Почему я установил imageSize: "2K", а на выходе все равно 1K?
Три самые частые причины: (1) используется SDK, который отфильтровывает неизвестные поля, (2) имя поля написано как image_size, (3) ошибка в уровне вложенности generationConfig. Сначала перехватите реальный исходящий запрос, чтобы убедиться, что body соответствует спецификации, а затем проверяйте серверную часть.

Q7: Что делать с ограничением 429 от вышестоящего сервиса?
Используйте экспоненциальную задержку (3с/6с/12с). Если ваш сервис чувствителен к задержкам, можно переключить группу в рабочем пространстве APIYI или запросить отдельную квоту. Ни в коем случае не делайте бесконечный цикл с мгновенным повтором — это приведет к постоянному срабатыванию лимитов.

Q8: Есть ли лимит на количество входных изображений?
Интерфейс Gemini 3 image имеет ограничение на общий размер изображений в одном запросе (обычно измеряется в МБ, уточняйте в официальной документации). Рекомендуется использовать не более 4-5 эталонных изображений, каждое из которых предварительно сжато (сначала resize, потом base64), иначе можно получить ошибку 413 или таймаут.

Резюме: доводим «метод двух параметров разрешения» до мышечной памяти

Если нужно запомнить только одну вещь, пусть это будет:

Итоговое разрешение Nano Banana Pro = imageConfig.imageSize × imageConfig.aspectRatio. Забудьте про передачу поля size в стиле OpenAI.

Полный чек-лист:

  • ✅ Имя модели: gemini-3-pro-image-preview
  • ✅ Эндпоинт: /v1beta/models/.../generateContent
  • ✅ generationConfig.imageConfig.imageSize ∈ 512 / 1K / 2K / 4K
  • ✅ generationConfig.imageConfig.aspectRatio ∈ 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 21:9 / …
  • ✅ generationConfig.responseModalities обязательно должно содержать "IMAGE"
  • ✅ Входные данные с несколькими изображениями размещайте в массиве parts, текстовый промпт — в самом конце
  • ✅ При ошибке 429 (лимиты) используйте экспоненциальную задержку (3с/6с/12с)
  • ❌ Не передавайте size: "1024x1024"
  • ❌ Не пишите image_size / aspect_ratio (snake_case здесь не работает)
  • ❌ Не доверяйте старым SDK, которые фильтруют неизвестные поля — сначала проверьте через перехват трафика

📢 Напоследок: если вы подключаетесь к Nano Banana Pro через APIYI (apiyi.com), просто скопируйте шаблоны кода на cURL / Python / Node.js из этой статьи. Все параметры строго соответствуют нативному протоколу Gemini: копируете, вставляете API-ключ — и всё работает.

Автор: Команда APIYI · Постоянно собираем лучшие практики вызова API больших языковых моделей · apiyi.com

Оставьте комментарий