API документация Nano Banana 2

Введение

Nano Banana 2 предоставляет REST API для генерации изображений через искусственный интеллект, управления балансом и просмотра истории. API позволяет интегрировать генерацию изображений в ваши приложения, боты и скрипты.

Базовый URL

https://nanobanana.expert/api/v1

Чтобы получить API ключ, перейдите в Dashboard → вкладка API.

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

Все запросы к API должны содержать заголовок Authorization с вашим API ключом в формате Bearer токена. Ключи начинаются с префикса nb_.

HTTP

Authorization: Bearer nb_your_api_key_here

Каждый запрос использует баланс бананов вашего аккаунта. Ключ привязан к аккаунту — не передавайте его третьим лицам.

Баланс

Возвращает текущий баланс вашего аккаунта.

GET

/api/v1/balance

Получить баланс бананов и купонов

Ответ

JSON

{
  "bananas": 1250,
  "generation_coupons": 2
}

Примеры

cURL

curl -H "Authorization: Bearer nb_your_key" \
  https://nanobanana.expert/api/v1/balance

JavaScript

const res = await fetch('https://nanobanana.expert/api/v1/balance', {
  headers: { 'Authorization': 'Bearer nb_your_key' }
});
const { bananas, generation_coupons } = await res.json();
console.log(`Balance: ${bananas} bananas`);

Генерация изображения

Генерирует изображение по текстовому описанию. Стоимость списывается с баланса.

POST

/api/v1/generate

Создать изображение по промпту

Тело запроса

Параметр	Тип	Описание
prompt	string	Обязательный. Текстовое описание изображения или инструкция для редактирования (если переданы reference_images).
reference_images	string[]	Необязательный. Массив 1–4 исходных изображений для image-to-image (улучшение/редактирование). Каждый элемент — публичный http(s) URL или base64 data URL вида data:image/png;base64,…. При наличии этого поля запрос автоматически выполняется в режиме редактирования; цена та же, что и для генерации по промпту, и зависит только от resolution.
model	string	Необязательный. "nb2" (по умолчанию — Nano Banana 2, универсальная) или "gpt2" (GPT Image 2, лучше с текстом на изображениях).
quality	string	Необязательный. Только для model="gpt2": "low" \| "medium" (по умолчанию) \| "high". Влияет на детализацию и стоимость. У провайдера "stable" цена одинакова для всех уровней качества (но качество всё равно передаётся модели).
aspect_ratio	string	Необязательный. Например: "16:9", "1:1", "9:16". По умолчанию: "1:1".
resolution	string	Необязательный. "1k" \| "2k" \| "4k". По умолчанию: "1k".
output_format	string	Необязательный. "png" \| "jpeg" \| "webp". По умолчанию: "png".
seed	number	Необязательный. Seed для воспроизводимости результата.
preferred_provider	string	Необязательный. Уровень провайдера: "economy" (дешевле, менее стабильный), "stable" (по умолчанию — рекомендуется, средний баланс цены и качества), "reliable" (премиум — максимальная стабильность). Поддерживаются legacy-значения: "cheap" → "economy", "official" → "stable". При сбое основного провайдера система автоматически пробует остальных по возрастанию стоимости.

Ответ

JSON

{
  "image_url": "https://...",
  "bananas_spent": 42,
  "used_coupon": false,
  "seed": 1234567890,
  "generation_id": "uuid",
  "provider_chain": ["kie"]
}

provider_chain — список фактических step'ов которые мы пробовали в порядке выполнения. Один элемент — primary выбранного tier'а сработал с первого раза; несколько — primary упал и сработал fallback.

Примеры

cURL

curl -X POST https://nanobanana.expert/api/v1/generate \
  -H "Authorization: Bearer nb_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a banana in space, cinematic lighting",
    "aspect_ratio": "16:9",
    "resolution": "1k",
    "output_format": "png"
  }'

JavaScript

const res = await fetch('https://nanobanana.expert/api/v1/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer nb_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: 'a banana in space, cinematic lighting',
    aspect_ratio: '16:9',
    resolution: '1k',
    preferred_provider: 'stable', // economy / stable / reliable
  }),
});
const { image_url, bananas_spent } = await res.json();
console.log('Generated:', image_url);

Image-to-image (улучшение загруженной картинки)

Чтобы улучшить или переработать существующее изображение, передайте его в массиве reference_images вместе с промптом — endpoint тот же. Промпт описывает, что нужно изменить (или оставить пустым «keep as is» для апскейла). Поддерживаются http(s)-ссылки и base64 data URL.

cURL

curl -X POST https://nanobanana.expert/api/v1/generate \
  -H "Authorization: Bearer nb_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "make the lighting cinematic, keep the subject",
    "reference_images": ["https://example.com/photo.jpg"],
    "resolution": "2k"
  }'

JavaScript

// Option 1 — public URL (recommended, no body size limits)
await fetch('https://nanobanana.expert/api/v1/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer nb_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: 'restore colors, increase sharpness',
    reference_images: ['https://example.com/photo.jpg'],
    resolution: '2k',
  }),
});

// Option 2 — base64 data URL (image/png|jpeg|webp|gif)
const dataUrl = 'data:image/jpeg;base64,/9j/4AAQSk...';
await fetch('https://nanobanana.expert/api/v1/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer nb_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: 'restore colors, increase sharpness',
    reference_images: [dataUrl],
  }),
});

Рекомендуем использовать публичные URL: они работают без ограничений на размер тела запроса. Base64 удобен для быстрых проб, но может упереться в лимит платформы (~4 МБ). Цена image-to-image равна цене обычной генерации для выбранного resolution.

История генераций

Возвращает список ваших генераций в обратном хронологическом порядке.

GET

/api/v1/history

Получить историю генераций

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

Параметр	Описание
limit	Кол-во записей (макс. 100, по умолчанию 20)
offset	Смещение для пагинации (по умолчанию 0)

Ответ

JSON

{
  "generations": [
    {
      "id": "uuid",
      "prompt": "a banana in space",
      "image_url": "https://...",
      "model": "kie/nano-banana-2",
      "seed": 1234567890,
      "created_at": "2026-03-04T12:00:00Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

cURL

curl "https://nanobanana.expert/api/v1/history?limit=10&offset=0" \
  -H "Authorization: Bearer nb_your_key"

Управление ключами через API

Вы можете управлять API ключами программно через сам API.

GET

/api/v1/keys

Получить список активных ключей

POST

/api/v1/keys

Создать новый ключ (возвращается один раз)

DELETE

/api/v1/keys?id=uuid

Отозвать ключ по ID

cURL — create key

curl -X POST https://nanobanana.expert/api/v1/keys \
  -H "Authorization: Bearer nb_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Bot"}'

cURL — revoke key

curl -X DELETE "https://nanobanana.expert/api/v1/keys?id=key-uuid-here" \
  -H "Authorization: Bearer nb_your_key"

Коды ошибок

Код	Значение	Решение
401	Unauthorized	Проверьте заголовок Authorization: Bearer nb_...
402	Insufficient funds	Пополните баланс бананов на /dashboard
400	Bad Request	Проверьте обязательные параметры запроса
403	Forbidden	Аккаунт заблокирован
429	Too Many Requests	Слишком много запросов, подождите
500	Internal Error	Внутренняя ошибка сервера
503	Service Unavailable	Сервис временно недоступен

Все ошибки возвращаются в формате { "error": "message" }.