> ## 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.1-flash-image-preview > API usage guide for gemini-3.1-flash-image-preview. {/* source_model_id: gemini-3.1-flash-image-preview */} {/* source_updated_at: 1778228368 */} **Model ID** ```bash theme={null} gemini-3.1-flash-image-preview ``` **Calling method:** sync # Gemini 3.1 Flash Image Preview API Usage Guide ## Overview **Gemini 3.1 Flash Image Preview** 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](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: ```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.1-flash-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": "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 ```json theme={null} { "request_id": "7eaa77fc-bc67-4021-9f1b-96b3fd832314", "model": "gemini-3.1-flash-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.1-flash-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": "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-preview ``` ### Example ```bash theme={null} curl -X GET "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests?model_id=gemini-3.1-flash-image-preview" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Get Model Information ### Endpoint ``` GET /api/v1/ie/requestqueue/apikey/models/gemini-3.1-flash-image-preview ``` ### Example ```bash theme={null} curl -X GET "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/models/gemini-3.1-flash-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://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`](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.1-flash-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.1-flash-image-preview: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 ```python theme={null} from google import genai from google.genai import types MODEL = "gemini-3.1-flash-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 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`. ```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` with prior conversation context 3. **Next Turn**: Copy `next_turn_contents` into payload `contents`, then append your new user instruction 4. **Repeat**: Continue until the result is satisfactory ## Model Specifications | Specification | Value | | ----------------------------- | --------------------------------------------------------- | | Model ID | gemini-3.1-flash-image-preview | | 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 1. Use specific and descriptive prompts for stable outputs. 2. For complex edits, use multi-turn mode with `contents` for iterative refinement. 3. Use high-quality reference images and keep composition/style instructions explicit.