图片生成

Gemini 原生图片生成使用 contents[].parts[].text 传入提示词，并通过 generationConfig.imageConfig 设置图片比例和分辨率。生成结果以 Base64 形式返回在 candidates[].content.parts[].inlineData 中。

接口地址

POST https://{your-domain}/v1beta/models/{model}:generateContent

可用图片模型可能随上游调整。调用前请通过 GET /v1/models 查询当前 API Key 可用的模型，并选择支持图片输出的 Gemini 模型。支持模型包括：

gemini-2.5-flash-image
gemini-2.5-flash-image-preview
gemini-3.1-flash-image
gemini-3.1-flash-image-preview
gemini-3-pro-image-preview

鉴权

推荐使用 Google 风格 API Key 请求头，

x-goog-api-key: YOUR_API_KEY
Content-Type: application/json

平台也兼容 Bearer 请求头：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

请求结构

字段	类型	必填	说明
`contents`	array	是	对话内容数组。图片生成时通常只需要一条用户消息。
`contents[].role`	string	否	建议设置为 `user`。
`contents[].parts[].text`	string	是	图片生成提示词，可使用中文或英文。
`generationConfig.responseModalities`	array	建议	只需要图片时传 `["IMAGE"]`；需要文字和图片时传 `["TEXT", "IMAGE"]`。
`generationConfig.imageConfig.aspectRatio`	string	否	图片宽高比，例如 `1:1`、`3:2`、`4:3`、`9:16` 或 `16:9`。
`generationConfig.imageConfig.imageSize`	string	否	图片分辨率，例如 `1K`、`2K` 或 `4K`；实际支持范围取决于模型。

常见宽高比包括：

1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9

不同模型支持的比例和分辨率可能不同。若请求返回参数错误，请先确认当前模型能力。预览模型也可能调整或下线，生产环境不要写死未经验证的模型名称。

curl 示例

curl --request POST \
  --url 'https://{your-domain}/v1beta/models/gemini-3.1-flash-image:generateContent' \
  --header 'x-goog-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "生成一座漂浮在日出云海上方的天文研究岛微缩模型，采用高细节等距视角和手工黏土 3D 风格。画面为宽幅 16:9 构图，不要人物、文字、标志或水印。"
          }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "1K"
      }
    }
  }'

请求体

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "生成一座漂浮在日出云海上方的天文研究岛微缩模型，采用高细节等距视角和手工黏土 3D 风格。画面为宽幅 16:9 构图，不要人物、文字、标志或水印。"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["IMAGE"],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "1K"
    }
  }
}

响应示例

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/jpeg",
              "data": "/9j/4AAQSkZJRgABAQEBLAEs..."
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 38,
    "candidatesTokenCount": 1584,
    "totalTokenCount": 1622
  },
  "modelVersion": "gemini-3.1-flash-image"
}

图片数据位于 candidates[0].content.parts[] 中包含 inlineData 的片段。inlineData.mimeType 表示实际图片格式，inlineData.data 是不带 Data URI 前缀的 Base64 字符串。

Python 示例

import base64
from pathlib import Path

import requests

api_key = "YOUR_API_KEY"
model = "gemini-3.1-flash-image"
url = f"https://{{your-domain}}/v1beta/models/{model}:generateContent"

payload = {
    "contents": [
        {
            "role": "user",
            "parts": [
                {"text": "生成一幅雨后城市街道的电影感夜景，16:9 构图，不要文字或水印。"},
            ],
        }
    ],
    "generationConfig": {
        "responseModalities": ["IMAGE"],
        "imageConfig": {
            "aspectRatio": "16:9",
            "imageSize": "1K",
        },
    },
}

resp = requests.post(
    url,
    headers={
        "x-goog-api-key": api_key,
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=300,
)
resp.raise_for_status()

parts = resp.json()["candidates"][0]["content"]["parts"]
image = next(part["inlineData"] for part in parts if "inlineData" in part)
suffix = ".png" if image["mimeType"] == "image/png" else ".jpg"
Path(f"generated-image{suffix}").write_bytes(base64.b64decode(image["data"]))

JavaScript 示例

import { writeFile } from "node:fs/promises";

const apiKey = "YOUR_API_KEY";
const model = "gemini-3.1-flash-image";

const response = await fetch(
  `https://{your-domain}/v1beta/models/${model}:generateContent`,
  {
    method: "POST",
    headers: {
      "x-goog-api-key": apiKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      contents: [
        {
          role: "user",
          parts: [
            { text: "生成一幅雨后城市街道的电影感夜景，16:9 构图，不要文字或水印。" },
          ],
        },
      ],
      generationConfig: {
        responseModalities: ["IMAGE"],
        imageConfig: {
          aspectRatio: "16:9",
          imageSize: "1K",
        },
      },
    }),
  }
);

if (!response.ok) {
  throw new Error(await response.text());
}

const result = await response.json();
const image = result.candidates[0].content.parts.find(
  (part) => part.inlineData
).inlineData;
const extension = image.mimeType === "image/png" ? "png" : "jpg";
await writeFile(`generated-image.${extension}`, Buffer.from(image.data, "base64"));

最佳实践

建议	说明
明确描述构图	在提示词中写明主体、环境、镜头、光线、风格和宽高比。
明确排除项	不需要人物、文字、标志或水印时，在提示词中直接说明。
及时解码图片	Base64 响应体较大，收到后应及时解码保存，不要长期记录完整响应。
提高客户端超时	图片生成耗时通常高于文本请求，建议将超时设置为数分钟。
校验 MIME 类型	保存文件时以 `inlineData.mimeType` 为准，不要假定一定返回 JPEG。

常见问题

场景	表现	处理方式
返回 `model_not_allowed`	当前 API Key 无法使用该模型	调用 `GET /v1/models` 确认模型权限。
返回参数错误	模型不支持请求的比例或分辨率	改用模型支持的 `aspectRatio` 和 `imageSize`。
响应中没有图片	模型未生成图片或响应模态配置不正确	确认模型支持图片输出，并传入 `responseModalities: ["IMAGE"]`。
JSON 响应过大	高分辨率图片以 Base64 内嵌返回	提高客户端响应体限制，避免在日志中打印完整正文。
图片中文字不准确	生成模型对精确排版和文字还原能力有限	减少画面文字，重要文字通过后期排版添加。

开始使用

API 参考

模型与计费

指南

参考

接口地址

鉴权

请求结构

curl 示例

请求体

响应示例

Python 示例

JavaScript 示例

最佳实践

常见问题

​接口地址

​鉴权

​请求结构

​curl 示例

​请求体

​响应示例

​Python 示例

​JavaScript 示例

​最佳实践

​常见问题

接口地址

鉴权

请求结构

curl 示例

请求体

响应示例

Python 示例

JavaScript 示例

最佳实践

常见问题