Gemini 图片生成接口教程

本文介绍如何通过 Gemini 原生接口进行文生图（Text-to-Image）。
如需图片编辑（改图），请参阅图片编辑教程。

一、接口信息

项目	说明
请求方式	`POST`
端点	`{base_url}/v1beta/models/{model}:generateContent`
认证	`Authorization: Bearer sk-xxxxxxxx`
Content-Type	`application/json`

二、可用模型

在请求 URL 中替换 {model} 为以下模型名称：

模型	特点
`gemini-3-pro-image-preview`	质量最高，支持 1K / 2K / 4K 分辨率
`gemini-3.1-flash-image-preview`	速度快，支持 512 / 1K，比例最多（含 1:4、4:1、1:8、8:1）
`gemini-3.1-flash-lite-image`	速度更快，成本更低，仅支持 1K，比例最多（含 1:4、4:1、1:8、8:1）
`gemini-2.5-flash-image-preview`	Flash 系列
`gemini-2.5-flash-image`	Flash 系列

模型所在的分组请前往模型广场查看！

三、最小可用示例

只需 contents + generationConfig 即可生成图片：

responseModalities 必须包含 "IMAGE"，否则模型只返回文本不出图。

四、完整参数示例

五、参数详解

5.1 contents（必填）

对话内容，文生图场景下只需一条 user 消息：

"contents": [
  {
    "role": "user",
    "parts": [
      { "text": "你的提示词" }
    ]
  }
]

字段	类型	说明
`role`	string	固定为 `"user"`
`parts[].text`	string	图片生成提示词

5.2 generationConfig（必填）

参数	类型	必填	默认	说明
`responseModalities`	string[]	是	—	必须包含 `"IMAGE"`。推荐 `["TEXT", "IMAGE"]`
`imageConfig`	object	否	—	图像尺寸与比例配置
`temperature`	number	否	1.0	0~2，越高越随机
`candidateCount`	int	否	1	生成候选数量
`maxOutputTokens`	int	否	—	输出 token 上限
`stopSequences`	string[]	否	—	停止序列，最多 5 个

5.3 imageConfig（图像配置）

"imageConfig": {
  "aspectRatio": "16:9",
  "imageSize": "2K"
}

aspectRatio 可选值

比例	所有模型	仅 Flash 2（3.1）
`1:1`	✓	✓
`2:3` / `3:2`	✓	✓
`3:4` / `4:3`	✓	✓
`4:5` / `5:4`	✓	✓
`9:16` / `16:9`	✓	✓
`21:9`	✓	✓
`1:4` / `4:1`	✗	✓
`1:8` / `8:1`	✗	✓

imageSize 可选值

值	支持模型	说明
`512`	仅 `gemini-3.1-flash-image-preview`	低分辨率，速度最快
`1K`	全部模型	默认值
`2K`	仅 `gemini-3-pro-image-preview`	高清
`4K`	仅 `gemini-3-pro-image-preview`	超高清

注意： 大小写敏感，必须大写 K（写 2k 会被忽略）。Flash 模型传 2K/4K 会静默回退到 1K。

5.4 safetySettings（可选）

"safetySettings": [
  { "category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_ONLY_HIGH" },
  { "category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_ONLY_HIGH" },
  { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "threshold": "BLOCK_ONLY_HIGH" },
  { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "BLOCK_ONLY_HIGH" },
  { "category": "HARM_CATEGORY_CIVIC_INTEGRITY", "threshold": "BLOCK_ONLY_HIGH" }
]

threshold 值	含义
`BLOCK_NONE`	完全不拦截
`BLOCK_ONLY_HIGH`	仅拦截高风险
`BLOCK_MEDIUM_AND_ABOVE`	中等及以上拦截（默认）
`BLOCK_LOW_AND_ABOVE`	低及以上全部拦截

六、响应结构

成功响应示例：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          { "text": "这是一幅未来城市..." },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "<base64 编码的图片数据>"
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 15,
    "candidatesTokenCount": 1290,
    "totalTokenCount": 1305
  }
}

字段	说明
`parts[].inlineData.data`	生成图片的 base64 数据，需解码后保存为图片文件
`parts[].inlineData.mimeType`	图片格式，通常为 `image/png`
`parts[].text`	模型可能附带的文字说明
`finishReason`	`STOP` = 正常完成

异常 finishReason

值	含义
`STOP`	正常完成
`MAX_TOKENS`	超出 token 限制
`SAFETY`	文本安全拦截
`IMAGE_SAFETY`	图片安全拦截
`PROHIBITED_CONTENT`	禁止内容
`OTHER`	其他拦截

七、输出像素对照表

Google 按「等面积」原则映射像素，不是按最长边。

1K

比例	输出像素
`1:1`	1024 x 1024
`4:3`	1184 x 864
`3:4`	864 x 1184
`3:2`	1248 x 832
`2:3`	832 x 1248
`16:9`	1344 x 768
`9:16`	768 x 1344
`5:4`	1152 x 896
`4:5`	896 x 1152
`21:9`	1536 x 672

2K（仅 Pro）

比例	输出像素
`1:1`	2048 x 2048
`4:3`	2304 x 1728
`3:4`	1728 x 2304
`3:2`	2496 x 1664
`2:3`	1664 x 2496
`16:9`	2752 x 1536
`9:16`	1536 x 2752
`5:4`	2304 x 1792
`4:5`	1792 x 2304
`21:9`	3072 x 1344

4K（仅 Pro）

比例	输出像素
`1:1`	4096 x 4096
`4:3`	4608 x 3456
`3:4`	3456 x 4608
`3:2`	4992 x 3328
`2:3`	3328 x 4992
`16:9`	5376 x 3024
`9:16`	3024 x 5376
`5:4`	4608 x 3584
`4:5`	3584 x 4608
`21:9`	6144 x 2688

八、内容安全须知

请避免生成以下类型内容：

未成年人相关内容，包括儿童安全、性化、暴力化、校服/儿童与成人化语境组合

色情、暗示性成人内容、内衣/泳装/贴身服装、性感姿势或容易被判定为 NSFW 的人像

暴力、血腥、火灾、灾难、武器、战争、恐怖主义或危险违法行为

仇恨、骚扰、霸凌、威胁、辱骂、歧视或有毒攻击性内容

名人、政治人物、公众人物、真实人物肖像、换脸、换衣、身体编辑或隐私敏感人像

版权 IP、动漫/游戏/影视角色、品牌吉祥物、Logo、水印移除或仿冒受保护角色

金融、订单、票据、价格标签、支付截图、证件、个人信息等截图篡改

Google 可能返回 IMAGE_SAFETY、PROHIBITED_CONTENT、OTHER 等拦截结果；这些拦截通常无法通过安全参数完全关闭。

九、常见问题

现象	原因	解决
请求成功但没有图片返回	`responseModalities` 未包含 `"IMAGE"`	改为 `["TEXT", "IMAGE"]`
`imageSize: "4K"` 实际只出 1K	使用了 Flash 模型	改用 `gemini-3-pro-image-preview`
传了 `2k` 小写没效果	大小写敏感	改为 `2K`
返回 `IMAGE_SAFETY`	Google 图片安全策略触发	修改 prompt 内容，无法通过参数关闭
返回 `PROHIBITED_CONTENT`	提示词包含禁止内容	调整描述，避免敏感词
429 Too Many Requests	超出速率限制	降低并发频率
比例参数没生效	模型不支持该比例	检查模型支持的比例列表

十、保存图片示例（Shell）

响应中的图片为 base64 编码，需解码保存：

十一、官方文档

Gemini 图像生成文档

请求参数

Path 参数

Header 参数

Body 参数application/json必填

示例

{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "a futuristic city skyline at sunset, ultra realistic" }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      },
      "temperature": 1.0,
      "candidateCount": 1
    },
    "safetySettings": [
      { "category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_NONE" },
      { "category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE" },
      { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "threshold": "BLOCK_NONE"
  },
      { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "BLOCK_NONE"
  },
      { "category": "HARM_CATEGORY_CIVIC_INTEGRITY", "threshold": "BLOCK_NONE" }
    ]
  }

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

图片生成

Gemini 图片生成接口教程#

一、接口信息#

二、可用模型#

三、最小可用示例#

四、完整参数示例#

五、参数详解#

5.1 contents（必填）#

5.2 generationConfig（必填）#

5.3 imageConfig（图像配置）#

aspectRatio 可选值#

imageSize 可选值#

5.4 safetySettings（可选）#

六、响应结构#

异常 finishReason#

七、输出像素对照表#

1K#

2K（仅 Pro）#

4K（仅 Pro）#

八、内容安全须知#

九、常见问题#

十、保存图片示例（Shell）#

十一、官方文档#