Nano Banana 2.1 · API

Quick start

Three steps: submit a job, poll it, take the image link. Replace YOUR_API_KEY with your key and the commands below run as they are.

curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2.1", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "16:9", "resolution": "2K"}'

{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281500,
  "model": "nano-banana-2.1"
}

curl https://nezhagate.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281500,
  "model": "nano-banana-2.1",
  "data": [
    {"url": "https://img.nezhagate.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "nano-banana-2.1"}
}

Step 3 · data[0].url is the image (PNG). It is kept for 60 days; download it to your own storage to keep it longer.

import time
import requests

BASE = "https://nezhagate.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. submit
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "nano-banana-2.1",
    "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field",
    "size": "16:9",
    "resolution": "2K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. poll every 3 seconds until it finishes
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. download the image
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("nano-banana-2.1.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["message"])

Authentication

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Create an API Key in the console to start.

Request body

Request example

# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "nano-banana-2.1", "prompt": "a serene ink-wash poster, lots of negative space", "size": "16:9", "resolution": "2K"}'
# 2) poll until status=succeeded
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'

import time, requests

base, key = "https://nezhagate.com/v1", "YOUR_API_KEY"
h = {"Authorization": f"Bearer {key}"}
job = requests.post(f"{base}/images/generations", headers=h,
                    json={"model": "nano-banana-2.1", "prompt": "an ink-wash poster", "size": "16:9", "resolution": "2K"}).json()
while True:
    r = requests.get(f"{base}/images/jobs/{job['id']}", headers=h).json()
    if r["status"] in ("succeeded", "failed"): break
    time.sleep(3)
print(r.get("data", [{}])[0].get("url"))

const base = "https://nezhagate.com/v1", key = "YOUR_API_KEY";
const h = { Authorization: `Bearer ${key}`, "Content-Type": "application/json" };
const job = await (await fetch(`${base}/images/generations`, { method: "POST", headers: h,
  body: JSON.stringify({ model: "nano-banana-2.1", prompt: "an ink-wash poster", size: "16:9", resolution: "2K" }) })).json();
let r;
do { await new Promise(s => setTimeout(s, 3000));
     r = await (await fetch(`${base}/images/jobs/${job.id}`, { headers: h })).json();
} while (r.status !== "succeeded" && r.status !== "failed");
console.log(r.data?.[0]?.url);

Response

{
  "id": "img_3f9a...c2",
  "object": "image.generation.job",
  "status": "queued",
  "model": "nano-banana-2.1"
}

Price

Billed per image by resolution tier only: aspect ratio, text-to-image or image-to-image make no difference. The tier price is held when you submit and refunded in full if the job fails. 1 credit = $0.005.

Each job returns exactly one image: whatever n you send, you get one image and pay for one. For several images, submit several jobs at once (an account renders up to 50 at the same time).

Aspect ratio, resolution and output size

Put the ratio in size and the tier in resolution (1K by default, 2K or 4K). The model renders at the chosen ratio directly; it does not draw a square and crop it. The delivered image has a longest side of 1024 / 2048 / 4096 pixels and the other side follows the ratio. Common ratios:

Besides these seven, 4:5, 5:4, 21:9, 1:4, 4:1, 1:8 and 8:1 also render natively (same longest-side rule). Any other ratio is drawn at the closest landscape, portrait or square shape and then cropped to your ratio, which can cut off part of the picture.

size can also be a pixel size (e.g. 1536x1024): the image is delivered at exactly that size and the tier follows the longest side: up to 1536 is 1K, up to 2048 is 2K, larger is 4K. resolution accepts only 1K / 2K / 4K (any case); any other value is ignored and the tier comes from size, 1K by default. Without size you get a 1:1 square.

Image-to-image and reference images

• Send image (one picture) or images (several, up to 8; only the first 8 are used if you send more) and the job runs image-to-image; say in the prompt what to change. POST /v1/images/edits takes the same parameters.
• Each reference can be a public image URL (http or https), a data: URI or plain base64, up to 16MB each, in a common format such as JPEG, PNG or WebP.
• A URL has to download the image itself: not a web page, and not behind a login or hotlink protection. A reference we cannot read is refused at submit with 400 and the reason; no job is created and nothing is charged.
• The output ratio comes from size, not from the reference. To keep the original ratio, set size to it.
• We host the references for you and keep them for 7 days.

curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2.1", "prompt": "Keep the people, change the background to a beach at night with warm string lights", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'

Job status and fields

GET /v1/images/jobs/{id} always returns id, object (image.generation.job), status, created (Unix seconds) and model; the other fields depend on the status:

Poll every 2-3 seconds. One account renders up to 50 images at a time; further jobs wait in submission order, and a job that has not started after 15 minutes fails and is refunded in full. Job records are kept for 3 days, after which the job id returns 404, but the image link stays valid for its 60 days. Only the account that submitted a job can read it.

How long it takes

Typical time from submit to result, as a guide. Image-to-image takes a few to a dozen seconds longer; a job the gateway re-runs on another line can take 1-2 minutes.

Errors and refunds

Every error has the same shape, {"error": {"message", "type", "code", "param"}}; branch on code.

Errors returned at submit (no job is created and nothing is charged)

Failed jobs (the job was accepted and later ended with status failed; the hold is refunded in full)

Use a webhook instead of polling

For production, add callback_url when you submit. When the job ends, successfully or not, we POST the same JSON as the job endpoint to that URL as image.completed or image.failed, with signature headers you can verify. You can also set one URL for the whole account under Settings > Webhook. Webhook docs

curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2.1", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'