Gemini API reference

此 API 参考文档介绍了可用于与 Gemini 模型交互的标准 API、流式 API 和实时 API。您可以在任何支持 HTTP 请求的环境中使用 REST API。如需了解如何开始发出第一个 API 调用，请参阅快速入门指南。如果您要查找特定语言的库和 SDK 的参考信息，请在左侧导航栏中的 SDK 参考下找到相应语言的链接。

主要端点

Gemini API 围绕以下主要端点组织而成：

  • 标准内容生成 (generateContent)：一种标准 REST 端点，用于处理您的请求，并在单个软件包中返回模型的完整回答。此方法最适合非互动任务，您可以等待整个结果。
  • 流式内容生成 (streamGenerateContent)：使用服务器发送的事件 (SSE) 在生成回答时将回答块推送给您。这可为聊天机器人等应用提供更快、更具互动性的体验。
  • Live API (BidiGenerateContent)：一种基于 WebSocket 的有状态 API，用于双向流式传输，专为实时对话使用情形而设计。
  • 批处理模式 (batchGenerateContent)：用于提交批量 generateContent 请求的标准 REST 端点。
  • 嵌入 (embedContent)：一种标准 REST 端点，可根据输入 Content 生成文本嵌入向量。
  • Gen Media API：用于通过我们的专用模型（例如用于生成图片的 Imagen 和用于生成视频的 Veo）生成媒体的端点。 Gemini 还内置了这些功能，您可以使用 generateContent API 访问这些功能。
  • 平台 API：支持核心功能的实用程序端点，例如上传文件和统计令牌数量。

身份验证

对 Gemini API 的所有请求都必须包含带有 API 密钥的 x-goog-api-key 标头。您可以在 Google AI Studio 中点击几下即可创建 API 密钥。

以下示例请求在标头中包含 API 密钥：

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

如需了解如何使用 Gemini SDK 将密钥传递给 API，请参阅使用 Gemini API 密钥指南。

内容生成

这是向模型发送提示的中心端点。有两个用于生成内容的端点，主要区别在于您接收响应的方式：

  • generateContent (REST)：接收请求，并在模型完成整个生成过程后提供单个响应。
  • streamGenerateContent (SSE)：接收完全相同的请求，但模型会以流式传输方式返回生成的回答块。这可让您立即显示部分结果，从而为互动式应用提供更好的用户体验。

请求正文结构

请求正文是一个 JSON 对象，在标准模式和流式模式下完全相同，由几个核心对象构建而成：

  • Content 对象：表示对话中的单个回合。
  • Part 对象：Content 回合中的一段数据（例如文本或图片）。
  • inline_data (Blob)：用于存储原始媒体字节及其 MIME 类型的容器。

在最高层级，请求正文包含一个 contents 对象，该对象是一个 Content 对象列表，每个对象都表示对话中的一个轮次。在大多数情况下，对于基本文本生成，您将使用单个 Content 对象，但如果您想保留对话历史记录，可以使用多个 Content 对象。

以下示例展示了一个典型的 generateContent 请求正文：

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
          "role": "user",
          "parts": [
              // A list of Part objects goes here
          ]
      },
      {
          "role": "model",
          "parts": [
              // A list of Part objects goes here
          ]
      }
    ]
  }'

响应正文结构

无论是流式模式还是标准模式，响应正文都类似，但以下方面除外：

从总体上讲，响应正文包含一个 candidates 对象，该对象是一个 Candidate 对象列表。Candidate 对象包含一个 Content 对象，该对象具有从模型返回的生成的回答。

请求示例

以下示例展示了这些组件如何针对不同类型的请求协同工作。

纯文本提示

简单的文本提示由包含单个 Content 对象的 contents 数组组成。相应对象的 parts 数组又包含一个带有 text 字段的 Part 对象。

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a single paragraph."
          }
        ]
      }
    ]
  }'

多模态提示（文本和图片）

如需在提示中同时提供文字和图片，parts 数组应包含两个 Part 对象：一个用于文字，另一个用于图片 inline_data。

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "contents": [{
    "parts":[
        {
            "inline_data": {
            "mime_type":"image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ... (base64-encoded image)"
            }
        },
        {"text": "What is in this picture?"},
      ]
    }]
  }'

多轮对话（聊天）

如需构建多回合对话，您可以使用多个 Content 对象定义 contents 数组。API 会将整个历史记录用作下一个回答的上下文。每个 Content 对象的 role 应在 user 和 model 之间交替。

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Hello." }
        ]
      },
      {
        "role": "model",
        "parts": [
          { "text": "Hello! How can I help you today?" }
        ]
      },
      {
        "role": "user",
        "parts": [
          { "text": "Please write a four-line poem about the ocean." }
        ]
      }
    ]
  }'

要点总结

  • Content 是信封：它是消息轮次的顶级容器，无论消息是来自用户还是模型。
  • Part 实现多模态：在单个 Content 对象中使用多个 Part 对象来组合不同类型的数据（文本、图片、视频 URI 等）。
  • 选择数据方法：
    • 对于直接嵌入的小型媒体（如大多数图片），请使用带有 inline_data 的 Part。
    • 对于较大文件或您想在多个请求中重复使用的文件，请使用 File API 上传文件，并通过 file_data 部分引用该文件。
  • 管理对话历史记录：对于使用 REST API 的聊天应用，请通过为每个对话轮次附加 Content 对象来构建 contents 数组，并在 "user" 和 "model" 角色之间交替。如果您使用的是 SDK，请参阅 SDK 文档，了解管理对话记录的推荐方式。

响应示例

以下示例展示了这些组件如何针对不同类型的请求协同工作。

纯文本回答

简单的文本回答包含一个 candidates 数组，其中包含一个或多个 content 对象，这些对象包含模型的回答。

以下是标准回答的示例：

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "At its core, Artificial Intelligence works by learning from vast amounts of data ..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 1
    }
  ],
}

以下是一系列流式响应。每个响应都包含一个 responseId，用于将整个响应关联起来：

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "The image displays"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  },
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

...

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " the following materials:\n\n*   **Wood:** The accordion and the violin are primarily"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  }
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

Live API (BidiGenerateContent) WebSockets API

Live API 提供基于有状态 WebSocket 的 API，用于双向流式传输，以实现实时流式传输用例。您可以查看 Live API 指南和 Live API 参考文档，了解更多详情。

专业模型

除了 Gemini 模型系列之外，Gemini API 还提供 Imagen、Lyria 和嵌入模型等专用模型的端点。您可以在“模型”部分下查看这些指南。

平台 API

其余端点可实现其他功能，以便与目前所述的主要端点搭配使用。如需了解详情，请查看“指南”部分中的批量模式和文件 API 主题。

后续步骤

如果您刚刚开始使用 Gemini API，请查看以下指南，这些指南将有助于您了解 Gemini API 编程模型：

您可能还想查看功能指南，其中介绍了不同的 Gemini API 功能并提供了代码示例：