Model ID

gemini-3-pro-image-preview

Calling method: sync

Gemini 3 Pro Image Preview API Usage Guide

Overview

Gemini 3 Pro Image Preview creates high-quality images from descriptive prompts and can blend in multiple reference images supplied as URLs. You can control aspect ratio, output resolution (1K/2K/4K) and the number of images per request. This model is hosted on Google AI Studio and requires a Google API key.

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-pro-image-preview",
    "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": "2K",
      "aspect_ratio": "4:5"
    }
  }'

Request Parameters

Parameter	Type	Required	Description	Default	Constraints
`prompt`	string	Yes	Text description of the desired image (max 2000 characters).	-	Required
`image`	string/array	No	Optional reference image URLs (up to 14). Supported: PNG, JPEG, WebP, HEIC, HEIF. Max 7MB inline.	-	Optional
`image_size`	string	No	Target resolution for generated images.	”1K”	Options: “1K”, “2K”, “4K”
`aspect_ratio`	string	No	Aspect ratio of the generated image.	”1:1”	Options: “1:1”, “4:5”, “5:4”, “3:4”, “4:3”, “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.	-	See multi-turn section

Response

{
  "request_id": "7eaa77fc-bc67-4021-9f1b-96b3fd832314",
  "model": "gemini-3-pro-image-preview",
  "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-pro-image-preview",
  "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": "2K",
    "aspect_ratio": "4:5"
  },
  "outcome": {
    "media_urls": [
      {
        "id": "0",
        "url": "https://storage.googleapis.com/gmi-generated-assets/.../gemini_output_0.jpg"
      },
    ]
  },
  "created_at": 1761763441,
  "updated_at": 1761763451,
  "queued_at": 1761763441
}

Request Status Values

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

List Your Requests

Endpoint

GET api/v1/ie/requestqueue/apikey/requests?model_id=gemini-3-pro-image-preview

Example

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

Get Model Information

Endpoint

GET /api/v1/ie/requestqueue/apikey/models/gemini-3-pro-image-preview

Example

curl -X GET "https://api.example.com/api/v1/apikey/models/gemini-3-pro-image-preview" \
  -H "Authorization: Bearer YOUR_API_KEY"

List Available Models

Endpoint

GET /api/v1/apikey/models

Example

curl -X GET "https://api.example.com/api/v1/apikey/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
    "model_ids": [
        "gemini-3-pro-image-preview",
        "other-model-1",
        "other-model-2"
    ]
}

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-pro-image-preview:generateContent

Curl example

curl --request POST \
  --url 'https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests/v1/models/gemini-3-pro-image-preview:generateContent' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "A hyperrealistic portrait of a snow leopard on a moonlit cliff, cinematic"}]
      }
    ],
    "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-pro-image-preview"
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 hyperrealistic portrait of a snow leopard on a moonlit cliff, cinematic",
    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 - a pre-formatted conversation history
Next Turn: Copy next_turn_contents to your payload’s contents field, then add your new instruction to the last user turn
Repeat: Continue iterating until satisfied

First Turn Request

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

First Turn Response (with next_turn_contents)

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

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-pro-image-preview",
    "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"}]
        }
      ],
      "image_size": "1K",
      "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

Pricing

Pricing Type: Per-image request
Price: $0.134 per image
Unit: Image

Tips for Better Results

Prompt Clarity: Use detailed, specific prompts for precise results.
Multi-turn Iteration: For complex edits, use multi-turn mode to refine the image step by step.

​Gemini 3 Pro Image Preview 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

​Response

​Gemini Native Interface (alternative)

​Endpoint

​Curl example

​google-genai SDK example

​Multi-turn

​Multi-turn Conversation (Iterative Image Editing)

​How It Works

​First Turn Request

​First Turn Response (with next_turn_contents)

​Second Turn Request (Using next_turn_contents)

​Multi-turn Tips

​Pricing

​Tips for Better Results

Gemini 3 Pro Image Preview 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

Response

Gemini Native Interface (alternative)

Endpoint

Curl example

google-genai SDK example

Multi-turn

Multi-turn Conversation (Iterative Image Editing)

How It Works

First Turn Request

First Turn Response (with next_turn_contents)

Second Turn Request (Using next_turn_contents)

Multi-turn Tips

Pricing

Tips for Better Results