Model ID

gemini-3.1-flash-image

Calling method: sync

Gemini 3.1 Flash Image API Usage Guide

Overview

Gemini 3.1 Flash Image is optimized for image understanding and generation, balancing speed and cost. 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/3-1-flash-image

Authentication

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

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

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-3.1-flash-image",
    "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"
    }
  }'

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; PNG/JPEG/WebP/HEIC/HEIF; 7MB inline upload, 30MB via GCS
`image_size`	string	No	Output resolution preset for generated image.	”1K”	Options: “512”, “1K”, “2K”, “4K”
`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”
`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

{
  "request_id": "7eaa77fc-bc67-4021-9f1b-96b3fd832314",
  "model": "gemini-3.1-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

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

{
  "request_id": "7eaa77fc-bc67-4021-9f1b-96b3fd832314",
  "model": "gemini-3.1-flash-image",
  "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"
  },
  "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-3.1-flash-image

Example

curl -X GET "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests?model_id=gemini-3.1-flash-image" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Model Information

Endpoint

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

Example

curl -X GET "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/models/gemini-3.1-flash-image" \
  -H "Authorization: Bearer YOUR_API_KEY"

List Available Models

Endpoint

GET /api/v1/apikey/models

Example

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

Endpoint

POST https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests/v1/models/gemini-3.1-flash-image:generateContent

Curl example

curl --request POST \
  --url 'https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests/v1/models/gemini-3.1-flash-image: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

from google import genai
from google.genai import types

MODEL = "gemini-3.1-flash-image"
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.

{
  "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

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

Model Specifications

Specification	Value
Model ID	gemini-3.1-flash-image
Max input tokens	131,072
Max output tokens	32,768
Max input images	14
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 aspect ratios	1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
Temperature	0.0-2.0 (default 1.0)
topP	0.0-1.0 (default 0.95)
candidateCount	1

Capabilities

Supported: System instructions, Count Tokens, Thinking
Not supported: Code execution, Function calling, Gemini Live API, implicit/explicit context caching, Vertex AI RAG Engine, Chat completions

Pricing

Input (text, image): $0.50 per 1M tokens
Text output (response/reasoning): $3.00 per 1M tokens
Image output: $60 per 1M tokens
- 512 output image: 747 tokens (about $0.045/image)
- 1K output image: 1120 tokens (about $0.067/image)
- 2K output image: 1680 tokens (about $0.101/image)
- 4K output image: 2520 tokens (about $0.15/image)

Tips for Better Results

Use specific and descriptive prompts for stable outputs.
For complex edits, use multi-turn mode with contents for iterative refinement.
Use high-quality reference images and keep composition/style instructions explicit.

​Gemini 3.1 Flash Image API Usage Guide

​Overview

​Authentication

​Submit Image Generation Request

​Base URL

​Endpoint

​Request Format

​Request Parameters

​Response

​Check Request Status

​Endpoint

​Example

​Response

​Request Status Values

​List Your Requests

​Endpoint

​Example

​Get Model Information

​Endpoint

​Example

​List Available Models

​Endpoint

​Example

​Gemini Native Interface (alternative)

​Endpoint

​Curl example

​google-genai SDK example

​Multi-turn

​Multi-turn Conversation (Iterative Image Editing)

​How It Works

​Model Specifications

​Capabilities

​Pricing

​Tips for Better Results

Gemini 3.1 Flash Image API Usage Guide

Overview

Authentication

Submit Image Generation Request

Base URL

Endpoint

Request Format

Request Parameters

Response

Check Request Status

Endpoint

Example

Response

Request Status Values

List Your Requests

Endpoint

Example

Get Model Information

Endpoint

Example

List Available Models

Endpoint

Example

Gemini Native Interface (alternative)

Endpoint

Curl example

google-genai SDK example

Multi-turn

Multi-turn Conversation (Iterative Image Editing)

How It Works

Model Specifications

Capabilities

Pricing

Tips for Better Results