gemini-3.1-flash-image-preview-official API Руководство по модели
Краткий вывод
- 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.
Ключевые возможности
- 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 generating marketing/e-commerce/creative image assets at scale.
- When using references to stabilize style and iterate prompts quickly.
Когда не использовать
- For long-form video generation or temporal shot control.
- For complex multi-turn reasoning chat tasks.
Особенности работы
- 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.
Минимальный запрос
{
"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"
}
Минимальный ответ
{
"id": "task_img_xxxxxxxx",
"object": "generation.task",
"model": "gemini-3.1-flash-image-preview-official",
"status": "queued",
"progress": 0,
"created_at": 1703884800,
"metadata": {}
}
Ключевые параметры
| Параметр | Тип | Обяз. | По умолчанию | Диапазон | Описание |
|---|
| model | string | Да | gemini-3.1-flash-image-preview-official | - | Exact image model identifier from ToAPIs. |
| prompt | string | Да | - | - | Primary image instruction prompt. |
| size | string | Нет | 1:1 | 1:1 | 16:9 |
| resolution | string | Нет | 1K | 1K | 2K |
| reference_images | file[] | Нет | - | max 14 | Reference image array for style/composition control. |
| temperature | number | Нет | 0.8 | 0-2 | Sampling temperature for diversity control. |
| topP | number | Нет | 0.95 | 0-1 | Nucleus sampling threshold. |
Частые ошибки
| HTTP | Code | Триггер | Исправление | Повтор |
|---|
| 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.
- Ошибка у модели изображений или видео: invalid apitype: -1
Обычно это означает, что запрос отправлен не в тот endpoint. Модели изображений и видео обычно не используют chat endpoint. Вместо этого нужно отправлять HTTP-запрос на создание задачи по документации и затем опрашивать endpoint статуса задачи. Сначала проверьте фактический код запроса, URL и payload.
- Задача на генерацию изображения или видео завершилась ошибкой, но списание произошло
Сначала попросите у пользователя лог задачи или скриншот и проверьте, есть ли там статистика входных или выходных токенов. Если учет токенов есть, запрос, скорее всего, был отправлен через chat endpoint, а не через правильный media workflow. Модели изображений и видео обычно работают как асинхронные HTTP task API: сначала отправляется задача, затем выполняется опрос по task id согласно документации.
Связанные API
