gemini-3.1-flash-image-preview-official API Model Guide
TL;DR
- Supports prompt-based image generation with multiple aspect ratios.
- Supports reference_images for stronger style consistency.
- Official variants expose richer generation controls for production tuning.
Core Capabilities
- High-quality image generation：Generate high-fidelity images via a unified API.
- Reference-guided consistency：Use reference_images to stabilize style and composition.
- Production tuning controls：Tune resolution, aspect ratio, and sampling for quality/cost balance.
When to Use
- When generating marketing/e-commerce/creative image assets at scale.
- When using references to stabilize style and iterate prompts quickly.
When Not to Use
- For long-form video generation or temporal shot control.
- For complex multi-turn reasoning chat tasks.
Runtime Behavior
- Uses a unified image generation endpoint with task-style responses.
- Supports reference image inputs with count/size constraints.
- Resolution and aspect-ratio support vary by Gemini image variant.
Minimal Request
{
"model": "gemini-3.1-flash-image-preview-official",
"prompt": "High-end e-commerce product poster, soft light, realistic texture, minimal background",
"size": "1:1",
"resolution": "1K"
}
Minimal Response
{
"id": "task_img_xxxxxxxx",
"object": "generation.task",
"model": "gemini-3.1-flash-image-preview-official",
"status": "queued",
"progress": 0,
"created_at": 1703884800,
"metadata": {}
}
Key Parameters
| Parameter | Type | Required | Default | Range | Description |
|---|
| model | string | Yes | gemini-3.1-flash-image-preview-official | - | Exact image model identifier from ToAPIs. |
| prompt | string | Yes | - | - | Primary image instruction prompt. |
| size | string | No | 1:1 | 1:1 | 16:9 |
| resolution | string | No | 1K | 1K | 2K |
| reference_images | file[] | No | - | max 14 | Reference image array for style/composition control. |
| temperature | number | No | 0.8 | 0-2 | Sampling temperature for diversity control. |
| topP | number | No | 0.95 | 0-1 | Nucleus sampling threshold. |
Common Errors
| HTTP | Code | Trigger | Fix Action | Retry Policy |
|---|
| 400 | invalid_request_error | Missing or invalid request payload fields. | Validate model/prompt/size/resolution fields. | Retry only after fixing payload. |
| 401 | authentication_error | Missing or invalid API key. | Verify Authorization header and API key scope. | Retry after auth fix. |
| 429 | rate_limit_exceeded | Request rate, concurrency, or current quota hits upstream rate limiting. | Apply exponential backoff first, then review request rate, concurrency, and quota usage. | Use 1s/2s/4s backoff with jitter; if it persists, reduce submission pressure. |
FAQ
- How should I choose Gemini image variants?
Choose by resolution needs, official vs preview variant, and control parameters; prefer official for production.
- Why are reference images not taking effect?
Check reference count/format/size limits and ensure prompt explicitly uses references.
- Image or video model error: invalid apitype: -1
This usually means the request was sent to the wrong endpoint. Image and video models typically do not use the chat endpoint. Instead, submit the documented HTTP task request and poll the task status endpoint for results. Check the actual request code, URL, and payload first.
- An image or video task failed, but the user was still charged
Ask the user for the task log or screenshot first and check whether input or output token usage appears. If token accounting shows up, the request was likely sent through a chat endpoint instead of the proper media workflow. Image and video models usually run as async HTTP task APIs: submit the task first, then poll by task id according to the relevant docs.
Related APIs
