先确认模型和协议
新项目推荐 gemini-3.1-flash-image、gemini-3-pro-image；轻量生成可选原生 gemini-3.1-flash-lite-image。旧教程中的实验型号和 -preview 不作为新项目默认模型。
| 旧型号 | Google Gemini API 生命周期与迁移 |
|---|---|
gemini-3-pro-image-preview | 2026-06-25 已停用；改为 gemini-3-pro-image。 |
gemini-3.1-flash-image-preview | 2026-06-25 已停用；改为 gemini-3.1-flash-image。 |
gemini-2.5-flash-image-preview | 2026-01-15 已停用；新接入直接使用 3.1 Flash Image。 |
gemini-2.5-flash-image | 官方停用日期为 2026-10-02；本次核对日期已到，迁移到 3.1 Flash Image 并重新确认尺寸与提示效果。 |
gemini-2.0-flash-preview-image-generation 及旧实验生图名 | 不用于新接入；使用当前稳定版和本目录请求结构。 |
以上是厂商生命周期，不代表本站所有自定义别名的自动映射承诺。即使旧名称仍可在模型列表中看到，也应使用明确的稳定 ID；账号是否有权调用以本站控制台为准。旧页面 URL 已保留，原生生图和误放在 Claude 下的 Chat 生图内容统一归入本目录。
第一步：检查鉴权
使用请求头 Authorization: Bearer YOUR_API_KEY。将 YOUR_API_KEY 替换为青云TOP API 的 API Key，保留 Bearer 后的空格；基础地址为 https://top.qingyuntop.ai。
401 时确认 Key 正确且仍有效；403 时确认模型权限、分组与可用额度。不要把 Google Key、文档站地址或 YOUR_API_KEY 占位符原样当作真实凭据。
第二步：检查请求位置
原生：POST /v1beta/models/{model}:generateContent，模型放路径，文字图片放 contents[].parts[]，尺寸放 generationConfig.imageConfig。
Chat：POST /v1/chat/completions，模型放 JSON 顶层，输入放 messages，尺寸放 extra_body.google.image_config。原生驼峰字段与 Chat 扩展的下划线字段不能混用。
| 现象 | 检查与处理 |
|---|---|
| HTTP 400、INVALID_ARGUMENT | 检查字段层级、字符串类型、比例及模型尺寸组合；Pro 不填 512，Lite 不填 2K/4K，2.5 不填 imageSize。确认请求 JSON 完整且没有注释。 |
| HTTP 404、模型不存在 | 检查稳定模型 ID 与路径后缀；不要把预览停用型号、普通对话模型或别名当作当前官方生图型号。 |
| HTTP 413、请求过大 | 完整 JSON 控制在 20 MB 以下；压缩图片、减少参考图或开启新的独立编辑。Base64 和全部多轮历史都计入体积。 |
| HTTP 429 | 检查额度和速率限制；按 Retry-After（若返回）或指数退避加随机抖动，限制重试次数与并发。先区分配额不足和短期限流。 |
| HTTP 5xx、超时或断线 | 保留模型、请求时间、响应标识及脱敏错误联系本站支持；未确认上次结果前避免盲目重复生成。断线不代表取消。 |
| HTTP 200 但没有图片 | 检查 promptFeedback.blockReason、候选 finishReason 与文字说明；遍历所有非思考 parts，确认请求 IMAGE 输出。 |
| SAFETY、IMAGE_SAFETY、PROHIBITED_CONTENT 等 | 查看拒绝信息，调整请求内容或输入图片；不要循环重试同样请求。 |
| MAX_TOKENS、NO_IMAGE、IMAGE_OTHER | 检查是否输出受限、没有图片或生成未正常完成；简化复杂请求，保留正文供排查，不把残缺 Base64 作为完整文件。 |
| 尺寸参数没效果 | 使用本目录 imageConfig 字段；不要只写提示词“4K”，不要套用 responseFormat.image、顶层 size/quality 或模型后缀。 |
| Base64 解码失败 | 检查是否复制截断、加入省略号或前缀；原生 inlineData.data 不带 data URI 前缀，Chat 图片需要先从 Markdown 中提取。 |
| 多轮签名错误 | 回传完整 model content 和原位置的 thoughtSignature，使用同一模型；不拼接多个候选，不从 Chat Markdown 伪造历史。 |
响应追踪与重试边界
本目录的同步/流式接口没有任务轮询或恢复下载流程；不要把 responseId 拼成 /tasks/{id}，也不要用它填 previous_interaction_id。已收到完整图片时先保存产物；未收到终态时保留事件和时间供排查，不自行断言已取消、免费或自动退款。
需要给本站支持提供信息时，包含模型 ID、接口路径、请求时间、HTTP 状态、响应中的追踪 ID（若有）、脱敏参数及错误。不要提供完整 API Key 或在公开交流中粘贴私有图片的 Base64。
可用示例与参考
按文生图的最小请求排除基础接入问题，再加入高清参数、图片素材或多轮历史。结果结构见图片保存。官方参考：停用时间表、Gemini API 问题排查。