Nano Banana (модели изображений Gemini)

Модели изображений Gemini в продаже: gemini-3.1-flash-image-preview, gemini-3-pro-image-preview и gemini-3.1-flash-lite-image. Это модели генерации изображений, обслуживаемые каналами Gemini, и есть два способа обращения (точный список для каждой модели см. в поле supported_endpoint_types в разделе Модели):

Путь	Эндпоинт	Тело, которое вы отправляете
Формат изображений OpenAI	`POST /v1/images/generations`	JSON изображения OpenAI, описан в разделе Формат изображений OpenAI
Нативный Gemini	`POST /v1beta/models/{model}:generateContent`	`contents` + `generationConfig` Gemini

Используйте нативный путь, если ваш клиент уже работает по протоколу Gemini (Google GenAI SDK) и нуждается в полном контроле над responseModalities и imageConfig; используйте /v1/images/generations, если клиент умеет только OpenAI-совместимый API изображений.

Через /v1/images/generations

Структура запроса, аутентификация и тело ошибки совпадают с Форматом изображений OpenAI. RouteAPI преобразует ваш запрос изображения в вызов Gemini generateContent.

Параметры запроса

Поле	Тип	Обязательно	Описание
`model`	string	Да	ID модели изображений Gemini, например `gemini-3.1-flash-image-preview`
`prompt`	string	Да	Отправляется единственной текстовой частью в ходе `user`
`size`	string	Нет	Отображается в `generationConfig.imageConfig.aspectRatio` (см. таблицу ниже)
`n`	integer	Нет	Значения больше `1` передаются как `generationConfig.candidateCount`; `1` или отсутствие значения ничего не отправляют
`quality`, `response_format`, `style`, `user`, `watermark`	—	Нет	На этом пути не преобразуются; адаптер Gemini их игнорирует

RouteAPI сам заполняет responseModalities значением ["TEXT", "IMAGE"], поэтому через этот эндпоинт его передавать не нужно. Настройки безопасности берутся из платформенных настроек Gemini.

Размер в соотношение сторон

Только эти точные значения size отображаются в соотношение сторон:

`size`	`aspectRatio`
`256x256`, `512x512`, `1024x1024`	`1:1`
`1536x1024`	`3:2`
`1024x1536`	`2:3`
`1024x1792`	`9:16`
`1792x1024`	`16:9`

Значение, уже содержащее :, передаётся как соотношение сторон. Любое другое значение (например, 2K или auto) вообще не отправляет imageConfig, и применяется значение upstream по умолчанию. Пиксельные размеры на этом пути не запрашиваются — соотношение сторон является единственным управлением размером.

Пример запроса

curl https://api.routeapi.ai/v1/images/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "A nano banana wearing sunglasses, studio product shot",
    "size": "1536x1024"
  }'

Ответ

Ответ преобразуется в объект изображения OpenAI; сохраняются только встроенные части изображения, а любой текст, возвращённый моделью, отбрасывается.

{
  "created": 1740000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}

URL на этом пути не создаются — всегда читайте data[].b64_json. Если в ответе нет части изображения, запрос завершается с 500; если Gemini блокирует prompt, он завершается с 400, а причина блокировки записывается в запрос.

Нативно через generateContent

POST /v1beta/models/{model}:generateContent
POST /v1beta/models/{model}:streamGenerateContent?alt=sse

Пример:

curl https://api.routeapi.ai/v1beta/models/gemini-3-pro-image-preview:generateContent \
  -H "x-goog-api-key: $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      { "role": "user", "parts": [{ "text": "Draw a cat astronaut on the moon" }] }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" }
    }
  }'

Поля запроса

Поле	Тип	Обязательно	Описание
`contents`	array	Да	Содержимое диалога Gemini, минимум один элемент. Роли — `user` и `model`
`generationConfig.responseModalities`	array of string	Практически да	Должно включать `IMAGE`, иначе модель ответит только текстом
`generationConfig.imageConfig`	object	Нет	Параметры изображения, передаются в Gemini как есть. `aspectRatio` например `1:1`, `3:2`, `16:9`; `imageSize` например `1K`, `2K`, `4K`. Допустимые значения зависят от модели
`generationConfig.candidateCount`	integer	Нет	Число кандидатов; поддерживается не всеми моделями изображений
`safetySettings`	array	Нет	Настройки безопасности Gemini, передаются без изменений
`systemInstruction`	object	Нет	Системная инструкция; также принимается snake_case-форма `system_instruction`

generationConfig принимает как camelCase, так и snake_case написание полей (например, responseModalities / response_modalities и imageConfig / image_config); если присутствуют оба, побеждает snake_case. imageConfig и его содержимое передаются без проверки, поэтому о неподдерживаемом imageSize сообщит Gemini, а не RouteAPI.

Ввод изображения

Чтобы отредактировать или сослаться на изображение, добавьте встроенную часть изображения рядом с текстом:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Repaint this photo as a watercolor illustration" },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAA..."
          }
        }
      ]
    }
  ],
  "generationConfig": { "responseModalities": ["TEXT", "IMAGE"] }
}

inlineData содержит байты изображения в Base64 и передаётся в Gemini без изменений. Для файлов, уже загруженных в Google, также доступна нативная часть fileData.fileUri, которая входит в передаваемую структуру. Если ваш клиент использует формат чата OpenAI, части image_url скачиваются на сервере и преобразуются во встроенные части перед отправкой в Gemini.

Потоковая передача

Потоковая передача выбирается параметром ?alt=sse, а не именем действия: с ним действие upstream становится streamGenerateContent, а ответ представляет собой поток server-sent events Gemini. Каждый фрагмент имеет стандартную структуру candidates[].content.parts. Используйте его, если изображение должно приходить по частям; иначе :generateContent вернёт всю структуру одним телом.

Ответ

Нативный путь возвращает собственную структуру ответа Gemini без изменений:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          { "text": "Here is the image." },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgoAAAANSUhEUgAA..."
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 1120,
    "totalTokenCount": 1132
  }
}

Изображение читается из parts[].inlineData; обычно рядом присутствует текстовая часть. Если Gemini блокирует запрос, устанавливается promptFeedback.blockReason, а candidates пуст.

Тарификация

Модели изображений Gemini тарифицируются по токенам: сгенерированные изображения считаются выходными токенами по цене выхода, а prompt и изображения-референсы — входными токенами. Актуальные ставки см. в разделе Тарификация моделей и на странице модели.

Что дальше

Формат изображений OpenAI — общая структура /v1/images и поведение правок.
Seedream — размеры и семантика правок ByteDance Seedream.
Модели — найдите модели изображений и подтвердите поддержку image-generation.
Тарификация моделей — оплата по токенам и за изображение.