POST/v1beta/models/{modeName}:generateContent

Gemini Image 接入概览与模型选择

使用 Gemini Image 生成图片、修改已有图片或通过多轮对话迭代设计。先选择 Pro Image、Flash Image 或 Flash Lite Image，再选择原生或 Chat 兼容调用方式。

API Key application/json

功能与适用场景

Gemini Image 接受文字与图片，返回图片及可能的文字说明，适合海报、商品图、插画、文字排版与多图参考创作。生成结果直接随 HTTP 响应返回，不需要创建视频式异步任务。图片生成模型的 ID 必须包含 image；普通 Gemini 对话型号不能替代生图型号。

支持模型与选择

官方模型 ID	适用场景与输出范围
`gemini-3.1-flash-image`	Flash Image / Nano Banana 2。日常生图、海报、多图一致性与快速迭代。默认推荐。 imageSize：512 / 1K / 2K / 4K。 14 种比例；最多 14 张参考。
`gemini-3-pro-image`	Pro Image / Nano Banana Pro。复杂构图、精细文字、品牌素材和专业设计。思考默认开启，不能设置思考等级。 imageSize：1K / 2K / 4K。 10 种比例；最多 14 张参考。
`gemini-3.1-flash-lite-image`	Flash Lite Image / Nano Banana 2 Lite。轻量生图、简单改色与背景调整。建议少量参考；复杂多图与连续编辑优先选 Flash 或 Pro。 imageSize：1K。本目录推荐 10 种常用比例。
`gemini-2.5-flash-image`	旧版 Flash Image / Nano Banana。旧项目迁移参考；建议最多 3 张输入。不设置 imageSize。官方停用日期为 2026-10-02，本次核对日期已到，应迁移至 3.1 Flash Image。输出约 1K，具体像素随比例变化。

本站当前可见型号（2026-10-02）

下面是青云TOP API 公共目录快照，不等同于厂商官方型号清单。带 -c、-preview、-t 或尺寸后缀的名称按本站模型 ID 使用；是否可调用仍以你的 API Key 的 GET /v1/models 结果为准。

模型 ID	可见协议	分组
`gemini-2.5-flash-image`	gemini、openai	Verterx渠道Gemini、Gemini官转、Gemini特价
`gemini-2.5-flash-image-preview`	gemini、openai	Gemini官转
`gemini-3-pro-image`	gemini、openai	Verterx渠道Gemini、Gemini官转
`gemini-3-pro-image-c`	gemini、openai	按次计费
`gemini-3-pro-image-preview`	gemini、openai	Verterx渠道Gemini、Gemini官转
`gemini-3-pro-image-preview-2k`	gemini、openai	Gemini官转
`gemini-3-pro-image-preview-4k`	gemini、openai	Gemini官转
`gemini-3-pro-image-preview-c`	gemini、openai	按次计费
`gemini-3-pro-image-preview-t`	gemini、openai	Verterx渠道Gemini
`gemini-3.1-flash-image`	gemini、openai	Verterx渠道Gemini、Gemini官转、Gemini-CLI、Gemini特价
`gemini-3.1-flash-image-c`	gemini、openai	按次计费
`gemini-3.1-flash-image-preview`	gemini、openai	Verterx渠道Gemini、Gemini官转
`gemini-3.1-flash-image-preview-2k`	gemini、openai	Gemini官转
`gemini-3.1-flash-image-preview-4k`	gemini、openai	Gemini官转
`gemini-3.1-flash-image-preview-c`	gemini、openai	按次计费
`gemini-3.1-flash-lite-image`	gemini、openai	Verterx渠道Gemini、Gemini官转、Gemini特价

新项目优先使用稳定版。gemini-3-pro-image-preview 与 gemini-3.1-flash-image-preview 已于 2026-06-25 在 Google Gemini API 停用；gemini-2.5-flash-image 的官方停用日期为 2026-10-02，本次核对日期已到，不再作为新项目默认型号。迁移时改用上表稳定版。控制台中的模型可见性仍取决于账号分组、权限和当前可用性；带 -c、-t、-2k、-4k 等后缀的名称不能直接当作官方型号或参数约定。详见模型迁移。

调用方式	适用需求与结果
Gemini 原生格式，推荐	`POST /v1beta/models/{model}:generateContent`；精确配置输出比例、尺寸、参考图、搜索工具；返回 `candidates[].content.parts[]`。多轮编辑可保留思考签名。
Gemini 原生流式	`POST /v1beta/models/{model}:streamGenerateContent?alt=sse`；读取 SSE 中的文字与图片块，详见流式消费。
Chat 兼容格式	`POST /v1/chat/completions`；适用于已有 Chat 调用链的 Pro Image / Flash Image 单轮生图与编辑；返回内容中的 Markdown 图片 data URI。见兼容调用。Flash Lite 推荐原生格式。

第一步：设置鉴权

使用请求头 Authorization: Bearer YOUR_API_KEY。将 YOUR_API_KEY 替换为青云TOP API 的 API Key，保留 Bearer 后的空格；基础地址为 https://top.qingyuntop.ai。

第二步：调用模型

从文生图示例开始；编辑图片使用本地图片与多图参考。两者使用同一原生接口，只是 contents[].parts[] 的输入不同。输出尺寸放在 generationConfig.imageConfig，具体限制见参数表和高清输出。

官方当前指南还提供 Interactions API，并在部分 generateContent 示例中采用 responseFormat.image。本站本目录使用 generationConfig.imageConfig，不要直接把 input、previous_interaction_id、response_format 或 steps 等 Interactions 字段移入本页请求。

返回结果与后续操作

原生结果中的 inlineData.data 是 Base64 图片字节；根据同一对象的 mimeType 保存文件，不能把 Base64 文本当图片链接。遍历所有非思考内容块，不固定读取第一个 part。详见返回结果与图片保存。

连续修改同一作品使用多轮编辑，完整保留模型响应及 thoughtSignature。需要基于搜索资料生成图片时，查看搜索辅助生图。

能力边界与参考

本目录不提供 /v1/images/generations、/v1/images/edits、Interactions、Files 上传或 Batch 批任务教程；不要将这些接口的请求结构用于上述两个生图入口。需要大量图片时，在应用侧控制并发；提示词要求的图片数量不保证等于实际输出数量。所有生成图片包含 SynthID 水印。

费用以青云TOP API 控制台当前价格及用量记录为准；模型思考、输入图片和输出分辨率可能影响用量。官方参考：图片生成指南、Pro Image、Flash Image、Flash Lite Image。

Request

请求

/v1beta/models/{modeName}:generateContent

Body

必填

Bodyobject

contentsarray<object>必填

元素object

partsarray<object>必填

元素object

textstring必填

提示词

inline_dataobject

图片内嵌数据

mime_typestring必填

图片MIME类型

datastring必填

图片 base64 追多支持传入 14 张图片

generationConfigobject

生成配置

responseModalitiesarray<string>

响应模式： Text、Image 默认：["Text", "Image"]

元素string

imageConfigobject

图片配置

aspectRatiostring

宽高比： 1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9 支持所有模型 1:4、1:8、4:1、8:1 这几个仅支持Gemini 3.1模型

imageSizestring

分辨率： 0.5K、1K、2K、4K 默认值：1K 注意：Gemini 2.5只支持1K，0.5K仅支持Gemini 3.1模型，值须填“512”

路径、查询与 Header 参数

参数	位置	类型	必填	说明	示例
`modeName`	Path	string	是	模型名称： gemini-2.5-flash-image gemini-2.5-flash-image-preview gemini-3-pro-image-preview gemini-3.1-flash-image-preview	gemini-2.5-flash-image-preview
`key`	Query	string	是	-	YOUR_API_KEY
`Content-Type`	Header	string	是	-	application/json

请求示例application/json

curl -X POST https://top.qingyuntop.ai/v1beta/models/{modeName}:generateContent \
  -H "Authorization: Bearer ${QINGYUN_TOP_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Hi, can you create a 3d rendered image of a pig with wings and a top hat flying over a happy futuristic scifi city with lots of greenery?"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "IMAGE"
    ]
  }
}'

Response

返回响应 `200`

HTTP 响应

响应 200object