> ## 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-3-pro-image-preview > API usage guide for gemini-3-pro-image-preview. {/* source_model_id: gemini-3-pro-image-preview */} {/* source_updated_at: 1778228079 */} **Model ID** ```bash theme={null} 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: ```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-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 ```json theme={null} { "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 ```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-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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} curl -X GET "https://api.example.com/api/v1/apikey/models" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Response ```json theme={null} { "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`](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. ### Endpoint ``` POST https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests/v1/models/gemini-3-pro-image-preview:generateContent ``` ### Curl example ```bash theme={null} 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 ```python theme={null} 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`. ```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` - 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-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) ```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-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 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.