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

# gemini-nano-banana-2.1

> API usage guide for gemini-nano-banana-2.1.

**Model ID**

```bash theme={null}
gemini-nano-banana-2.1
```

**Calling method:** sync

# Gemini Nano Banana 2.1 API Usage Guide

## Overview

**Gemini Nano Banana 2.1** is an update to Nano Banana 2 (Gemini 3.1 Flash Image) and the primary high-efficiency model for image generation and conversational editing. It keeps Flash-level speed and cost while improving visual quality, text rendering and multi-turn character consistency at 1K, 2K and 4K resolutions. It supports text-to-image, image-guided editing, and multi-turn iterative workflows via `contents`.

Reference: [https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/nano-banana-2-1](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/nano-banana-2-1)

## Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

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

## Submit Image Generation Request

### Base URL

```
https://console.gmicloud.ai
```

### Endpoint

```
POST /api/v1/ie/requestqueue/apikey/requests
```

### Request Format

```bash theme={null}
curl -X POST "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "payload": {
      "prompt": "A hyperrealistic portrait of a cyberpunk woman under neon lights",
      "image": [
        "https://example.com/ref1.jpg",
        "https://example.com/ref2.jpg"
      ],
      "image_size": "1K",
      "aspect_ratio": "4:5",
      "thinking": "medium"
    }
  }'
```

### Request Parameters

| Parameter | Type | Required | Description | Default | Constraints |
| - | - | - | - | - | - |
| `prompt` | string | Yes (single-turn) | Text description of the target image. | - | Required when `contents` is not provided |
| `image` | string/array | No | Optional reference image URLs for image-guided generation/editing. | - | Max 14 images (high fidelity for up to 10 objects and up to 4 characters); PNG/JPEG/WebP/HEIC/HEIF; 7MB inline upload, 30MB via GCS |
| `image_size` | string | No | Output resolution preset for generated image. | "1K" | Options: "1K", "2K", "4K" (512 is not supported) |
| `aspect_ratio` | string | No | Aspect ratio of the generated image. | "1:1" | Options: "1:1", "3:2", "2:3", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9", "9:21", "1:4", "4:1", "1:8", "8:1" |
| `thinking` | string | No | How much the model reasons before generating. Higher levels improve complex compositions at the cost of latency. Thinking tokens are billed as text output. | "medium" | Options: "minimal", "medium", "high" |
| `image_output_format` | string | No | Output image format. | "png" | Options: "png", "jpeg" |
| `contents` | array | No | Multi-turn conversation payload for iterative editing. | - | When provided, `prompt` and `image` are ignored |

### Response

```json theme={null}
{
  "request_id": "7eaa77fc-bc67-4021-9f1b-96b3fd832314",
  "model": "gemini-nano-banana-2.1",
  "status": "queued",
  "created_at": 1761763441,
  "updated_at": 1761763441,
  "queued_at": 1761763441
}
```

## Check Request Status

### Endpoint

```
GET /api/v1/ie/requestqueue/apikey/requests/{request_id}
```

### Example

```bash theme={null}
curl -X GET "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests/7eaa77fc-bc67-4021-9f1b-96b3fd832314" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```json theme={null}
{
  "request_id": "7eaa77fc-bc67-4021-9f1b-96b3fd832314",
  "model": "gemini-nano-banana-2.1",
  "status": "success",
  "payload": {
    "prompt": "A hyperrealistic portrait of a cyberpunk woman under neon lights",
    "image": [
      "https://example.com/ref1.jpg",
      "https://example.com/ref2.jpg"
    ],
    "image_size": "1K",
    "aspect_ratio": "4:5",
    "thinking": "medium"
  },
  "outcome": {
    "media_urls": [
      {
        "id": "0",
        "url": "https://storage.googleapis.com/gmi-generated-assets/.../gemini_output_0.png"
      }
    ]
  },
  "created_at": 1761763441,
  "updated_at": 1761763451,
  "queued_at": 1761763441
}
```

## Request Status Values

| Status | Description |
| - | - |
| `queued` | Request is waiting to be processed |
| `processing` | Image generation is in progress |
| `success` | Image generation completed successfully |
| `failed` | Image generation failed |
| `cancelled` | Request was cancelled |

## List Your Requests

### Endpoint

```
GET /api/v1/ie/requestqueue/apikey/requests?model_id=gemini-nano-banana-2.1
```

### Example

```bash theme={null}
curl -X GET "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests?model_id=gemini-nano-banana-2.1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Get Model Information

### Endpoint

```
GET /api/v1/ie/requestqueue/apikey/models/gemini-nano-banana-2.1
```

### Example

```bash theme={null}
curl -X GET "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/models/gemini-nano-banana-2.1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## List Available Models

### Endpoint

```
GET /api/v1/apikey/models
```

### Example

```bash theme={null}
curl -X GET "https://console.gmicloud.ai/api/v1/apikey/models" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Gemini Native Interface (alternative)

In addition to the GMI-shape `/requests` endpoint above, this model accepts
the **Vertex-native `generateContent` shape** — request body matches what
Google's [`generateContent`](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/model-reference/generate-content)
uses. Customers already running on `google-genai` SDK or any HTTP client
that follows Google's REST contract can plug in by changing only the
`base_url` and `Authorization` header.

Notes for this model:

* `temperature`, `topP`, `topK` and `seed` are not supported by Nano Banana 2.1 and are ignored.
* `thinkingConfig` is not forwarded on this interface; the model uses its default thinking level (`medium`). Use the `/requests` endpoint with `thinking` to choose a level.
* `tools` (including Google Search grounding) are not supported on this interface.

### Endpoint

```
POST https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests/v1/models/gemini-nano-banana-2.1:generateContent
```

### Curl example

```bash theme={null}
curl --request POST \
  --url 'https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests/v1/models/gemini-nano-banana-2.1:generateContent' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "A serene mountain lake at dawn, photorealistic, soft mist over the water"}]
      }
    ],
    "generationConfig": {
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "1K",
        "imageOutputOptions": {"mimeType": "image/png"}
      }
    }
  }'
```

### google-genai SDK example

```python theme={null}
from google import genai
from google.genai import types

MODEL = "gemini-nano-banana-2.1"
ENDPOINT = (
    "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests"
    f"/v1/models/{MODEL}:generateContent"
)

client = genai.Client(
    vertexai=True,
    http_options={
        "base_url": ENDPOINT,
        "headers": {"Authorization": "Bearer YOUR_API_KEY"},
    },
)

response = client.models.generate_content(
    model=MODEL,
    contents="A serene mountain lake at dawn, photorealistic, soft mist over the water",
    config=types.GenerateContentConfig(
        image_config=types.ImageConfig(
            aspect_ratio="16:9",
            image_size="1K",
            image_output_options=types.ImageConfigImageOutputOptions(
                mime_type="image/png",
            ),
        ),
    ),
)

# Typed access — SDK auto-decodes inlineData base64 to bytes
print("model_version:", response.model_version)
for c in response.candidates:
    for p in c.content.parts:
        if p.inline_data:
            print(f"got {len(p.inline_data.data)} bytes of {p.inline_data.mime_type}")
```

### Multi-turn

Pass `contents` as user/model/user alternation. The last turn must be
`role: "user"`. Reference images on user turns go in
`parts[].inlineData` (base64) — same field shape as Google's
`generateContent`.

```json theme={null}
{
  "contents": [
    {"role": "user",  "parts": [{"text": "Generate a cyberpunk cityscape"}]},
    {"role": "model", "parts": [{"text": "Here is a neon-lit city at night."}]},
    {"role": "user",  "parts": [{"text": "Make it rainy with a lone figure walking under neon lights"}]}
  ]
}
```

## Multi-turn Conversation (Iterative Image Editing)

This model supports multi-turn conversations for iterative image editing. After generating an image, you can continue refining it by providing additional instructions.

### How It Works

1. **First Turn**: Send a regular request with `prompt` (and optional `image`)
2. **Response**: The response includes `next_turn_contents` with prior conversation context
3. **Next Turn**: Copy `next_turn_contents` into payload `contents`, then append your new user instruction
4. **Repeat**: Continue until the result is satisfactory

## Model Specifications

| Specification | Value |
| - | - |
| Model ID | gemini-nano-banana-2.1 |
| Max input tokens | 131,072 |
| Max output tokens | 32,768 |
| Max input images | 14 (high fidelity for up to 10 objects and up to 4 characters) |
| Max file size (inline upload) | 7 MB |
| Max file size (GCS) | 30 MB |
| Max input size | 500 MB |
| Supported image MIME types | image/png, image/jpeg, image/webp, image/heic, image/heif |
| Supported resolutions | 1K, 2K, 4K |
| Supported aspect ratios | 1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 9:21, 1:4, 4:1, 1:8, 8:1 |
| Thinking levels | minimal, medium, high (default medium) |
| Temperature, topP, topK, seed | Not supported |
| candidateCount | 1 |

## Capabilities

* **Supported**: System instructions, Count Tokens, Thinking, Implicit context caching
* **Not supported**: Code execution, Function calling, Gemini Live API, Structured output, URL context, Vertex AI RAG Engine, Chat completions, Tuning

## Pricing

* **Input (text, image)**: \$1.50 per 1M tokens
* **Text output (response/reasoning)**: \$7.50 per 1M tokens
* **Image output**: \$30 per 1M tokens
  * 1K output image: 1120 tokens (about \$0.0336/image)
  * 2K output image: 1680 tokens (about \$0.0504/image)
  * 4K output image: 3780 tokens (about \$0.113/image)

## Tips for Better Results

1. Use specific and descriptive prompts for stable outputs.
2. For complex edits, use multi-turn mode with `contents` for iterative refinement.
3. Use high-quality reference images and keep composition/style instructions explicit.
4. For text-heavy images (infographics, menus, posters), use `thinking: "high"` and spell out the exact text you want rendered.


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