> ## 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-2.5-flash-image

> API usage guide for gemini-2.5-flash-image.

{/* source_model_id: gemini-2.5-flash-image */}

{/* source_updated_at: 1782166691 */}

**Model ID**

```bash theme={null}
gemini-2.5-flash-image
```

**Calling method:** sync

# Gemini 2.5 Flash Image API Usage Guide

## Overview

**Gemini 2.5 Flash Image** is optimized for image understanding and generation, offering a balance of price and performance. It uses the speed and cost-effectiveness of Gemini 2.5 Flash to provide fast and efficient image generation and editing capabilities. Supports text-to-image, image editing, and multi-turn conversations. Each generated image consumes 1290 tokens.

Reference: [https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/2-5-flash-image](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/2-5-flash-image)

## 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-2.5-flash-image",
    "payload": {
      "prompt": "A hyperrealistic portrait of a cyberpunk woman under neon lights",
      "image": [
        "https://example.com/ref1.jpg"
      ],
      "aspect_ratio": "4:5"
    }
  }'
```

### Request Parameters

| Parameter      | Type         | Required | Description                                                                                                               | Default | Constraints                                                                      |
| -------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------- |
| `prompt`       | string       | Yes      | Text description of the desired image.                                                                                    | -       | Required                                                                         |
| `image`        | string/array | No       | Optional reference image URLs (up to 3). Supported formats: PNG, JPEG, WebP, HEIC, HEIF. Max 7MB inline or 30MB from GCS. | -       | Max 3 images                                                                     |
| `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" |

### Response

```json theme={null}
{
  "request_id": "7eaa77fc-bc67-4021-9f1b-96b3fd832314",
  "model": "gemini-2.5-flash-image",
  "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-2.5-flash-image",
  "status": "success",
  "payload": {
    "prompt": "A hyperrealistic portrait of a cyberpunk woman under neon lights",
    "image": [
      "https://example.com/ref1.jpg"
    ],
    "aspect_ratio": "4:5"
  },
  "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-2.5-flash-image
```

### Example

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

## Get Model Information

### Endpoint

```
GET /api/v1/ie/requestqueue/apikey/models/gemini-2.5-flash-image
```

### Example

```bash theme={null}
curl -X GET "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/models/gemini-2.5-flash-image" \
  -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"
```

### Response

```json theme={null}
{
    "model_ids": [
        "gemini-2.5-flash-image",
        "gemini-3-pro-image-preview",
        "other-model-1"
    ]
}
```

## 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` - a pre-formatted conversation history
3. **Next Turn**: Copy `next_turn_contents` to your payload's `contents` field, then add your new instruction to the last user turn
4. **Repeat**: Continue iterating until satisfied

### First Turn Request

```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-2.5-flash-image",
    "payload": {
      "prompt": "A panda making latte art in a cozy cafe",
      "aspect_ratio": "1:1"
    }
  }'
```

### First Turn Response (with next\_turn\_contents)

```json theme={null}
{
  "request_id": "abc123",
  "status": "success",
  "outcome": {
    "media_urls": [{"id": "0", "url": "https://storage.googleapis.com/.../generated.png"}],
    "next_turn_contents": [
      {
        "role": "user",
        "parts": [{"text": "A panda making latte art in a cozy cafe"}]
      },
      {
        "role": "model",
        "parts": [
          {"text": "Here is the generated image."},
          {"fileData": {"mimeType": "image/png", "fileUri": "gs://bucket/generated.png"}}
        ]
      },
      {
        "role": "user",
        "parts": [{"text": ""}, {"fileData": {"mimeType": "image/png", "fileUri": ""}}]
      }
    ]
  }
}
```

### Second Turn Request (Using next\_turn\_contents)

Copy `next_turn_contents` to `contents`, then fill in the last user turn with your new instruction:

```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-2.5-flash-image",
    "payload": {
      "contents": [
        {
          "role": "user",
          "parts": [{"text": "A panda making latte art in a cozy cafe"}]
        },
        {
          "role": "model",
          "parts": [
            {"text": "Here is the generated image."},
            {"fileData": {"mimeType": "image/png", "fileUri": "gs://bucket/generated.png"}}
          ]
        },
        {
          "role": "user",
          "parts": [{"text": "Change the panda to a brown bear and make the cup blue"}]
        }
      ],
      "aspect_ratio": "1:1"
    }
  }'
```

### Multi-turn Tips

* **Text-only edits**: Just fill in the `text` field in the last user turn
* **Add reference image**: Include a `fileData` with `fileUri` pointing to a GCS or HTTP URL
* **Empty fields are ignored**: Empty `text` or `fileUri` are automatically filtered out
* **Conversation history**: Each response includes updated `next_turn_contents` for the next iteration

## Model Specifications

| Specification                | Value                       |
| ---------------------------- | --------------------------- |
| Model ID                     | gemini-2.5-flash-image      |
| Max input tokens             | 32,768                      |
| Max output tokens            | 32,768                      |
| Max input images             | 3                           |
| Max output images per prompt | 10                          |
| Tokens per output image      | 1,290                       |
| Supported image types        | PNG, JPEG, WebP, HEIC, HEIF |
| Max file size (inline)       | 7 MB                        |
| Max file size (GCS)          | 30 MB                       |
| Temperature                  | 0.0–2.0 (default 1.0)       |
| topP                         | 0.0–1.0 (default 0.95)      |
| topK                         | 64 (fixed)                  |

## Pricing

* **Input (text, image, video)**: \$0.30 per 1M tokens
* **Image output**: $30 per 1M tokens (1290 tokens per image ≈ **$0.0387 per image\*\*)
* **Text output**: \$2.50 per 1M tokens

## Tips for Better Results

1. **Prompt Clarity**: Use detailed, specific prompts for precise results.
2. **Multi-turn Iteration**: For complex edits, use multi-turn mode to refine the image step by step.
3. **Reference Images**: Provide up to 3 reference images to guide style and composition.