Nano banana 2.1 Image Generation

Model selection

Model ID	Billing	Images per request	Reference image size
`gemini-nano-banana-2.1`	Actual token usage	1–4	Up to 20MB per image
`gemini-nano-banana-2.1-ext`	Per image, based on resolution tier	1 only	Up to 20MB per image, 50MB total

Both models offer the same output dimensions and image quality. Choose the official version for multiple images in one request, or Ext for per-image cost estimates. Refer to model pricing for current prices.

Info

This is an asynchronous endpoint. A successful submission returns a task_id. Use task queries to retrieve status and images. Poll every 3–5 seconds and allow at least 3 minutes for the overall wait timeout.

Request example

curl --request POST \
  --url https://api.openveer.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gemini-nano-banana-2.1",
    "prompt": "An orange cat on a wooden table beside a cup of coffee, soft morning light, realistic photography",
    "size": "16:9",
    "resolution": "2K",
    "n": 1
  }'

import requests

response = requests.post(
    "https://api.openveer.com/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "gemini-nano-banana-2.1",
        "prompt": "An orange cat on a wooden table beside a cup of coffee, soft morning light, realistic photography",
        "size": "16:9",
        "resolution": "2K",
        "n": 1
    }
)
print(response.json())

const response = await fetch("https://api.openveer.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gemini-nano-banana-2.1",
    prompt: "An orange cat on a wooden table beside a cup of coffee, soft morning light, realistic photography",
    size: "16:9",
    resolution: "2K",
    n: 1
  })
});
console.log(await response.json());

Response example

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K..."
    }
  ]
}

Request headers

Authorization string

Bearer authentication in the format Bearer <token>, where <token> is your OpenVeer API Key.

Request parameters

model string

Model ID: gemini-nano-banana-2.1 or gemini-nano-banana-2.1-ext.

prompt string

A text description for image generation or editing. Chinese and English are supported.

size string

Output aspect ratio. Supports 1:4, 4:1, 1:8, 8:1, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, and 21:9. Formats such as 16x9 are also accepted.

If omitted or set to auto, the model decides. Image-to-image output follows the reference image aspect ratio.

The official version supports all 14 ratios at 1K, 2K, and 4K. Ext supports 1:4, 4:1, 1:8, and 8:1 only at 1K. At 2K and 4K, Ext supports only the other 10 ratios.

resolution string

Output resolution tier: 1K, 2K, or 4K. Lowercase values are accepted. This also affects billing.

0.5K and 512 are not supported and return HTTP 400 on submission. Other unrecognized values, such as 3K, use 1K for both generation and billing. Use only the supported values above.

n integer

Number of output images: 1–4 for the official version; only 1 for Ext.

Values above 4 return HTTP 400 immediately. Ext requests with 2–4 fail during execution and receive a full refund. Submit separate Ext tasks or use the official version for multiple images.

image_urls string[]

Reference image list. Omit for text-to-image; provide for image-to-image or editing. Each item supports:

A publicly accessible HTTP(S) image URL.
A Base64 Data URL, such as data:image/png;base64,....

PNG, JPEG, or WEBP is recommended. The official version allows up to 20MB per image. Ext allows up to 20MB per image and 50MB in total.

The platform has no fixed reference image count limit, but uploads are not unlimited: exceeding model limits may cause task failure and a refund. More reference images usually take longer.

official_fallback boolean

Only applies to gemini-nano-banana-2.1-ext. When enabled, attempts to complete the task using the official version if Ext fails.

If the official version is actually used, billing switches to its actual token usage instead of Ext per-image pricing.

webhook string

Callback URL notified when the task ends. See task webhooks.

Output dimension reference

Aspect ratio	1K	2K	4K
1:1	1024×1024	2048×2048	4096×4096
2:3	848×1264	1696×2528	3392×5056
3:2	1264×848	2528×1696	5056×3392
3:4	896×1200	1792×2400	3584×4800
4:3	1200×896	2400×1792	4800×3584
4:5	928×1152	1856×2304	3712×4608
5:4	1152×928	2304×1856	4608×3712
9:16	768×1376	1536×2752	3072×5504
16:9	1376×768	2752×1536	5504×3072
21:9	1584×672	3168×1344	6336×2688

These dimensions include measured values and reference values from the model family. Not all combinations have been tested. The actual returned image determines the pixel dimensions.

Edit a reference image

{
  "model": "gemini-nano-banana-2.1-ext",
  "prompt": "Put a red knitted hat on the cat in the image and leave everything else unchanged",
  "image_urls": ["https://example.com/cat.jpg"],
  "resolution": "1K"
}

Replace the example URL with an accessible image URL. If size is omitted, output follows the reference image aspect ratio.

Batch generation (official version only)

{
  "model": "gemini-nano-banana-2.1",
  "prompt": "Cyberpunk city at night, neon lights, streets after rain",
  "size": "16:9",
  "resolution": "2K",
  "n": 4
}

Submission response

code integer

Response status code. 200 indicates success.

data array

Task submission result. status is submitted. Use task_id to query task status and results; it is not the final image URL.

Query task results

curl --request GET \
  --url https://api.openveer.com/v1/tasks/task_01K... \
  --header 'Authorization: Bearer <token>'

Example success response (the image URL is a placeholder):

{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": ["https://example.com/generated-image.png"],
          "expires_at": 1791417625
        }
      ]
    }
  }
}

Task status	Meaning
`pending`	Queued
`processing`	Generating
`completed`	Success; read the image URL array from `data.result.images[0].url`
`failed`	Failure; read the reason from `data.error.message`. Full refund; `data.cost` is 0

All finished image links are in the data.result.images[0].url array. Generating 4 images gives 4 links in this array. Only finished images are returned; n=1 corresponds to 1 finished image.

Links expire 24 hours after task completion, as indicated by expires_at. Download and save them promptly. Output is PNG or JPEG; refer to the actual file content. data.cost in the query result is the final charge in USD.

Billing

Official version: billed by actual input and output token usage. Prompts and reference images count as input. An amount based on resolution tier and n is reserved at submission, then adjusted to actual usage with a refund or additional charge.
Ext version: resolution-tier unit price × actual image count. Aspect ratio does not affect the tier. If official_fallback is enabled and the official version is actually used, official token-based billing applies.
Refer to model pricing for unit prices. Requests rejected at submission create no task and incur no charge. Failed tasks receive a full refund.

Common errors

Condition	Action
HTTP 400	Check for `0.5K` / `512`, `n` above 4, or reference images exceeding the per-image size limit
HTTP 401	Check the API Key
HTTP 402	Check that the balance covers the reserved amount
HTTP 429	Rate limit reached; retry with backoff
Task failed: unsupported aspect ratio	Check that `size` is supported by the selected model and resolution, or use `auto`
Task failed: multiple images requested with Ext	Set `n` to 1 or use the official version
Task failed: content safety block	Revise the prompt or reference images and retry
Task failed: reference image download failed	Ensure the image URL is publicly accessible

Warning

Nano banana 2.1 and Gemini 3.1 Flash Image are different models; their names are not interchangeable aliases. When migrating from the latter, remove the unsupported 0.5K resolution.

This documentation is built and hosted on Mintlify, a developer documentation platform.