快速结论
- 支持 prompt 文生图，覆盖多种宽高比。
- 支持 reference_images 参考图输入，可增强风格一致性。
- 官方版本支持更多生成控制参数，便于生产调优。
关键参数
- model | string | 必填 | gemini-3.1-flash-image-preview-official | - | 生图模型标识，必须使用 ToAPIs 提供值。
- prompt | string | 必填 | - | - | 图片描述文本。
- size | string | 可选 | 1:1 | 1:1 | 16:9 | 9:16 | 4:3 | 3:4 | 21:9 | 输出宽高比。
- resolution | string | 可选 | 1K | 1K | 2K | 4K（按模型能力） | 输出分辨率，取值随模型版本变化。
- reference_images | file[] | 可选 | - | max 14 | 参考图片数组，用于风格与构图约束。
- temperature | number | 可选 | 0.8 | 0-2 | 采样温度，控制生成多样性。
- topP | number | 可选 | 0.95 | 0-1 | 核采样阈值，控制概率截断范围。
常见错误
- 400 invalid_request_error: 触发=请求体字段缺失或类型不合法。; 修复=校验 model/prompt/size/resolution 字段和值。; 重试=修正参数后重试。
- 401 authentication_error: 触发=API Key 缺失或无效。; 修复=检查 Authorization 头与密钥权限。; 重试=修复鉴权后重试。
- 429 rate_limit_exceeded: 触发=请求频率、并发或当前额度命中上游限流策略。; 修复=先做指数退避重试，并检查当前请求节奏、并发设置和额度使用情况。; 重试=建议 1s/2s/4s + 抖动；连续触发时再收紧提交节奏。
