Nano Banana 2.1 API: первая картинка за пять минут

01Что понадобится, чтобы отправить первый запрос?

Нужны аккаунт Rendergrid, деньги на балансе и ключ API. Порядок такой: создайте ключ, пополните баланс, отправьте запрос.

Ключ API. В личном кабинете откройте раздел «Ключи API» и нажмите «Создать ключ». Рабочий ключ начинается с rg_live_, а целиком его показывают один раз, при создании, поэтому сразу сохраните его. Потерянный ключ восстановить нельзя: создайте новый. Подробности — на странице «Ключи и вход».

Баланс. Пополнить его можно в USDT, в разделе «Баланс и пополнение». Начните с небольшой суммы: цена списывается за каждую картинку. У пополнения своё окно оплаты, и в «пять минут» статьи оно не входит. Как оно устроено, написано на странице «Пополнение USDT».

Инструменты. Подойдёт любой язык, который отправляет HTTPS-запросы. В примерах — curl, Python с пакетом requests и Node.js 22+. Положите ключ в переменную окружения RENDERGRID_API_KEY: все примеры читают его оттуда. Ключ — пароль от вашего баланса, поэтому не вставляйте его в код сайта или мобильного приложения и отправляйте запросы только с сервера.

02Как отправить запрос на генерацию?

Одна картинка — один POST-запрос на /api/public/v1/images/generate. Ключ API идёт в заголовке Authorization: Bearer <ключ>, а тело запроса — это JSON с такими полями:

• model — модель: nano-banana-2.1.
• prompt — описание картинки. Поле обязательное: пустой промпт получит ответ 400 без списания. Длина — до 20 000 символов.
• resolution — 1K, 2K или 4K. Без этого поля картинка рисуется в 2K.
• aspect_ratio — формат кадра, например 1:1. Без этого поля будет 1:1.

Заголовок X-Idempotency-Key защищает от двойного списания: на каждую новую картинку берите новое значение, а при повторе того же запроса — прежнее. Подробнее — на странице о повторах без двойного списания.

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

# Нужны bash, curl и uuidgen. Ключ повтора — один на запрос.
IDEMPOTENCY_KEY="$(uuidgen)" || exit 1
curl --fail-with-body --max-time 30 \
  -X POST https://api.rendergrid.io/api/public/v1/images/generate \
  -H "Authorization: Bearer $RENDERGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "model": "nano-banana-2.1",
    "prompt": "На светлом письменном столе лежит закрытая тетрадь в льняной обложке, рядом деревянный карандаш и белая керамическая чашка. Съёмка слегка сверху, все три предмета в центре с равными свободными полями. Мягкий свет из окна слева, отчётливо видны ткань обложки, дерево и глазурь. Без надписей, логотипов, людей и водяных знаков.",
    "resolution": "1K",
    "aspect_ratio": "1:1"
  }'

import os
import uuid

import requests

API = "https://api.rendergrid.io/api/public/v1"
KEY = os.environ["RENDERGRID_API_KEY"]
PROMPT = "На светлом письменном столе лежит закрытая тетрадь в льняной обложке, рядом деревянный карандаш и белая керамическая чашка. Съёмка слегка сверху, все три предмета в центре с равными свободными полями. Мягкий свет из окна слева, отчётливо видны ткань обложки, дерево и глазурь. Без надписей, логотипов, людей и водяных знаков."

response = requests.post(
    f"{API}/images/generate",
    headers={
        "Authorization": f"Bearer {KEY}",
        # новый на каждую картинку; при повторе того же запроса — прежний
        "X-Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "model": "nano-banana-2.1",
        "prompt": PROMPT,
        "resolution": "1K",
        "aspect_ratio": "1:1",
    },
    timeout=(10, 120),
)
response.raise_for_status()
creation = response.json()
print(creation["id"], creation["status"], creation["cost"])

// Node.js 22+, файл .mjs
import { randomUUID } from "node:crypto";

const API = "https://api.rendergrid.io/api/public/v1";
const prompt = "На светлом письменном столе лежит закрытая тетрадь в льняной обложке, рядом деревянный карандаш и белая керамическая чашка. Съёмка слегка сверху, все три предмета в центре с равными свободными полями. Мягкий свет из окна слева, отчётливо видны ткань обложки, дерево и глазурь. Без надписей, логотипов, людей и водяных знаков.";

const response = await fetch(`${API}/images/generate`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RENDERGRID_API_KEY}`,
    "Content-Type": "application/json",
    // новый на каждую картинку; при повторе того же запроса — прежний
    "X-Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    model: "nano-banana-2.1",
    prompt,
    resolution: "1K",
    aspect_ratio: "1:1",
  }),
  signal: AbortSignal.timeout(120_000),
});
if (response.status !== 202) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
const creation = await response.json();
console.log(creation.id, creation.status, creation.cost);

Ответ 202 Accepted значит «запрос принят», а не «картинка готова». В теле — id, status со значением queued, task_id и cost: сумма в долларах, которую списали с баланса при приёме запроса. Сохраните id: по нему вы узнаете результат.

Деньги списываются до начала работы, а если картинки не будет, сумма сразу вернётся на баланс. Как это выглядит в ответе API и в кабинете, разобрано в статье «Неудачный запрос бесплатен: как устроена оплата за картинку».

03Как узнать, что картинка готова?

Картинка делается в фоне, поэтому после 202 результат нужно запросить: GET /api/public/v1/creations/{id} с тем же ключом. Подставьте id из ответа на запрос. Статус может быть таким:

• queued — запрос принят и ждёт очереди.
• processing — картинка рисуется.
• completed — готово: ссылки на файлы лежат в result_urls.
• failed — картинку получить не удалось: в ответе будут error и failure с полями type, code и retryable.

Пока статус queued или processing, спросите ещё раз через 5 секунд или позже, а на completed и failed опрос прекратите. Одно задание одним ключом можно опрашивать не чаще раза в 5 секунд: на более частые запросы API ответит 429 ERR_RATE_LIMIT. О лимитах и повторах с паузой — в статье «Ошибка 429 и лимиты: как генерировать без отказов».

CREATION_ID="5b0214ae-9e39-460a-820a-f6ae3e24400b"  # id из ответа на запрос
curl --fail-with-body --max-time 20 \
  "https://api.rendergrid.io/api/public/v1/creations/$CREATION_ID" \
  -H "Authorization: Bearer $RENDERGRID_API_KEY"

import os
import time

import requests

API = "https://api.rendergrid.io/api/public/v1"
KEY = os.environ["RENDERGRID_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}"}
creation_id = "5b0214ae-9e39-460a-820a-f6ae3e24400b"  # id из ответа на запрос
MAX_WAIT = 300  # секунд: ваш предел ожидания, а не срок сервиса

started = time.monotonic()
while True:
    r = requests.get(f"{API}/creations/{creation_id}", headers=HEADERS, timeout=(5, 20))
    r.raise_for_status()
    creation = r.json()
    if creation["status"] in ("completed", "failed"):
        break
    if time.monotonic() - started > MAX_WAIT:
        raise TimeoutError(f"{creation_id}: не дождались, спросите позже")
    time.sleep(5)  # чаще раза в 5 секунд спрашивать нельзя

if creation["status"] == "completed":
    print(creation["result_urls"])
else:
    print(creation["error"], creation["failure"])

// Node.js 22+, файл .mjs
const API = "https://api.rendergrid.io/api/public/v1";
const headers = { Authorization: `Bearer ${process.env.RENDERGRID_API_KEY}` };
const creationId = "5b0214ae-9e39-460a-820a-f6ae3e24400b"; // id из ответа на запрос
const MAX_WAIT_MS = 300_000; // ваш предел ожидания, а не срок сервиса
const pending = (status) => status === "queued" || status === "processing";

const started = Date.now();
let creation;
do {
  // чаще раза в 5 секунд спрашивать нельзя
  await new Promise((resolve) => setTimeout(resolve, 5000));
  const res = await fetch(`${API}/creations/${creationId}`, {
    headers,
    signal: AbortSignal.timeout(20_000),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  creation = await res.json();
  if (pending(creation.status) && Date.now() - started > MAX_WAIT_MS) {
    throw new Error(`${creationId}: не дождались, спросите позже`);
  }
} while (pending(creation.status));

console.log(creation.status);
console.log(creation.result_urls ?? creation.error);

Сколько ждать картинку, заранее не обещано: срок зависит от модели и нагрузки, поэтому ограничьте время ожидания в своём коде. Среднее время ожидания за последние 7 дней — 40 с.

{
  "id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
  "status": "queued",
  "task_id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
  "cost": 0.02
}

{
  "id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
  "status": "completed",
  "result_urls": [
    "https://…"
  ]
}

Готовые файлы хранятся сутки, а опрос срок хранения не продлевает: сохраните картинку в своё хранилище сразу после completed. Вместо опроса можно передать в запросе webhook_url — публичный адрес HTTPS, на который придёт событие creation.completed или creation.failed. Опрос при этом оставьте запасным путём. Подробнее — на странице о вебхуках и в статье «Генерация пачками: очередь, вебхуки и ключ идемпотентности».

Если задание стало failed, сумма за него уже вернулась на баланс. Для новой попытки отправьте новый запрос с новым значением X-Idempotency-Key.

04Как выбрать разрешение: 1K, 2K или 4K?

Размер картинки задаёт поле resolution: 1K, 2K или 4K. У Nano Banana 2.1 доступны все три. Это уровень размера модели, а не точное число пикселей: поля width и height API не принимает.

Мы трижды отправили один и тот же промпт — в 1K, 2K и 4K, формат кадра 1:1, по одной попытке на разрешение. Ничего не отбирали и не переделывали.

Один промпт — три разрешения

На светлом письменном столе лежит закрытая тетрадь в льняной обложке, рядом деревянный карандаш и белая керамическая чашка. Съёмка слегка сверху, все три предмета в центре с равными свободными полями. Мягкий свет из окна слева, отчётливо видны ткань обложки, дерево и глазурь. Без надписей, логотипов, людей и водяных знаков.

1K, 2K и 4K · 1:1 · одна попытка на каждоеКопировать промпт

На квадратных кадрах API вернул файлы 1024×1024, 2048×2048 и 4096×4096 пикселей. Предметы везде одни и те же: тетрадь, карандаш и чашка. Но сцена каждый раз новая: это три отдельные генерации, а не один кадр в трёх размерах. На 1K у чашки есть ручка, на 2K и 4K её нет, а расстановка предметов и ракурс разные. Поэтому не ждите, что 4K окажется «тем же кадром, только крупнее»: в этом примере каждое разрешение дало свою композицию.

Цена зависит от разрешения: $0,02 в 1K, $0,03 в 2K и $0,04 в 4K за одну картинку. Без поля resolution картинка рисуется и оплачивается в разрешении по умолчанию, то есть в 2K. Цены Rendergrid и Google в сравнении — в статье «Nano Banana 2.1 API: цена за картинку в 1K, 2K и 4K» и на странице цен.

Для первого запроса хватит 1K: он нужен, чтобы проверить всю цепочку — ключ, запрос и статус. Другое разрешение — это одно изменённое поле resolution.

05Как выбрать формат кадра?

Формат кадра задаёт поле aspect_ratio. У Nano Banana 2.1 на любом разрешении доступны 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2, 5:4, 4:5 и 21:9, а также вытянутые 1:4, 1:8, 4:1 и 8:1. Есть и значение auto: тогда модель выбирает формат кадра сама, но без образцов этот формат не гарантирован. Если от него зависит ваш макет, указывайте aspect_ratio явно.

Значение пишите точно, как в списке: без пробелов и перестановки цифр. Отсутствие поля не значит auto: без него будет 1:1. Кадры этой статьи квадратные; чтобы получить, например, горизонтальный баннер, поменяйте в запросе одно поле: "aspect_ratio": "16:9".

Формат, которого у модели нет, получит ответ 400 ERR_INVALID_REQUEST до списания. В error.details.supported придёт список допустимых значений, а деньги не тратятся. Какие значения доступны вашему аккаунту, покажет GET /models; подробнее — на странице «Модели и параметры».

06Чего этот пример не покрывает?

• Три кадра — не бенчмарк. Одна сцена и одна попытка на разрешение: по ним нельзя судить ни о качестве, ни о скорости, ни о надёжности модели. На ваших промптах результат может быть другим.
• «Пять минут» — не срок генерации. Это время прохождения шагов статьи с пополненным балансом и готовым ключом. Сколько займёт сама картинка, зависит от модели и нагрузки.
• Только генерация по тексту. Картинки-образцы и правки по ним в пример не вошли: они описаны на странице «Картинки-образцы».
• Одна картинка на запрос. Нужно больше — отправляйте несколько запросов в пределах лимитов аккаунта.
• Ключ — только на сервере. Не вставляйте его в код сайта или мобильного приложения.

07Вопросы и ответы

08Источники

1. Быстрый старт — документация RendergridКлюч, запрос, статус и скачивание результата.
2. Создание картинки — документация RendergridПоля запроса, ответ 202 и проверки до списания.
3. Задачи и статусы — документация RendergridСтатусы, интервал опроса и срок хранения файлов.
4. Ключи и вход — документация RendergridКак создать, передать и хранить ключ API.
5. Модели и параметры — документация RendergridРазрешения, форматы кадра и разрешение по умолчанию.
6. Цены RendergridЦена за картинку для каждой модели и разрешения.
7. Три кадра этой статьиОдин промпт в 1K, 2K и 4K, формат 1:1, по одной попытке через публичный API Rendergrid.
8. Статистика RendergridСреднее время ожидания Nano Banana 2.1 за последние 7 дней.