> ## Documentation Index
> Fetch the complete documentation index at: https://docs.freemodel.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Nano Banana 2.1

> Generate and edit 1K, 2K and 4K images with nano-banana-2.1 and predictable per-image billing.

Use `nano-banana-2.1` to generate a new image from text or edit with reference images. Each request delivers one image. This model is separate from Nano Banana 2 and does not substitute the older model on failure.

| Property | Value |
| - | - |
| Public model ID | `nano-banana-2.1` |
| Resolutions | `1K` (default), `2K`, `4K` |
| Size | `auto` (default) or one of ten supported ratios |
| Count | `n: 1` only |
| References | Up to 16 public URLs or PNG/JPEG/WebP Data URLs |
| Waiting response | `data[].url`, or HTTP `202` with a task if still running |

| Resolution | Price per delivered image |
| - | -: |
| `1K` | \$0.04 (4 FreeModel credits) |
| `2K` | \$0.05 (5 FreeModel credits) |
| `4K` | \$0.06 (6 FreeModel credits) |

**100 FreeModel credits = \$1**. References have no extra charge. Confirm current availability and prices with [`GET /v1/models`](https://docs.freemodel.app/api-reference/list-models) and the [live model page](https://freemodel.app/models/nano-banana-2-1).

**model** `string` *required*

Set to `nano-banana-2.1`.

**prompt** `string` *required*

A non-empty visual brief of at most 100,000 characters. For edits, describe
what to change and what to preserve.

**resolution** `string` (default: 1K)

`1K`, `2K` or `4K`. This selects the billed resolution tier.

**size** `string` (default: auto)

`auto`, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `5:4`, `4:5` or
`21:9`.

**n** `integer` (default: 1)

This route accepts one image per request. Submit separate requests for
variants.

**image\_urls** `string[]`

Optional, up to 16 publicly reachable HTTP(S) URLs or PNG, JPEG and WebP Data
URLs. Private, loopback and credentialed URLs are rejected. Data URL images
must be valid Base64 and at most 20 MiB decoded per image, with at most 50 MiB
decoded in total. The whole JSON request is subject to the gateway
request-size cap (default 10 MiB), so use public URLs for larger references.

This route does not support `quality`, custom pixel sizes, `version`, masks, video inputs or search controls. Official token-priced fallback is disabled; `official_fallback: true` is rejected before a billing reservation.

## Generate an image

```bash theme={null}
curl https://api.freemodel.app/v1/images/generations \
  -H "Authorization: Bearer $FREEMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2.1",
    "prompt": "A ceramic coffee mug on a walnut table, soft window light, product photo",
    "resolution": "1K",
    "size": "1:1",
    "n": 1
  }'
```

A normal request waits for a terminal result (default 180 seconds). Success returns image URLs:

```json theme={null}
{
  "created": 1791460800,
  "data": [{ "url": "https://cdn.example.com/generated-image.png" }]
}
```

## Edit with a reference

```json theme={null}
{
  "model": "nano-banana-2.1",
  "prompt": "Preserve the mug shape and replace the background with warm linen",
  "resolution": "2K",
  "size": "4:3",
  "n": 1,
  "image_urls": ["https://cdn.example.com/reference-mug.png"]
}
```

## Run asynchronously

Send `Prefer: respond-async` to receive HTTP `202` immediately. Use `Idempotency-Key` (1–200 characters) for retries of the same submission. A normal waiting request can also return `202` when the job is still running. Read the gateway task ID and poll [`GET /v1/tasks/{id}`](https://docs.freemodel.app/api-reference/task-status) with the same key until `succeeded` or `failed`.

```bash theme={null}
curl https://api.freemodel.app/v1/images/generations \
  -H "Authorization: Bearer $FREEMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -H "Idempotency-Key: mug-concept-001" \
  -d '{"model":"nano-banana-2.1","prompt":"A blue ceramic mug on linen","resolution":"1K","size":"16:9","n":1}'
```

```bash theme={null}
curl "https://api.freemodel.app/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $FREEMODEL_API_KEY"
```

> [!NOTE]
>
> The gateway reserves the selected resolution price before submitting the
> request and settles the delivered image count against that immutable price
> version. Explicit failure or cancellation releases the reservation. Uncertain
> or invalid results are held for reconciliation. Repeated status polls do not
> charge twice. Result URLs are temporary: download successful files promptly
> and respect any returned expiry time.

> **[Try Nano Banana 2.1](https://freemodel.app/models/nano-banana-2-1)**
>
> Generate from text or references in the model Playground and compare live
> rates.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.