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

# Gemini Nano Banana 2.1 Image Generation

> Generate images with Gemini Nano Banana 2.1 standard and VIP using up to 14 reference images and 1K, 2K, or 4K resolution.

> [!NOTE]
>
> **Note for users in mainland China:** Use `https://toapis.cn` as the Base URL. Replace `https://toapis.com` with `https://toapis.cn` in the examples below.

## Model Selection

| Version | Model ID |
| - | - |
| Standard | `gemini-nano-banana-2.1` |
| VIP | `gemini-nano-banana-2.1-vip` |

Both models use the same endpoint and request parameters. Switch versions using the `model` field. Text-to-image and image-to-image requests run asynchronously. Query results using the task ID returned after submission.

> [!WARNING]
>
> `image_urls` only accepts publicly accessible image URLs, not base64 data. Use the [Upload Image API](https://docs.toapis.com/docs/en/api-reference/uploads/images.md) to upload local images and obtain URLs first.

## Authentication

**Authorization** `string` *required*

All requests require a Bearer Token. Get your API Key from the [API Key Management Page](https://toapis.com/console/token).

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Request Parameters

**model** `string` *required* (default: gemini-nano-banana-2.1)

Model name. Use `gemini-nano-banana-2.1` or `gemini-nano-banana-2.1-vip`.

**prompt** `string` *required*

Text description for image generation or editing.

**size** `string`

Output image aspect ratio. Supported values:

* `1:1`
* `3:2`, `2:3`
* `4:3`, `3:4`
* `16:9`, `9:16`
* `5:4`, `4:5`
* `21:9`
* `1:4`, `4:1`
* `1:8`, `8:1`

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

The output count is fixed at the number `1`. Do not use the string `"1"`.

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

Array of reference image URL strings for image-to-image generation or editing. Maximum 14 images. Each URL must be publicly accessible. The reference image count is not the output image count.

Maximum 10MB per image. Supported formats: .jpeg, .jpg, .png, .webp.

```json theme={null}
["https://example.com/photo.jpg"]
```

**metadata** `object`

Additional configuration options.

**metadata**

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

Output image resolution. Supported values: `1K`, `2K`, `4K`. Default: `1K`. Use an uppercase `K`.

**grounding** `string` (default: none)

Google Search grounding. When enabled, the model searches Google before generating; the result may include cited sources in `grounding_metadata`.
Only the VIP version (`gemini-nano-banana-2.1-vip`) supports grounding.

Options:

* `none` - Disabled (default)
* `web` - Web search
* `image` - Image search
* `web_image` - Web + image search

Billed per executed search query at \$0.014 per query. A deposit of up to 4 queries is reserved when the request is submitted, and unused queries are refunded at settlement.

## Response Fields

**id** `string`

Task ID used to query task status and results.

**object** `string`

Always `generation.task`.

**model** `string`

Model ID used in the request.

**status** `string`

Task status: `queued`, `in_progress`, `completed`, `failed`.

**progress** `integer`

Task progress as a percentage from 0 to 100.

**created\_at** `integer`

Task creation time as a Unix timestamp in seconds.

**metadata** `object`

Task metadata.

```bash cURL theme={null}
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gemini-nano-banana-2.1",
  "prompt": "A cyberpunk city at night with flickering neon lights",
  "size": "16:9",
  "n": 1,
  "metadata": {
    "resolution": "2K"
  }
}'
```

```bash cURL (VIP Image-to-Image) theme={null}
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gemini-nano-banana-2.1-vip",
  "prompt": "Transform this photo into a watercolor painting",
  "size": "1:1",
  "n": 1,
  "image_urls": [
    "https://example.com/photo.jpg"
  ],
  "metadata": {
    "resolution": "2K"
  }
}'
```

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

response = requests.post(
    "https://toapis.com/v1/images/generations",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "model": "gemini-nano-banana-2.1",
        "prompt": "A cyberpunk city at night with flickering neon lights",
        "size": "16:9",
        "n": 1,
        "metadata": {
            "resolution": "2K"
        }
    }
)
response.raise_for_status()
task = response.json()
print(task["id"])
```

```javascript JavaScript theme={null}
const response = await fetch('https://toapis.com/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "model": "gemini-nano-banana-2.1",
    "prompt": "A cyberpunk city at night with flickering neon lights",
    "size": "16:9",
    "n": 1,
    "metadata": {
      "resolution": "2K"
    }
  })
});

if (!response.ok) {
  throw new Error(await response.text());
}
const task = await response.json();
console.log(task.id);
```

```json 200 theme={null}
{
  "id": "task_img_abc123def456",
  "object": "generation.task",
  "model": "gemini-nano-banana-2.1",
  "status": "queued",
  "progress": 0,
  "created_at": 1703884800,
  "metadata": {}
}
```

## Query Results

The `id` in the submission response is the task ID. Use the [Image Task Status API](https://docs.toapis.com/docs/en/api-reference/tasks/image-status.md) to retrieve task status and final images. See [Task Webhooks](https://docs.toapis.com/docs/en/api-reference/webhooks/task-webhooks.md) for asynchronous notifications.


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