跳转到主要内容

​
Gemini 内容生成 (Gemini Native Format)

该接口用于调用 Gemini 原生多模态模型（如 Nano Banana 系列），支持文本生成、图像生成以及“思维链”过程的返回。

​
📌 基础信息

  • 接口地址: POST /v1beta/models/{model}:generateContent/
  • 请求参数 (Path):
    • model: 模型名称，例如 gemini-3-pro-image-preview。
  • 认证方式: Bearer Token
  • 内容类型: application/json

​
📥 请求参数 (Request Body)

参数名类型必选描述
contentsarray是对话内容列表。
└─ rolestring否角色（如 user）。
└─ partsarray是包含消息组成部分的列表。
└─ └─ textstring是提示词或文本输入。
generationConfigobject是生成配置对象。
└─ responseModalitiesarray是响应模态，可选值：TEXT, IMAGE。
└─ thinkingConfigobject否思考配置。
└─ └─ includeThoughtsboolean否是否返回模型生成时的思考逻辑（思维链）。
└─ imageConfigobject是图像生成配置。
└─ └─ aspectRatiostring是纵横比，如 16:9, 1:1, 4:3。
└─ └─ imageSizestring是图像质量/尺寸，如 4K, 1024x1024。

​
📤 响应结果 (Response)

状态码: 200 OK
字段名类型描述
candidatesarray生成的备选内容列表。
└─ contentobject包含生成的角色和具体 parts（可能包含文本或图像数据）。
└─ finishReasonstring停止生成的原因（如 STOP）。
└─ safetyRatingsarray安全性评估评分。
usageMetadataobjectToken 消耗元数据（Prompt, Candidates, Total）。

​
📝 请求示例 (生成图像)

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "draw a futuristic city at sunset"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "4K"
    },
    "thinkingConfig": {
      "includeThoughts": true
    }
  }
}

​
💡 开发者建议

  1. 思维链返回: 通过设置 includeThoughts: true，你可以看到模型在绘图前是如何理解你的需求并进行“构思”的，这对于调试复杂提示词非常有用。
  2. 多模态响应: 在 responseModalities 中同时包含 TEXT 和 IMAGE 时，模型会先给出描述性文字，再生成对应的图像。
  3. 模型版本: 请确保路径中的 {model} 参数与您当前使用的 API 权限相匹配。