Generate an image

Submits an asynchronous image generation. The request is validated, priced, and charged up front, then accepted with 202 and a creation id; if generation later fails, the charge is refunded in full. Available models: nano-banana-2 and nano-banana-pro — see Models.

Request

Send a JSON body with your API key and Content-Type: application/json. An optional X-Idempotency-Key header makes the request safe to retry — see Idempotency.

Text-to-image

The minimal request is a model and a prompt:

curl -X POST https://api.rendergrid.io/api/public/v1/images/generate \
  -H "Authorization: Bearer rg_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "a lighthouse on a cliff at golden hour, dramatic clouds",
    "aspect_ratio": "16:9"
  }'

Response — 202 Accepted

Success is 202 Accepted. id is the creation id to poll (task_id is accepted interchangeably by GET /creations/{id}), status starts at queued, and cost is the amount charged, in USD, rounded to 2 decimal places:

{
  "id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
  "status": "queued",
  "task_id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
  "cost": 0.1
}

When the creation completes, polling it returns the output URLs:

{
  "id": "c0ea4d5b-c965-4943-aaad-76fda0c53ca9",
  "status": "completed",
  "result_urls": [
    "https://cdn.rendergrid.io/images/2026/07/02/d13e03c7-7897-48b5-8571-8cd1e78e5f45/8b5f7dcb_20260702_100059_0f9a5d99_req_c0ea4d5b.jpg"
  ]
}

Image-to-image

Upload input images first via POST /uploads — a multipart form with a file part and kind=image (max 25 MiB per image). The returned file_id is valid for 24 hours and is passed as image_file_id (single input) or image_file_ids (multiple references):

# 1. Upload the reference image
curl -X POST https://api.rendergrid.io/api/public/v1/uploads \
  -H "Authorization: Bearer rg_live_xxx" \
  -F "file=@product.png" \
  -F "kind=image"
# -> {"file_id": "ea7b3c89972d3657", "url": "https://cdn.rendergrid.io/…", "expires_at": "…"}

# 2. Generate, referencing the file id
curl -X POST https://api.rendergrid.io/api/public/v1/images/generate \
  -H "Authorization: Bearer rg_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "place this product on a marble pedestal in soft studio light",
    "image_file_ids": ["ea7b3c89972d3657"]
  }'

Costs

Both models bill per image, in USD. List prices (your contract may carry per-model overrides — GET /models always returns your effective prices):

• nano-banana-2 — $0.10 per image at every resolution (1K / 2K / 4K).
• nano-banana-pro — $0.10 per image at every resolution (1K / 2K / 4K).

Each resolution bills its own variant, selected by your request parameters (e.g. resolution: "2K" bills the 2k variant) and charged at generation time; the charged total is returned as cost — a USD amount — in the 202 response.

Batching (n > 1)

Set n (1–4) to generate several images from one request. The whole batch is a single creation: cost is the per-image price multiplied by n, and all outputs are returned together in result_urls when the creation completes.

Webhooks

Pass a webhook_url to receive a signed POST callback the moment the creation reaches a terminal status instead of polling. The URL is set per request, must be HTTPS, and every delivery is HMAC-signed — see Webhooks for headers, signature verification, and retry behavior.

Common errors

Validation failures return 400 ERR_INVALID_REQUEST with the field-level problems in details.errors. Other errors you should handle explicitly:

See Errors for the error envelope and the complete code table.