gemini-3.1-flash-image-preview-official API 模型解析指南
快速结论
- 支持 prompt 文生图，覆盖多种宽高比。
- 支持 reference_images 参考图输入，可增强风格一致性。
- 官方版本支持更多生成控制参数，便于生产调优。
核心能力
- 高质量文生图：在统一接口中完成高质量图像生成与风格探索。
- 参考图控制：通过 reference_images 约束构图、风格与主题一致性。
- 生产参数可调：结合分辨率、比例与采样参数优化效果和成本。
适用场景
- 需要批量生成营销/电商/创意视觉素材。
- 需要用参考图稳定风格并快速迭代提示词。
不适用场景
- 需要长视频生成或时间序列镜头控制时。
- 需要复杂多轮推理对话时。
运行特性
- 统一调用图片生成接口，结果通常以异步任务状态返回。
- 支持参考图输入，需注意文件数量与大小限制。
- 不同 Gemini 生图版本在分辨率/比例支持上存在差异。
最小请求示例
{
"model": "gemini-3.1-flash-image-preview-official",
"prompt": "高级时尚电商产品海报，柔和灯光，真实质感，极简背景",
"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 | - | 生图模型标识，必须使用 ToAPIs 提供值。 |
| prompt | string | 是 | - | - | 图片描述文本。 |
| size | string | 否 | 1:1 | 1:1 | 16:9 |
| resolution | string | 否 | 1K | 1K | 2K |
| reference_images | file[] | 否 | - | max 14 | 参考图片数组，用于风格与构图约束。 |
| temperature | number | 否 | 0.8 | 0-2 | 采样温度，控制生成多样性。 |
| topP | number | 否 | 0.95 | 0-1 | 核采样阈值，控制概率截断范围。 |
常见错误
| HTTP | Code | 触发条件 | 修复建议 | 重试策略 |
|---|
| 400 | invalid_request_error | 请求体字段缺失或类型不合法。 | 校验 model/prompt/size/resolution 字段和值。 | 修正参数后重试。 |
| 401 | authentication_error | API Key 缺失或无效。 | 检查 Authorization 头与密钥权限。 | 修复鉴权后重试。 |
| 429 | rate_limit_exceeded | 请求频率、并发或当前额度命中上游限流策略。 | 先做指数退避重试，并检查当前请求节奏、并发设置和额度使用情况。 | 建议 1s/2s/4s + 抖动；连续触发时再收紧提交节奏。 |
FAQ
- Gemini 生图模型如何选择？
优先按分辨率、官方/预览版本和可控参数需求选择；生产场景建议优先 official。
- 为什么参考图不生效？
请检查参考图数量、格式和大小限制，并确认 prompt 中明确了参考意图。
- 图像视频模型报错：invalid apitype: -1
这类错误通常说明接口走错了。图像和视频模型一般不走 chat 接口，而是按对应文档发起 HTTP 任务请求，并通过任务状态接口轮询结果。排查时建议先看用户的实际请求代码、请求地址和请求体。
- 用户进行生成图片/视频的任务时出现任务失败，但是扣款
先让用户提供任务日志或截图，重点看是否出现了输入或输出 token 统计。如果有这类 token 记录，大概率是用户把图片/视频模型走成了 chat 接口；这不是正确用法。图片和视频模型通常是异步任务接口，需要通过 HTTP 请求先提交任务，再拿到任务 ID 轮询状态，详细以对应文档为准。
相关 API
