Model ID

gemini-3-pro-image-preview

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"
    ]
}

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

Tips for Better Results

Prompt Clarity: Use detailed, specific prompts for precise 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

​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

​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

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

Tips for Better Results