01Getting started
Nano Banana & GPT Image API documentation
Get a key, send one request, and download the finished image. It takes five minutes.
This model doesn’t produce every resolution and aspect ratio: the examples use the ones available to it.
What you need
- A Rendergrid account and an API key—how to get one.
- A balance in US dollars. A Nano Banana Pro image at 1K costs $0.04, so $1 buys 25 images. Prices for all models are on the pricing page.
- Any language that can send HTTPS requests. The examples use curl, Python with the
requestspackage, and Node.js 22+.
Start with a small top-up: the price is charged per image, and a failed request is free—the amount goes straight back to your balance.
Step 1. Get a key
In the portal, open “API keys” and click “Create key”. A key looks like rg_live_ followed by 40 more characters. It is shown once, so copy it right away.
Put the key in an environment variable on your server. That keeps it out of your code and out of your repository.
$ export RENDERGRID_API_KEY="rg_live_your_key"
A key is the password to your balance. Don’t paste it into website or mobile app code: send API requests from your server only.
Step 2. Send a request
The first image needs three fields: model, prompt, and, if the aspect ratio matters, aspect_ratio. The X-Idempotency-Key header protects you from a double charge if you have to repeat the request.
# Requires bash, curl, and uuidgen. One idempotency key per request. 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": "A ceramic mug on marble, soft window light", "resolution": "1K", "aspect_ratio": "4:5" }'
import os import uuid import requests key = os.environ["RENDERGRID_API_KEY"] payload = { "model": "nano-banana-pro", "prompt": "A ceramic mug on marble, soft window light", "resolution": "1K", "aspect_ratio": "4:5", } response = requests.post( "https://api.rendergrid.io/ api/ public/ v1/ images/ generate", headers={ "Authorization": f"Bearer {key}", # a new key for every request; the same key when you repeat one "X-Idempotency-Key": str(uuid.uuid4()), }, json=payload, timeout=(10, 120), ) response.raise_for_status() creation = response.json() print(creation["id"], creation["status"], creation["cost"])
// Node.js 22+, .mjs file 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", // a new key for every request; the same key when you repeat one "X-Idempotency-Key": randomUUID(), }, body: JSON.stringify({ model: "nano-banana-pro", prompt: "A ceramic mug on marble, soft window light", resolution: "1K", aspect_ratio: "4:5", }), signal: AbortSignal.timeout(120_000), }); if (!response.ok) { const body = await response.text(); throw new Error(`HTTP ${response.status}: ${body}`); } const creation = await response.json(); console.log(creation.id, creation.status, creation.cost);
The response is 202 Accepted. It means “request accepted,” not “image ready.” Save the id: you will use it to get the result.
{
"id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
"status": "queued",
"task_id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
"cost": 0.04
}cost is the amount in dollars we charged for the image. It is written as a number, for example 0.04.
Step 3. Wait for the result
An image takes from a few seconds to a minute to generate. Check the status at most once every 5 seconds. While the status is queued or processing, keep waiting; completed means the image is ready; failed means it did not work.
CREATION_ID="5b0214ae-9e39-460a-820a-f6ae3e24400b" # the ID from step 2 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" # the ID from step 2 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 time.sleep(5) # do not ask more often than once every 5 seconds if creation["status"] == "completed": print(creation["result_urls"]) else: print(creation["error"], creation["failure"])
// Node.js 22+, .mjs file const API = "https://api.rendergrid.io/ api/ public/ v1"; const key = process.env.RENDERGRID_API_KEY; const headers = { Authorization: `Bearer ${key}` }; // the ID from step 2 const creationId = "5b0214ae-9e39-460a-820a-f6ae3e24400b"; let creation; do { // do not ask more often than once every 5 seconds await new Promise((resolve) => setTimeout(resolve, 5000)); const url = `${API}/creations/${creationId}`; const res = await fetch(url, { headers }); if (!res.ok) { throw new Error(`HTTP ${res.status}: ${await res.text()}`); } creation = await res.json(); } while (["queued", "processing"].includes(creation.status)); console.log(creation.status); console.log(creation.result_urls ?? creation.error);
{
"id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
"status": "completed",
"result_urls": ["https://A failed request is free: the amount goes straight back to your balance.
So a failed request can be repeated—see retries without a double charge.
Instead of polling, you can receive an event when the image is ready: webhooks. All statuses and response fields are on the “Tasks and statuses” page.
Step 4. Download the image
The links in result_urls stay valid for a day, and then the file is deleted. Save the image on your side as soon as the status is completed.
$ curl -L -o result.jpg \ "https://cdn.rendergrid.io/ images/ example/ result.jpg"
That’s it: a key, a request, and your first image. Next you can add reference images, choose another model, or set up webhooks.