Create an image

01Request

Send JSON with the Authorization and Content-Type: application/json headers. Use a new X-Idempotency-Key for every new image, and the previous one when you repeat the same request: that way you will not pay twice (learn more).

# 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": "2K",
    "aspect_ratio": "16:9"
  }'

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": "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 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",
    "X-Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    model: "nano-banana-pro",
    prompt: "A ceramic mug on marble, soft window light",
    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}`);
}
// a 202 response: {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

The task identifier. You use it to get the result: Tasks and statuses.

status

Right after acceptance, queued.

task_id

The task identifier. In GET /creations/{id} use id.

cost

The amount charged for the image, in dollars: a number with four decimal places of precision.

202 Accepted means “request accepted,” not “image ready.”

02Build a request

Build the request body and see the price. Each model has its own resolutions and aspect ratios. A grayed-out option cannot be selected: click it to see the response the API would return to refuse it, without charging anything.

{
  "model": "nano-banana-pro",
  "prompt": "A ceramic mug on marble, soft window light",
  "resolution": "2K",
  "aspect_ratio": "16:9"
}

03Request fields

The size of the image is set by resolution: it is the model’s size level, not an exact number of pixels. The width and height fields are not accepted. If you need an exact size, look at the dimensions of the file you receive.

04What is checked before the charge

These checks run before the charge. If the API answered 400 ERR_INVALID_REQUEST, the balance has not changed, and error.details says what to fix.

• prompt is missing, empty, or made only of spaces.
• The chosen model does not have the resolution or aspect_ratio you passed—the list of allowed values arrives in details.supported.
• n greater than 1, or width or height, is passed.
• There is a mask (mask, mask_file_id): masks are not supported. Pass the source image as a reference image and describe the edit in the prompt.
• Reference images from two families at once (for example, image_file_ids and image_urls), or more than 14 of them.
• The webhook_url address is invalid or not allowed.

05Price and charge

The price depends on the model and the resolution. For example, Nano Banana Pro costs $0.04 at 1K and $0.07 at 4K, and GPT Image 2 costs $0.02 per image. All prices are on the “Models and parameters” page and in the GET /models response.

The amount is charged when the request is accepted, before work starts, and arrives in the cost field. You can check the balance with a GET /balance request.

06What’s next