Nano Banana 2.1 · API

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

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

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"}'

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

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

{
  "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 дней; чтобы пользоваться им дольше, скачайте его в своё хранилище.

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

Чтобы начать, создайте API-ключ в консоли.

Тело запроса

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

# 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'

import time, requests

base, key = "https://nezhagate.com/v1", "YOUR_API_KEY"
h = {"Authorization": f"Bearer {key}"}
job = requests.post(f"{base}/images/generations", headers=h,
                    json={"model": "nano-banana-2.1", "prompt": "an ink-wash poster", "size": "16:9", "resolution": "2K"}).json()
while True:
    r = requests.get(f"{base}/images/jobs/{job['id']}", headers=h).json()
    if r["status"] in ("succeeded", "failed"): break
    time.sleep(3)
print(r.get("data", [{}])[0].get("url"))

const base = "https://nezhagate.com/v1", key = "YOUR_API_KEY";
const h = { Authorization: `Bearer ${key}`, "Content-Type": "application/json" };
const job = await (await fetch(`${base}/images/generations`, { method: "POST", headers: h,
  body: JSON.stringify({ model: "nano-banana-2.1", prompt: "an ink-wash poster", size: "16:9", resolution: "2K" }) })).json();
let r;
do { await new Promise(s => setTimeout(s, 3000));
     r = await (await fetch(`${base}/images/jobs/${job.id}`, { headers: h })).json();
} while (r.status !== "succeeded" && r.status !== "failed");
console.log(r.data?.[0]?.url);

Ответ

{
  "id": "img_3f9a...c2",
  "object": "image.generation.job",
  "status": "queued",
  "model": "nano-banana-2.1"
}

Цена

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

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

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

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

Кроме этих семи, 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 дней.

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; остальные поля зависят от статуса:

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

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

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

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

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

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

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

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

В продакшене добавляйте callback_url при отправке. Когда задача завершится, успешно или нет, мы отправим POST на этот адрес с тем же JSON, что возвращает запрос статуса, как событие image.completed или image.failed, с заголовками подписи для проверки отправителя. Можно также задать один адрес для всего аккаунта в «Настройки → Webhook». Документация по webhook

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"}'