POST/v1beta/models/gemini-3-pro-image-preview:generateContent

Gemini Image 宽高比与高清输出

使用 Pro Image 或 Flash Image 控制输出宽高比和分辨率。示例生成 16:9 的 4K 宣传图，解释 512、1K、2K、4K 与具体像素的关系。

API Key application/json

功能与支持组合

aspectRatio 决定构图比例，imageSize 选择分辨率档位，两者配合使用。4K 不代表任意比例下都是 4096×4096，也不是上传图片的大小。

官方模型 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特价

Pro 与 Flash 的正方形 1:1 在 1K、2K、4K 档位分别为 1024×1024、2048×2048、4096×4096；16:9 分别为 1376×768、2752×1536、5504×3072。实际文件仍应以返回图片的像素为准。

3.1 Flash Image 还支持 imageSize="512"，适合小图；Pro 不支持此档位。Lite 使用 1K，不要照搬本页的 4K 示例。完整比例列表见参数与模型限制。

第一步：设置鉴权

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

第二步：调用模型

POST https://top.qingyuntop.ai/v1beta/models/gemini-3-pro-image:generateContent

Content-Type 为 application/json。同样的 16:9 + 4K 参数也可用于稳定版 gemini-3.1-flash-image，只需替换 URL 中模型 ID。

Request

请求

/v1beta/models/gemini-3-pro-image-preview:generateContent

Body

必填

Bodyobject

contentsarray<object>必填

元素object

partsarray<object>

元素object

textstring

inline_dataobject

mime_typestring必填

datastring必填

generationConfigobject必填

responseModalitiesarray<string>必填

元素string

imageConfigobject必填

aspectRatiostring必填

路径、查询与 Header 参数

参数	位置	类型	必填	说明	示例
`key`	Query	string	是	-	YOUR_API_KEY
`Content-Type`	Header	string	是	-	application/json

请求示例application/json

set -euo pipefail
cat > request-template.json <<'JSON'
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "生成一张横版产品宣传图：白色陶瓷咖啡杯放在浅色木桌上，柔和自然光，右侧留出排版空间，标题准确写着“慢享每一天”，细节清晰。"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "TEXT",
      "IMAGE"
    ],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "4K"
    }
  }
}
JSON
cp request-template.json request.json
[ "$(wc -c < request.json)" -lt 20000000 ] || { echo "请求超过 20 MB，请压缩图片或缩短历史" >&2; exit 1; }
curl --fail-with-body --connect-timeout 30 --max-time 600 "https://top.qingyuntop.ai/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  --output response.json

Response

返回响应 `200`

HTTP 响应

响应 200object

返回结果与保存

Python/Node.js 自动保存图片与完整响应；cURL 保存 JSON，按结果保存解码。高分辨率 Base64 数据较大，应避免把完整图片字符串输出到业务日志或按文字截断后再解码。

图片编辑也使用同一个 generationConfig.imageConfig 对象，参阅多图参考。4K 可能增加等待时间和输出用量，不代表固定价格或处理时间。

常见错误与参考

尺寸报错时检查模型组合、大小写和字段层级；尺寸未按预期生效时确认请求中使用 imageConfig，不是 responseFormat 或顶层 size。官方参考：宽高比和分辨率、ImageConfig。