POST/v1/gemini/models/{model}:generateContent

Gemini 图生图

用于 Gemini 原生图生图/图片编辑。请求体使用 generateContent 协议，contents.parts 中同时放文本 prompt 和图片；图片可用 inlineData 传 Base64，也可用 fileData 传可访问的图片 URI。返回图片仍在 candidates[].content.parts[].inlineData 中。

基础信息

鉴权	Authorization: Bearer sk-... / x-goog-api-key: sk-... / ?key=sk-...
请求类型	application/json
响应类型	application/json

请求参数

Path

字段

类型

必填

位置

说明

model

string

是

path

Gemini 图片模型 ID。

示例："gemini-3.1-flash-image-preview"

Body

字段

类型

必填

位置

说明

contents

array

是

body

Gemini 原生消息数组。文生图只需要文本 prompt；图生图需要文本 prompt 加图片 part。

role

string

否

body

消息角色，通常为 user。

示例："user"

parts

array

否

body

消息内容。文生图放 text；图生图同时放 text 和 inlineData/fileData。

generationConfig.responseModalities

array

否

body

返回模态。图片生成场景建议传 ["TEXT", "IMAGE"]。

示例：["TEXT","IMAGE"]

generationConfig.temperature

number

否

body

采样温度。

示例：0.8

请求示例

json

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "基于这张图片生成一版电商主图，保留主体轮廓，替换为更干净的浅色背景并增强产品质感。"
        },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAIAAABMXPacAAABXUlEQVR42u3dwQnCQBBA0VRhAbZhLzaRDuzNdjyJ4MkcBJG4kihmZiQv/Armkcu6E7vT+abEOiMAAEAAAAgAAAEAIAAABACAAAAQAAACAEAAAAgAAJUB8DQfAAAAAAAAAAAAAAAAAAAA4G+e7XEPIHTccwKQM/evJQD8fvQfMVQB2B0ukcVMf44BgGWnP2kAYNnRTzIACJr+OwMAAGoABEy/aQAgdPqvBgCipz8yAAAgFSBl+s8GAAAAWC1A4vQfBgAAAAAAAAAAAMEA6dO/5w3wBgAAAAAAAAAAnIY6DQUAAIDfhAEAcC/IzTg349wNBQDAfoANGRsydsRsSa5gS9KeMACb8r4VAcDXUgAAAAAAAAAAAACMn2u/qRwAAAAAAAAAAAAAAAAAAAAAwFmQsyAAAAAAqAAgf2cLQAAACAAAAQAgAAAEAIAAABAAAAIAQAAACAAAAQAgAADUagAbMOXIAHaxNAAAAABJRU5ErkJggg=="
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "TEXT",
      "IMAGE"
    ],
    "temperature": 0.7
  }
}

响应示例

json

{
  "modelVersion": "gemini-3.1-flash-image-preview",
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "已根据原图生成新版图片。"
          },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgo..."
            }
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 48,
    "candidatesTokenCount": 1290,
    "totalTokenCount": 1338,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 24
      },
      {
        "modality": "IMAGE",
        "tokenCount": 24
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "IMAGE",
        "tokenCount": 1290
      }
    ]
  }
}

响应字段

字段

类型

必填

位置

说明

candidates[].content.parts[].text

string

否

body

模型返回的文字说明。

candidates[].content.parts[].inlineData.mimeType

string

否

body

生成图片的 MIME 类型。

示例："image/png"

candidates[].content.parts[].inlineData.data

string

否

body

生成图片的 Base64 数据。

usageMetadata

object

否

body

Gemini 原生用量信息，平台会按返回的文本/图片用量进入计费。

错误码

HTTP	code	说明
400	`invalid_request_error`	请求体结构不合法、缺少必填参数，或 JSON 无法解析。
401	`invalid_auth_header`	缺少或传错鉴权头，网关无法识别当前调用身份。
403	`model_not_allowed`	当前 API Key 没有访问该模型的权限。
402	`insufficient_balance`	余额不足，平台在调用前预检时已拒绝请求。
503	`model_not_available`	当前模型没有可用路由或上游渠道不可用。

在线调试

Playground · 浏览器直连网关