06Основы API
Создание картинки
Один запрос — одна картинка. Опишите, что нарисовать, выберите модель и форму кадра, а результат заберите опросом или вебхуком.
Эта модель рисует не все разрешения и форматы кадра: в примерах стоят те, что ей доступны.
Запрос
/images/ generateОтправьте JSON с заголовками Authorization и Content-Type: application/json. Для каждой новой картинки берите новый 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": "2K", "aspect_ratio": "16:9" }'
import os import uuid import requests key = os.environ["RENDERGRID_API_KEY"] payload = { "model": "nano-banana-pro", "prompt": "Керамическая кружка на мраморе, мягкий свет окна", "resolution": "2K", "aspect_ratio": "16:9", } response = requests.post( "https://api.rendergrid.io/ api/ public/ v1/ images/ generate", headers={ "Authorization": f"Bearer {key}", "X-Idempotency-Key": str(uuid.uuid4()), }, json=payload, timeout=(10, 120), ) response.raise_for_status() creation = response.json() # 202: {id, status, task_id, cost} print(creation["id"])
// Node.js 22+, файл .mjs import { randomUUID } from "node:crypto"; const API = "https://api.rendergrid.io/ api/ public/ v1"; 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: "2K", aspect_ratio: "16:9", }), signal: AbortSignal.timeout(120_000), }); if (response.status !== 202) { const body = await response.text(); throw new Error(`HTTP ${response.status}: ${body}`); } // ответ 202: {id, status, task_id, cost} const creation = await response.json(); console.log(creation.id);
{
"id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
"status": "queued",
"task_id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
"cost": 0.04
}- id
- Идентификатор задания. По нему вы получите результат: Задачи и статусы.
- status
- Сразу после приёма —
queued. - task_id
- Идентификатор задачи. В
GET /creations/подставляйте{id} id. - cost
- Сумма, списанная за картинку, в долларах: число с точностью до четырёх знаков.
202 Accepted значит «запрос принят», а не «картинка готова».
Соберите запрос
Соберите тело запроса и посмотрите цену. У каждой модели свои разрешения и форматы кадра. Серый вариант выбрать нельзя: нажмите на него, и вы увидите ответ, которым API откажет, не списав денег.
48 из 20 000 знаков. Сотрите текст — увидите, как API откажет пустому промпту.
Не указали разрешение — будет 2K.
Серые форматы эта модель не рисует. Не указали формат — будет 1:1; auto — выбор модели.
{
"model": "nano-banana-pro",
"prompt": "Керамическая кружка на мраморе, мягкий свет окна",
"resolution": "2K",
"aspect_ratio": "16:9"
}Цена этой картинки: $0,04. Неудачный запрос бесплатен: сумма сразу возвращается на баланс.
Поля запроса
| Поле | Тип | Описание |
|---|---|---|
modelобязательное | string | Идентификатор модели из каталога вашего аккаунта: Модели и параметры. |
promptобязательное | string | Описание картинки или правки, до 20 000 знаков. Нужно всегда, даже когда есть образцы. Пустой промпт или одни пробелы — ответ 400, деньги не списываются. |
aspect_ratioнеобязательное | string | Форма кадра, например 16:9. Без этого поля будет 1:1 — отсутствие поля не значит auto. Допустимые значения зависят от модели. |
resolutionнеобязательное | string | 1K, 2K или 4K, регистр не важен. Допустимые значения и значение по умолчанию зависят от модели. |
output_formatнеобязательное | string | Формат файла результата: png или jpg. Без этого поля файл приходит в исходном формате модели. |
image_file_idsнеобязательное | string[] | До 14 значений file_id из POST /uploads. Для генерации только по тексту не передавайте. Подробнее — Картинки-образцы. |
image_file_idнеобязательное | string | Один file_id. Замена image_file_ids для одного образца; вместе их не передавайте. |
image_urlsнеобязательное | string[] | От 1 до 14 публичных адресов картинок. Не сочетайте с file_id: выберите одно семейство полей. |
webhook_urlнеобязательное | string | Публичный адрес HTTPS до 2048 знаков для уведомления о готовности: Вебхуки. |
Размер картинки задаёт resolution: это уровень размера модели, а не точное число пикселей. Поля width и height не принимаются. Нужен точный размер — смотрите на размеры полученного файла.
Одна картинка на запрос. Нужно больше — отправьте несколько запросов с разными ключами повтора, в пределах лимитов аккаунта.
Что проверяется до списания
Эти проверки идут до списания. Если API ответил 400 ERR_INVALID_REQUEST, баланс не изменился, а в error.details сказано, что исправить.
- Нет
prompt, он пустой или состоит из пробелов. resolutionилиaspect_ratioнет у выбранной модели — вdetails.supportedпридёт список допустимых.- Передан
nбольше 1, а такжеwidthилиheight. - Есть маска (
mask,mask_file_id): маски не поддерживаются. Передайте исходную картинку как образец и опишите правку в промпте. - Образцы из двух семейств сразу (например,
image_file_idsиimage_urls) или больше 14 штук. - Адрес
webhook_urlневерный или запрещённый.
Цена и списание
Цена зависит от модели и разрешения. Например, Nano Banana Pro стоит $0,04 в 1K и $0,07 в 4K, а GPT Image 2 — $0,02 за картинку. Все цены — на странице «Модели и параметры» и в ответе GET /models.
Сумма списывается при приёме запроса, до начала работы, и приходит в поле cost. Баланс можно проверить запросом GET /balance.
Неудачный запрос бесплатен: сумма сразу возвращается на баланс.