多模态（原生协议）

API 参考/Multimodal/Gemini 多模态

生成内容

POST/v1beta/models/{model}:{method}

通过 Google 原生协议调用 Gemini 文本、图片理解、图片生成和 PDF 文件理解能力。

认证

通过 Bearer Token 认证。

Authorizationstring必填

API Key，格式为 Bearer YOUR_API_KEY。

默认值：-

Content-Typestring必填

请求体格式。

默认值：application/json

Request-Idstring可选

客户侧生成的唯一请求标识，用于追踪和排查。

默认值：-

路径参数

路径中的 {method} 决定普通响应或流式响应。

modelstring必填

Gemini 模型名称，例如 gemini-2.5-flash、gemini-2.5-flash-image。

默认值：-

methodstring必填

调用方法：generateContent 或 streamGenerateContent。

默认值：-

请求

请求体使用 Google Gemini 原生 contents[].parts 结构。

contentsarray必填

对话内容列表。

默认值：-

contents[].rolestring必填

角色：user 或 model。

默认值：-

contents[].partsarray必填

内容块列表，可包含 text、inlineData 或 fileData。

默认值：-

contents[].parts[].textstring可选

文本内容。

默认值：-

contents[].parts[].inlineDataobject可选

Base64 内联文件，常用于图片或 PDF。

默认值：-

contents[].parts[].fileDataobject可选

文件 URI 输入，适合已托管文件。

默认值：-

generationConfigobject可选

生成配置。

默认值：-

generationConfig.temperaturenumber可选

采样温度。

默认值：-

generationConfig.maxOutputTokensinteger可选

最大输出 Token 数。

默认值：-

generationConfig.responseModalitiesarray可选

响应模态，例如 TEXT、IMAGE 或二者组合。

默认值：-

响应

响应返回候选内容和用量信息。图片生成时，图片通常出现在 candidates[].content.parts[].inlineData。

candidatesarray必填

候选响应列表。

默认值：-

candidates[].contentobject可选

模型返回内容。

默认值：-

candidates[].content.partsarray可选

返回内容块，可能包含 text 或 inlineData。

默认值：-

candidates[].finishReasonstring可选

停止原因，例如 STOP、MAX_TOKENS 或 SAFETY。

默认值：-

usageMetadataobject可选

Token 用量统计。

默认值：-

常用端点

端点	用途
/v1beta/models/gemini-2.5-flash:generateContent	Gemini 文本生成或图像理解
/v1beta/models/gemini-2.5-flash:streamGenerateContent	Gemini 流式文本生成
/v1beta/models/gemini-2.5-flash-image:generateContent	Gemini 图片生成
/v1beta/models/gemini-3.1-flash-image-preview:generateContent	Gemini 3.1 图片生成预览

错误

状态码	说明
400	请求体字段错误、文件格式不支持或模型与方法不匹配
401	API Key 缺失或无效
403	当前账户无权调用该模型
429	请求超过速率限制
500 / 503	平台或上游模型服务异常

相关指南

• 多模态概览
• 图像理解
• 图像生成
• PDF 文件

请求示例POST

curl __DOCS_API_ORIGIN__/v1beta/models/gemini-2.5-flash:generateContent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {"text": "介绍一下量子计算"}
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 2048
    }
  }'

成功响应200

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "量子计算是一种利用量子力学原理进行信息处理的计算方式..."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 8,
    "candidatesTokenCount": 128,
    "totalTokenCount": 136
  }
}