Reference images

01How to pass reference images

Reference images are optional: without them the model draws from the text alone. If you need them, choose one family of fields: a file you uploaded in advance, or an image address.

{
  "model": "nano-banana-pro",
  "prompt": "Keep the lamp, put it on a light windowsill",
  "resolution": "2K",
  "image_file_ids": ["ea7b3c89972d3657"]
}

{
  "model": "nano-banana-pro",
  "prompt": "Keep the lamp, put it on a light windowsill",
  "resolution": "2K",
  "image_urls": ["https://cdn.example.com/products/lamp.png"]
}

02Uploading a file

Send the file as multipart/form-data: the file field is the file itself, and the kind field has the value image. The response contains a file_id: put it in the generation request.

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 file
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

The file identifier. It belongs to the account that uploaded it.

url

The address of a copy of the file. This is not permanent storage: after expires_at you cannot use it.

expires_at

When file_id stops working: 24 hours after the upload.

Check the file before sending

This is how the API responds to the most common files. All of these refusals arrive immediately, before generation.

03An address instead of a file

If the image is already online, do not upload it: pass the link in image_urls. Our server downloads the image, so the link must open from outside without signing in.

• A public http:// or https:// address on port 80 or 443. Addresses on internal networks and links with a username and password inside do not work.
• Redirects are not followed: give the final address of the image.
• The response must be a PNG, JPEG, or WebP image of no more than 25 MiB.
• The source must respond quickly: the download time is limited. If the source is slow or password-protected, download the file yourself and upload it through POST /uploads.

04How to prepare reference images

• Say in the prompt what to keep and what to change. The model sees the reference image but does not know what you want from it.
• Up to 14 reference images per request.
• A reference image heavier than 7 MiB or longer than 4,096 pixels on its long side may be downscaled or recompressed before processing. For large images with a transparent background, the background may become white.
• Keep the originals yourself: file_id is valid for 24 hours after the upload, and the file itself is deleted 48 hours after the last upload.
• Masks (inpainting) are not supported. Pass the source image as a reference image and describe the edit in words.

05What can go wrong

These refusals arrive before the charge: the balance does not change.

If a reference image becomes unavailable after the request is accepted, the task ends with the status failed and failure.code: reference_unavailable or reference_fetch_failed. For more, see “Error codes.”

FAQFrequently asked questions