# Nano Banana 2.1 — /images/generations

Генерация изображений (асинхронно, через задачи) на базе Google Nano Banana 2.1 — обновлённой версии Nano Banana 2, выпущенной в октябре 2026 года. Для генерации по тексту нужен только prompt; для редактирования передайте референсы в image или images (URL, data: URI или base64) либо вызовите /v1/images/edits. После отправки сразу возвращается id задачи (HTTP 202); опрашивайте GET /v1/images/jobs/{id}, чтобы получить изображение. Пропорции вроде 1:1, 3:4, 2:3, 9:16, 4:3, 3:2 и 16:9 в 1K / 2K / 4K, а также широкие кадры 4:1, 1:4, 8:1 и 1:8. Оплата за изображение; неудачные запросы не оплачиваются.

**Эндпоинт:** `POST https://nezhagate.com/v1/images/generations`

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

Три шага: отправить задачу, опросить её и забрать ссылку на изображение. Замените YOUR_API_KEY своим ключом, и команды ниже заработают как есть.

Шаг 1 · Отправка (сразу возвращает id задачи, HTTP 202)

```bash
curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2.1", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "16:9", "resolution": "2K"}'
```

Ответ (HTTP 202)

```json
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281500,
  "model": "nano-banana-2.1"
}
```

Шаг 2 · Опрашивайте каждые 2–3 секунды, пока status не станет succeeded или failed

```bash
curl https://nezhagate.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Ответ при успехе

```json
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281500,
  "model": "nano-banana-2.1",
  "data": [
    {"url": "https://img.nezhagate.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "nano-banana-2.1"}
}
```

Шаг 3 · data[0].url — это изображение (PNG). Оно хранится 60 дней; чтобы пользоваться им дольше, скачайте его в своё хранилище.

### Полный пример (Python: отправить, дождаться, сохранить на диск)

```python
import time
import requests

BASE = "https://nezhagate.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. отправка
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "nano-banana-2.1",
    "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field",
    "size": "16:9",
    "resolution": "2K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. опрос каждые 3 секунды до завершения
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. скачивание изображения
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("nano-banana-2.1.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["message"])
```

## Аутентификация
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Тело запроса
| Параметр | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| `model` | string | Да | Идентификатор модели, здесь nano-banana-2.1. |
| `prompt` | string | Да | Текстовый промпт с описанием изображения. |
| `size` | string | Нет | Соотношение сторон результата. Рекомендуется передавать соотношение — 1:1, 3:4, 2:3, 9:16, 4:3, 3:2, 16:9 — тогда модель рендерит нативно именно в этом соотношении, без обрезки объекта. Также принимаются размеры в пикселях (например, 1024x1024, 1024x1536, 1536x1024). По умолчанию 1:1 (квадрат). |
| `resolution` | string | Нет | Уровень разрешения: 1K (по умолчанию) / 2K / 4K, оплата по уровню. Используйте вместе с пропорцией в size, например {"size": "16:9", "resolution": "2K"}; точные размеры для каждого уровня — ниже, в разделе «Пропорции, разрешение и размер изображения». Если в size указан размер в пикселях (например, 2048x1152), уровень определяется по длинной стороне. |
| `n` | integer | Нет | Всегда 1: каждая задача возвращает одно изображение. Большее значение всё равно даст одно изображение и оплату за одно; для нескольких изображений отправьте несколько задач одновременно. |
| `image` | string | Нет | Изображение в изображение: референсное изображение в виде публичного URL, data: URI или необработанного base64. Если это поле передано, запрос выполняет полноценное изображение-в-изображение с сохранением идентичности объекта в выбранном соотношении и размере (размер/соотношение) — эквивалентно вызову /v1/images/edits. |
| `images` | array | Нет | Несколько референсов, до 8 (если больше, используются первые 8): массив строк или объектов {"image_url": "..."}; каждый — публичная ссылка на изображение, data: URI или base64, до 16 МБ. С ними задача идёт как «изображение из изображения», так же как /v1/images/edits. Для одного референса подойдёт и поле image выше. |

## Пример запроса
```bash
# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "nano-banana-2.1", "prompt": "a serene ink-wash poster, lots of negative space", "size": "16:9", "resolution": "2K"}'
# 2) poll until status=succeeded
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```

## Ответ
```json
{
  "id": "img_3f9a...c2",
  "object": "image.generation.job",
  "status": "queued",
  "model": "nano-banana-2.1"
}
```

## Цена

Оплата за изображение; цена зависит только от уровня разрешения, а пропорция и режим (из текста или из изображения) не влияют. При отправке резервируется цена уровня, а если задача не удалась, сумма полностью возвращается. 1 кредит = $0.005.

| Уровень | Кредитов за изображение | USD за изображение |
| --- | --- | --- |
| 1K | 3 | $0.015 |
| 2K | 5 | $0.025 |
| 4K | 8 | $0.04 |

Каждая задача возвращает ровно одно изображение: какой бы n вы ни передали, вы получите одно изображение и заплатите за одно. Нужно несколько — отправьте несколько задач одновременно (один аккаунт генерирует до 50 изображений параллельно).

## Пропорции, разрешение и размер изображения

Пропорцию задаёт size, уровень — resolution (по умолчанию 1K, также 2K или 4K). Модель рисует сразу в выбранной пропорции, а не квадрат с последующей обрезкой. У готового изображения длинная сторона 1024 / 2048 / 4096 пикселей, вторая — по пропорции. Частые пропорции:

| Пропорция | 1K | 2K | 4K |
| --- | --- | --- | --- |
| 1:1 | 1024x1024 | 2048x2048 | 4096x4096 |
| 3:4 | 768x1024 | 1536x2048 | 3072x4096 |
| 2:3 | 683x1024 | 1365x2048 | 2731x4096 |
| 9:16 | 576x1024 | 1152x2048 | 2304x4096 |
| 4:3 | 1024x768 | 2048x1536 | 4096x3072 |
| 3:2 | 1024x683 | 2048x1365 | 4096x2731 |
| 16:9 | 1024x576 | 2048x1152 | 4096x2304 |

Кроме этих семи, 4:5, 5:4, 21:9, 1:4, 4:1, 1:8 и 8:1 тоже рисуются нативно (по тому же правилу длинной стороны). Любая другая пропорция рисуется в ближайшей горизонтальной, вертикальной или квадратной форме и затем обрезается до нужной, поэтому часть кадра может пропасть.

В size можно указать и размер в пикселях (например, 1536x1024): изображение отдаётся ровно в этом размере, а уровень определяется по длинной стороне: до 1536 — 1K, до 2048 — 2K, больше — 4K. resolution принимает только 1K / 2K / 4K (в любом регистре); другие значения игнорируются, и уровень берётся из size, по умолчанию 1K. Без size получится квадрат 1:1.

## Изображение из изображения и референсы

- Передайте image (одно изображение) или images (несколько, до 8; если больше, используются первые 8), и задача станет «изображение из изображения»; в промпте напишите, что изменить. POST /v1/images/edits принимает те же параметры.
- Каждый референс — это публичная ссылка на изображение (http или https), data: URI или просто base64, до 16 МБ каждый, в распространённом формате: JPEG, PNG, WebP и т. п.
- Ссылка должна отдавать само изображение, а не веб-страницу и не адрес за логином или с защитой от хотлинка. Референс, который не удаётся прочитать, отклоняется при отправке с кодом 400 и причиной; задача не создаётся, деньги не списываются.
- Пропорцию результата задаёт size, а не референс. Чтобы сохранить исходную пропорцию, укажите её в size.
- Референсы мы храним у себя 7 дней.

**Изображение из изображения по двум референсам**

```bash
curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2.1", "prompt": "Keep the people, change the background to a beach at night with warm string lights", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'
```

## Статус задачи и поля ответа

GET /v1/images/jobs/{id} всегда возвращает id, object (image.generation.job), status, created (секунды Unix) и model; остальные поля зависят от статуса:

| status | Значение | Дополнительные поля |
| --- | --- | --- |
| `queued` | В очереди | queue_position (сколько задач впереди), eta_seconds (ориентировочное ожидание в секундах) |
| `processing` | Генерируется | — |
| `succeeded` | Готово | data[].url (ссылка на изображение; наш хостинг хранит его 60 дней); usage.images (сколько изображений выдано), usage.resolution (уровень оплаты) |
| `failed` | Ошибка; сумма, зарезервированная при отправке, полностью возвращена | error.message, error.type, error.code |

Опрашивайте каждые 2–3 секунды. Один аккаунт генерирует до 50 изображений одновременно; остальные задачи ждут в порядке отправки, а задача, не начавшаяся за 15 минут, завершается ошибкой с полным возвратом. Записи о задачах хранятся 3 дня, после этого по id вернётся 404, но ссылка на изображение действует все 60 дней. Задачу может читать только аккаунт, который её отправил.

## Сколько ждать

Обычное время от отправки до результата, ориентировочно. «Изображение из изображения» занимает на несколько секунд больше; задача, которую шлюз перезапустил на другой линии, может занять 1–2 минуты.

| Уровень | Обычное время |
| --- | --- |
| 1K | 25–40 с |
| 2K | 25–50 с |
| 4K | 35–80 с |

## Ошибки и возвраты

Все ошибки имеют одну форму, {"error": {"message", "type", "code", "param"}}; ориентируйтесь на code.

### Ошибки при отправке (задача не создаётся, деньги не списываются)

| HTTP | code | Причина | Что делать |
| --- | --- | --- | --- |
| 400 | `missing_prompt` | prompt пустой | Добавьте prompt |
| 400 | `model_not_found` | Неверный id модели или модель сейчас недоступна | Проверьте id; список моделей — /v1/models |
| 400 | `invalid_request` | Не удаётся прочитать референс (битая ссылка, не изображение, больше 16 МБ…); в message указано, какой и почему | Дайте прямую ссылку на изображение или передайте base64 |
| 401 | `invalid_api_key` | Ключ неверный, удалён или отключён | Проверьте ключ в консоли |
| 402 | `insufficient_quota` | Не хватает баланса, чтобы зарезервировать задачу | Пополните баланс и повторите |
| 429 | `rate_limit_exceeded` | Превышен поминутный лимит, заданный для этого ключа | Снизьте частоту или поднимите лимит ключа в консоли |
| 503 | `model_maintenance` | Модель на обслуживании | Повторите позже; подробности на странице статуса |
| 503 | `service_unavailable` | Временная ошибка на нашей стороне (например, не удалось сохранить референс) | Повторите чуть позже |

### Неудачные задачи (задача принята, но завершилась со status failed; резерв возвращается полностью)

| Ситуация | Что вы увидите | Что делать |
| --- | --- | --- |
| Промпт или референс не прошёл проверку безопасности Google | error.message вроде Content blocked | Перепишите промпт или замените референс; повторная отправка без изменений обычно снова отклоняется |
| Линия генерации дала сбой или не уложилась по времени (сначала мы повторяем на других линиях и возвращаем ошибку, только если не сработали все) | error.code вроде upstream_error или upstream_timeout, причина — в message | Отправьте снова |
| Задача 15 минут ждала и не началась | Это сказано в error.message | Отправьте позже |

## Webhook вместо опроса

В продакшене добавляйте callback_url при отправке. Когда задача завершится, успешно или нет, мы отправим POST на этот адрес с тем же JSON, что возвращает запрос статуса, как событие image.completed или image.failed, с заголовками подписи для проверки отправителя. Можно также задать один адрес для всего аккаунта в «Настройки → Webhook». [Документация по webhook](https://nezhagate.com/ru/docs/webhooks)

```bash
curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2.1", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'
```