Как использовать Nano Banana 2 API: ключ, запрос, результат

Чтобы использовать Nano Banana 2 API, создайте API-ключ, отправьте тело запроса generateContent от Google с полем model на единую конечную точку и опрашивайте возвращённую задачу, пока не будет готов URL изображения. Те же шаги работают для Nano Banana Pro и Nano Banana 2 Lite; меняется только значение model.

В этой инструкции каждый шаг разобран на рабочем коде, а затем показано, как редактировать изображения по референсам и как поручить работу ИИ-агенту для программирования.

Что нужно перед первым запросом?

API-ключ. Создайте его на странице API-ключей и храните на своём сервере. Никогда не размещайте его в браузерном коде.
Кредиты. Пополните баланс на странице оплаты. Кредиты не сгорают, а неудачные запросы не оплачиваются.
ID модели. gemini-3.1-flash-image списывает фиксированную цену за изображение; gemini-3.1-flash-image-official тарифицирует токены. Выбрать поможет руководство по ценам.

export SEEDROUTER_API_KEY="your-key"

Как отправить запрос к Nano Banana 2?

Отправьте запрос методом POST на /v1/images/generations. Тело запроса — это форма generateContent от Google плюс model:

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "contents": [{"parts": [{"text": "A ceramic teapot on a linen tablecloth, soft window light"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
    }
  }'

В ответ приходит задача, а не изображение:

{
  "id": "task_...",
  "model": "gemini-3.1-flash-image",
  "status": "processing",
  "created_at": 1790310979
}

Если вы уже работаете с API Google, тело запроса — то же самое, что вы отправили бы в generateContent. Прямые вызовы /v1beta/models/...:generateContent в SeedRouter не поддерживаются; используйте эту конечную точку.

Как получить изображение?

Опрашивайте задачу каждые несколько секунд, пока status не станет completed или failed. На Python:

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}

response = requests.post(
    f"{API}/images/generations",
    headers=headers,
    json={
        "model": "gemini-3.1-flash-image",
        "contents": [{"parts": [{"text": "A ceramic teapot on a linen tablecloth, soft window light"}]}],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"},
        },
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(f"{API}/tasks/{task_id}", headers=headers, timeout=30)
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        for image in task["output"]["data"]:
            print(image["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(3)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

В завершённой задаче URL изображения находится в output.data[0].url, а также указан расход токенов. С "responseModalities": ["TEXT", "IMAGE"] любой текст, который пишет модель, возвращается в output.text. Если изображение нужно надолго, скачайте его в своё хранилище.

Тайм-аут при опросе не означает, что генерация изображения не удалась. Сохраните идентификатор задачи и проверьте её снова; новый запрос означает оплату второго изображения.

Как редактировать изображение или использовать референсы?

Добавьте части fileData рядом с текстом. Каждая из них — это публичный URL и его MIME-тип:

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "contents": [{
      "role": "user",
      "parts": [
        {"text": "Turn this photo into a watercolor painting. Keep the composition."},
        {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://example.com/photo.jpg"}}
      ]
    }]
  }'

Nano Banana 2 принимает до 14 референсов на запрос: изображения, видео или PDF, каждый меньше 50 МБ. Референсы должны быть URL; base64 inlineData не принимается. Если URL не удаётся загрузить, задача завершается сбоем и не оплачивается. Для последующей правки отправьте предыдущие реплики как записи user и model и завершите новой репликой user.

Какие настройки важнее всего?

Настройка	Что делает
`imageConfig.imageSize`	`512`, `1K`, `2K` или `4K`; по умолчанию `1K`
`imageConfig.aspectRatio`	14 соотношений сторон от `1:8` до `8:1`; если не задано, берётся по первому референсу
`responseModalities`	`["IMAGE"]` — только изображение, `["TEXT", "IMAGE"]` — ещё и текст
`systemInstruction`	Постоянные правила, например фирменный стиль
`seed`	Используйте повторно, чтобы приблизиться к прежнему результату
`mediaResolution`	Сколько токенов расходует каждый референс; меньшее значение дешевле на Official

В справочнике Nano Banana 2 API перечислены все поля и ограничения. Неизвестные поля отклоняются до каких-либо списаний, а заземление через Google Search (tools) пока недоступно.

Как поручить Nano Banana 2 API ИИ-агенту для программирования?

ИИ-агент для программирования, например Claude Code, Codex или Cursor, может вызывать API командой в терминале или коротким скриптом. SeedRouter не поставляет MCP-сервер или готовый skill; этот промпт — вся интеграция. Сначала экспортируйте ключ, затем вставьте:

Use the SeedRouter API to generate a Nano Banana 2 image for me.

Security: read SEEDROUTER_API_KEY from my local environment. Never ask me to paste it and never print it.

Goal: [subject, setting, style, what the image is for]
Size: [512 | 1K | 2K | 4K]    Aspect ratio: [e.g. 1:1, 16:9, 9:16]
References: [public image URLs, or none]

Send POST https://api.seedrouter.ai/v1/images/generations with
{"model": "gemini-3.1-flash-image",
 "contents": [{"parts": [{"text": "..."}, {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://..."}}]}],
 "generationConfig": {"responseModalities": ["IMAGE"],
   "imageConfig": {"aspectRatio": "...", "imageSize": "..."}}}
Accepted top-level fields: model, contents, systemInstruction, safetySettings,
generationConfig. References must be fileData URLs (up to 14), never base64.
Do not add tools or any other field.

Before sending, show me the request body and wait for my approval: each
request is charged. Then poll GET https://api.seedrouter.ai/v1/tasks/{id}
every 3 seconds until status is completed or failed. If polling times out,
keep checking the same task; never resubmit. Save output.data[0].url into
./images/ and tell me the file path.

Шаг подтверждения важен: агент тратит ваш баланс, поэтому он никогда не должен отправлять запросы самостоятельно.

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

Как получить API-ключ Nano Banana 2?

Войдите в аккаунт, откройте страницу API-ключей и создайте ключ. Один и тот же ключ работает для Nano Banana 2, Nano Banana Pro, Nano Banana 2 Lite и других моделей в SeedRouter.

Поддерживает ли Nano Banana 2 API пакетные запросы?

Отправляйте один запрос на изображение и опрашивайте задачи параллельно. Каждый запрос возвращает одно изображение, и каждая задача оплачивается отдельно.

Какие ошибки нужно обрабатывать?

400 означает, что тело запроса нарушило правило, например содержит неизвестное поле или неподдерживаемый размер, и ничего не списывается. Задача, завершившаяся со статусом failed, содержит сообщение об ошибке и тоже не оплачивается. В руководстве по ошибкам перечислены все коды и указано, когда повторять запрос.

Отправьте первый запрос

Создайте ключ, пополните баланс на небольшую сумму и запустите пример на Python выше — или попробуйте тот же запрос без кода в Playground Nano Banana 2. Для сложных промптов смените модель на gemini-3-pro-image, чтобы использовать Nano Banana Pro.

Как использовать Nano Banana 2 API: ключ, запрос и результат