试用 Lyria 3，这是我们的全新音乐生成模型，能够根据文本和图片输入生成高保真立体声音频。

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 密钥：

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
          ]
      }
    ]
  }'

响应正文结构

对于流式模式和标准模式，响应正文类似，但存在以下例外情况：

标准模式：响应正文包含 GenerateContentResponse 的实例。
流式模式：响应正文包含 GenerateContentResponse 实例的数据流。

在较高级别，响应正文包含一个 candidates 对象，该对象是 Candidate 对象的列表。Candidate 对象包含一个 Content 对象，该对象具有从模型返回的生成的响应。

请求示例

以下示例展示了这些组件如何组合在一起以用于不同类型的请求。

纯文本提示

简单的文本提示包含一个 contents 数组，其中包含单个 Content 对象。相应对象的 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

其余端点支持与目前介绍的主要端点搭配使用的其他功能。如需了解详情，请查看“指南”部分中的主题批处理模式和 File API。

后续步骤

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

您可能还需要查看功能指南，这些指南介绍了不同的 Gemini API 功能并提供了代码示例：