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

# Nano banana 2.1 Image Generation

> Text-to-image and reference image editing with 1K / 2K / 4K output and 10 aspect ratios, available in official and Ext versions.

## 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](https://apimart.ai/pricing) for current prices.

<Info>
  This is an asynchronous endpoint. A successful submission returns a `task_id`. Use [task queries](/en/api-reference/tasks/status) to retrieve status and images. Poll every 3–5 seconds and allow at least 3 minutes for the overall wait timeout.
</Info>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/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
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.apimart.ai/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())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.apimart.ai/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());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01K..."
      }
    ]
  }
  ```
</ResponseExample>

## Request headers

<ParamField header="Authorization" type="string" required>
  Bearer authentication in the format `Bearer <token>`, where `<token>` is your APIMart API Key.
</ParamField>

## Request parameters

<ParamField body="model" type="string" required>
  Model ID: `gemini-nano-banana-2.1` or `gemini-nano-banana-2.1-ext`.
</ParamField>

<ParamField body="prompt" type="string" required>
  A text description for image generation or editing. Chinese and English are supported.
</ParamField>

<ParamField body="size" type="string" default="auto">
  Output aspect ratio. Supports `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.

  Other ratios, including `1:4`, `4:1`, `1:8`, and `8:1`, are not supported. Unsupported ratios cause task failure and a refund.
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  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.
</ParamField>

<ParamField body="n" type="integer" default="1">
  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.
</ParamField>

<ParamField body="image_urls" type="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.
</ParamField>

<ParamField body="official_fallback" type="boolean" default="false">
  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.**
</ParamField>

<ParamField body="webhook" type="string">
  Callback URL notified when the task ends. See [task webhooks](/en/api-reference/tasks/webhook).
</ParamField>

## 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

```json theme={null}
{
  "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)

```json theme={null}
{
  "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

<ResponseField name="code" type="integer">
  Response status code. `200` indicates success.
</ResponseField>

<ResponseField name="data" type="array">
  Task submission result. `status` is `submitted`. Use `task_id` to query task status and results; it is not the final image URL.
</ResponseField>

## Query task results

```bash theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01K... \
  --header 'Authorization: Bearer <token>'
```

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

```json theme={null}
{
  "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](https://apimart.ai/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 | Use one of the 10 supported `size` ratios or `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 `0.5K` resolution and the four extreme ratios: `1:4`, `4:1`, `1:8`, and `8:1`.
</Warning>


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