Картинки-образцы

01Как передать образец

Образцы необязательны: без них модель рисует по одному тексту. Если они нужны, выберите одно семейство полей: файл, который вы загрузили заранее, или адрес картинки.

{
  "model": "nano-banana-pro",
  "prompt": "Оставь лампу, поставь её на светлый подоконник",
  "resolution": "2K",
  "image_file_ids": ["ea7b3c89972d3657"]
}

{
  "model": "nano-banana-pro",
  "prompt": "Оставь лампу, поставь её на светлый подоконник",
  "resolution": "2K",
  "image_urls": ["https://cdn.example.com/products/lamp.png"]
}

02Загрузка файла

Отправьте файл как multipart/form-data: поле file — сам файл, поле kind со значением image. В ответ придёт file_id: его и подставляйте в запрос генерации.

curl --fail-with-body --connect-timeout 10 --max-time 120 \
  -X POST https://api.rendergrid.io/api/public/v1/uploads \
  -H "Authorization: Bearer $RENDERGRID_API_KEY" \
  -F "file=@lamp.png;type=image/png" \
  -F "kind=image"

import os
import requests

key = os.environ["RENDERGRID_API_KEY"]
with open("lamp.png", "rb") as image:
    response = requests.post(
        "https://api.rendergrid.io/api/public/v1/uploads",
        headers={"Authorization": f"Bearer {key}"},
        files={"file": ("lamp.png", image, "image/png")},
        data={"kind": "image"},
        timeout=(10, 120),
    )
response.raise_for_status()
upload = response.json()
print(upload["file_id"], upload["expires_at"])

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

const bytes = await readFile("lamp.png");
const file = new Blob([bytes], { type: "image/png" });
const form = new FormData();
form.append("file", file, "lamp.png");
form.append("kind", "image");

const API = "https://api.rendergrid.io/api/public/v1";
const key = process.env.RENDERGRID_API_KEY;
const response = await fetch(`${API}/uploads`, {
  method: "POST",
  headers: { Authorization: `Bearer ${key}` },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) {
  const body = await response.text();
  throw new Error(`HTTP ${response.status}: ${body}`);
}
const upload = await response.json();
console.log(upload.file_id, upload.expires_at);

{
  "file_id": "ea7b3c89972d3657",
  "url": "https://cdn.rendergrid.io/user_uploads/example.png",
  "expires_at": "2026-10-14T12:00:00+00:00"
}

file_id

Идентификатор файла. Принадлежит аккаунту, который его загрузил.

url

Адрес копии файла. Это не постоянное хранилище: после expires_at им пользоваться нельзя.

expires_at

Когда file_id перестанет работать: через 24 часа после загрузки.

Проверьте файл до отправки

Так API ответит на самые частые файлы. Все отказы приходят сразу, ещё до генерации.

03Адрес вместо файла

Если картинка уже лежит в интернете, не загружайте её: передайте ссылку в image_urls. Скачивает картинку наш сервер, поэтому ссылка должна открываться снаружи без входа.

• Публичный адрес http:// или https:// на порту 80 или 443. Адреса внутренних сетей и ссылки с логином и паролем внутри не подходят.
• Переадресации не выполняются: укажите конечный адрес картинки.
• Ответ должен быть картинкой PNG, JPEG или WebP не больше 25 МиБ.
• Источник должен отвечать быстро: время скачивания ограничено. Если источник медленный или закрыт паролем, скачайте файл у себя и загрузите через POST /uploads.

04Как подготовить образцы

• Опишите в prompt, что сохранить и что изменить. Модель видит образец, но не знает, чего вы от него хотите.
• В одном запросе — до 14 образцов.
• Образец тяжелее 7 МиБ или длиннее 4096 пикселей по длинной стороне может быть уменьшен или пережат перед работой. У больших картинок с прозрачным фоном фон может стать белым.
• Храните оригиналы у себя: file_id действует 24 часа после загрузки, а сам файл удаляется через 48 часов после последней загрузки.
• Маски (inpainting) не поддерживаются. Передайте исходную картинку образцом и опишите правку словами.

05Что может пойти не так

Эти отказы приходят до списания: баланс не меняется.

Если образец стал недоступен уже после приёма запроса, задание завершится статусом failed с failure.code: reference_unavailable или reference_fetch_failed. Подробнее — «Коды ошибок».

FAQЧастые вопросы