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

Gemini 文生图

用于 Gemini 原生文生图。请求体使用 generateContent 协议，contents.parts 只放文本 prompt，generationConfig.responseModalities 建议传 ["TEXT", "IMAGE"]；返回图片在 candidates[].content.parts[].inlineData 中，不是平台 /v1/images/generations 的 data[].url 格式。

基础信息

鉴权	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": "生成一张 1:1 的产品海报，画面包含云端模型网关控制台、清晰的卡片式数据面板和蓝白科技风背景。"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "TEXT",
      "IMAGE"
    ],
    "temperature": 0.8
  }
}

响应示例

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": 32,
    "candidatesTokenCount": 1290,
    "totalTokenCount": 1322,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 32
      }
    ],
    "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 · 浏览器直连网关