Nano Banana Pro API: быстрый старт и первая картинка

01Что нужно до первого запроса?

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

Ключ создаётся в личном кабинете. Он состоит из префикса rg_live_ и ещё 40 знаков и показывается целиком один раз, при создании: потерянный ключ восстановить нельзя, можно только создать новый. Положите его в переменную окружения RENDERGRID_API_KEY на сервере, чтобы он не попал в код и в репозиторий. Подробности — в документации о ключах.

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

Баланс пополняется в USDT в кабинете, а у оплаты есть своё окно: оно описано в документации по пополнению. Цена каждой картинки списывается при приёме запроса, поэтому, если на балансе меньше цены, API ответит 402. Начните с небольшой суммы: платить придётся только за картинки, которые получились.

Какие модели доступны вашему аккаунту и по каким ценам, покажет GET /models. Параметры всех моделей — в разделе «Модели и параметры».

02Как отправить запрос?

Обязательных полей два: model и prompt. Мы добавляем ещё resolution и aspect_ratio, чтобы разрешение и формат кадра не зависели от значений по умолчанию. Заголовок 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-pro",
    "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-pro",
        "prompt": PROMPT,
        "resolution": "1K",
        "aspect_ratio": "1:1",
    },
    timeout=(10, 120),
)
response.raise_for_status()
creation = response.json()  # 202: {id, status, task_id, cost}
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-pro",
    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()}`);
}
// ответ 202: {id, status, task_id, cost}
const creation = await response.json();
console.log(creation.id, creation.status, creation.cost);

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

03Как узнать статус и забрать результат?

Картинка рисуется в фоне, поэтому после 202 нужно спросить статус: GET /creations/{id} с тем же заголовком Authorization. Подставьте id из ответа на запрос. Задание видно только аккаунту, который его создал: чужой или неизвестный id даст 404.

Статусов четыре:

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

completed и failed конечные: опрос можно прекращать. Ответ 200 может нести status: "failed" — это итог задания, а не ошибка самого запроса статуса.

Как часто спрашивать статус

Одно задание одним ключом — не чаще раза в 5 секунд: более частый опрос получит 429. Ограничьте общее время ожидания в коде. Если оно вышло, сохраните id и продолжите позже: тайм-аут вашего клиента задание не отменяет. Заранее обещанного срока нет: он зависит от модели и нагрузки.

Цикл ниже ждёт, пока статус не станет конечным, и сохраняет первый файл. Предел ожидания в нём — настройка примера, а не срок работы модели. Более полный цикл с повторами при обрыве связи, 429 и 5xx — в разделе «Задачи и статусы».

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"

# Повторяйте не чаще раза в 5 секунд, пока status не станет completed или failed.
# Затем сохраните файл по первой ссылке из result_urls:
RESULT_URL="https://…"
curl --fail-with-body --max-time 60 -L -o result-1k "$RESULT_URL"

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 из ответа на запрос

# предел ожидания — настройка примера, а не срок работы модели
deadline = time.monotonic() + 180
while True:
    if time.monotonic() >= deadline:
        raise SystemExit(f"Ещё не готово, сохраните id: {creation_id}")
    time.sleep(5)  # чаще раза в 5 секунд спрашивать нельзя
    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 creation["status"] == "failed":
    raise SystemExit(f"{creation['error']} {creation['failure']}")

image = requests.get(creation["result_urls"][0], timeout=(10, 60))
image.raise_for_status()
print(image.headers.get("Content-Type"))  # по нему определите расширение файла
with open("result-1k", "wb") as file:
    file.write(image.content)

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

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 deadline = Date.now() + 180_000;
let creation;
do {
  if (Date.now() >= deadline) {
    throw new Error(`Ещё не готово, сохраните id: ${creationId}`);
  }
  // чаще раза в 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();
} while (["queued", "processing"].includes(creation.status));

if (creation.status === "failed") {
  throw new Error(`${creation.error} ${JSON.stringify(creation.failure)}`);
}

const image = await fetch(creation.result_urls[0], { signal: AbortSignal.timeout(60_000) });
if (!image.ok) throw new Error(`HTTP ${image.status}`);
console.log(image.headers.get("content-type")); // по нему определите расширение файла
await writeFile("result-1k", Buffer.from(await image.arrayBuffer()));

Весь обмен состоит из двух ответов: ответа на запрос и итогового ответа о статусе.

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

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

Как сохранить результат

result_urls — готовые ссылки на файлы. Берите их как есть: не собирайте из id. Формат файла задаёт поле output_format: png или jpg; без него файл приходит в исходном формате модели. Файлы хранятся сутки, а опрос срок не продлевает, поэтому сохраняйте картинку у себя сразу, как получили ссылку.

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

04Как получить ту же сцену в 1K, 2K и 4K?

Разрешение задаёт поле resolution: 1K, 2K или 4K, регистр не важен. Мы отправили один и тот же промпт трижды через публичный API Rendergrid и поменяли только resolution: по одной попытке на каждое разрешение, формат кадра 1:1. Вот что вышло.

Промпт — один для всех разрешений

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

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

Это три отдельных запроса, поэтому сцена получилась не одной и той же в трёх размерах, а тремя разными кадрами. На 1K флакон стоит, как в промпте. На 2K он лежит на боку, а бумага разложена полосами вместо одного сгиба. На 4K флакон снова стоит, но весь снимок окружён кремовой рамкой. Не ждите, что 2K и 4K повторят композицию 1K, только крупнее: если вам нужен определённый кадр, проверьте результат в том разрешении, в котором будете им пользоваться.

У этих файлов размер вышел 1 024 × 1 024 пикселей в 1K, 2 048 × 2 048 в 2K и 4 096 × 4 096 в 4K. Но resolution — это уровень размера, а не точное число пикселей: поля width и height не принимаются, а точный размер вы узнаете по полученному файлу.

Если resolution не указать, картинка нарисуется и будет оплачена в 2K: это разрешение по умолчанию у Nano Banana Pro.

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

05Сколько стоит картинка и когда списываются деньги?

Цена зависит от разрешения: $0,04 в 1K, $0,04 в 2K и $0,07 в 4K. Точные цены вашего аккаунта возвращает GET /models.

Сумма списывается при приёме запроса, до начала работы, и приходит в поле cost ответа 202. Если картинка не получилась, списание возвращается само: неудачный запрос бесплатен. Баланс можно проверить запросом GET /balance, но чтение ничего не резервирует, поэтому 402 обрабатывайте всегда, даже если проверка прошла.

Как цена складывается у Google и у Rendergrid — в статье «Nano Banana Pro API: цена за картинку у Google и в Rendergrid». Цены всех моделей — на странице цен.

06Что ответит API, если что-то пошло не так?

• 401, ERR_API_KEY_INVALID. Ключ не передан, неверный, отозван или просрочен. Проверьте, что заголовок Authorization доходит до API, или создайте новый ключ.
• 402, ERR_INSUFFICIENT_BALANCE. На балансе меньше цены картинки либо исчерпан месячный лимит ключа или аккаунта, если он задан. Пополните баланс или поднимите лимит.
• 400, ERR_INVALID_REQUEST. Нет prompt или у модели нет такого resolution либо aspect_ratio. Деньги не списаны: в error.details сказано, что исправить, а в details.supported придёт список допустимых значений.
• 404, ERR_NOT_FOUND. Такого id нет, или он принадлежит другому аккаунту. Проверьте id и убедитесь, что ключ из того же аккаунта.
• 429, ERR_RATE_LIMIT. Статус спросили слишком рано или превышены лимиты аккаунта. Ждите не меньше details.min_interval_seconds и не меньше, чем указано в заголовке Retry-After. Лимиты описаны в разделе «Лимиты».
• 200 со status: "failed". Задание не удалось. Читайте failure.type, failure.code и failure.retryable. Сумма за такое задание вернулась на баланс сама.

Причину отказа читайте по error.code и error.details.reason, а не по тексту сообщения. Все коды — в справочнике ошибок.

07Где этот гайд не подходит?

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

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

09Источники

1. Документация Rendergrid: быстрый стартКлюч, запрос, статус и результат в curl, Python и Node.js.
2. Документация Rendergrid: создание картинкиПоля запроса, ответ 202 и проверки до списания.
3. Документация Rendergrid: задачи и статусыСтатусы, частота опроса и срок хранения файлов.
4. Документация Rendergrid: модели и параметрыРазрешения, форматы кадра и значения по умолчанию.
5. Цены RendergridЦена за картинку для каждой модели и разрешения.
6. Три картинки этой статьиПромпт и параметры — в блоке с картинками: по одной попытке на каждое разрешение через API Rendergrid.