API Nano Banana

Быстрый старт

1. Создайте API-ключ в разделе «API». Ключ показывается один раз — сохраните его.
2. Отправьте POST /v1/images/generations — в ответе получите id запроса.
3. Опрашивайте GET /v1/images/generations/{id}, пока status не станет completed или failed.

Аутентификация

Все запросы требуют заголовок с вашим ключом. Не публикуйте ключ на клиенте и в репозиториях — он даёт доступ к балансу вашего аккаунта.

Authorization: Bearer nb_live_ВАШ_КЛЮЧ

Базовый URL: https://api.nanobanana.ru/v1

Создать генерацию

POST /v1/images/generations

• model — идентификатор модели (см. таблицу ниже). Обязательно.
• prompt — текстовое описание. Обязательно.
• n — число изображений, 1–4. По умолчанию 1.
• size — 1K, 2K или 4K. По умолчанию 1K. У nanobanana и nanobanana-2-lite доступен только 1K.
• aspect_ratio — по умолчанию 1:1. Набор зависит от модели, см. Соотношения сторон.
• input_images — массив изображений в base64 для редактирования (необязательно).
• background — transparent для прозрачного фона (результат PNG с альфой). Только у gpt-image-2.5; для других моделей вернёт 400.

curl -X POST https://api.nanobanana.ru/v1/images/generations \
  -H "Authorization: Bearer nb_live_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nanobanana-2",
    "prompt": "кот-астронавт в открытом космосе, кинематографично",
    "n": 1,
    "size": "1K",
    "aspect_ratio": "1:1"
  }'

{
  "id": "gen_a1b2c3d4e5f6...",
  "status": "pending",
  "model": "nanobanana-2",
  "n": 1,
  "size": "1K",
  "aspect_ratio": "1:1",
  "cost": 8,
  "created_at": "2026-07-17T12:00:00.000Z"
}

Списание происходит сразу при создании. Если часть изображений не удалась у провайдера — за них монеты возвращаются автоматически.

Получить результат

GET /v1/images/generations/{id}

Статусы меняются так: pending → processing → completed либоfailed. Опрашивайте раз в 2–3 секунды.

curl https://api.nanobanana.ru/v1/images/generations/gen_a1b2c3d4e5f6... \
  -H "Authorization: Bearer nb_live_ВАШ_КЛЮЧ"

{
  "id": "gen_a1b2c3d4e5f6...",
  "status": "completed",
  "model": "nanobanana-2",
  "n": 1,
  "cost": 8,
  "images": [
    { "url": "https://s3.twcstorage.ru/generations/..." }
  ]
}

Редактирование по фото

Передайте исходные изображения в input_images как строки base64 (без префиксаdata:). Тело запроса ограничено 50 МБ.

{
  "model": "nanobanana-2",
  "prompt": "смени фон на закат у моря",
  "n": 1,
  "size": "2K",
  "aspect_ratio": "3:2",
  "input_images": ["<base64_первого_изображения>"]
}

Модели и цены

Цена указана в монетах за одно изображение, в формате 1K / 2K / 4K.

Актуальный список и цены также доступны программно: GET /v1/models. Текущий баланс —GET /v1/balance.

Соотношения сторон

Все модели, кроме gpt-image-2 и gpt-image-2.5:

1:1  2:3  3:2  3:4  4:3  4:5  5:4  9:16  16:9  21:9

У gpt-image-2 набор шире, плюс режим auto — модель сама подбирает пропорции под запрос:

auto  1:1  3:2  2:3  4:3  3:4  5:4  4:5  16:9  9:16  2:1  1:2  3:1  1:3  21:9  9:21

Исключение: на 2K и 4K у gpt-image-2 недоступны 5:4, 4:5, 3:1, 1:3, 9:21. Запрос с таким сочетанием вернёт 400.

У gpt-image-2.5 свой набор, все значения доступны на любом size:

auto  1:1  3:2  2:3  4:3  3:4  16:9  9:16  21:9

Лимиты

• До 60 запросов в минуту на ключ.
• До 5 изображений одновременно в работе (в статусе pending/processing).
• Размер тела запроса — до 50 МБ.
• Референсов за раз: до 16 для gpt-image-2 и gpt-image-2.5, до 14 для nanobanana-2.1, до 9 для остальных моделей.

Ошибки

Ошибки приходят в едином формате:

{
  "error": {
    "message": "Insufficient balance.",
    "type": "billing_error",
    "code": "insufficient_balance",
    "required": 8
  }
}