实时 API 参考文档

Live API 支持与 Gemini 建立低延迟的双向语音和视频互动。借助 Live API，您可以为最终用户提供自然的、类似人类的语音对话体验，并能够使用语音指令中断模型的回答。Live API 可以处理文本、音频和视频输入，并提供文本和音频输出。

如需详细了解 Live API，请参阅 Live API。

功能

Live API 包含以下主要功能：

• 多模态：模型可以看、听和说。
• 低延迟实时互动：模型可以快速提供回答。
• 会话记忆：模型会记住单个会话中的所有互动，并回忆之前听到或看到的信息。
• 支持函数调用、代码执行和“将搜索作为工具”：您可以将模型与外部服务和数据源集成。

Live API 专为服务器到服务器的通信而设计。

对于网站和移动应用，我们建议您使用 Daily 提供的集成。

支持的模型

• 支持 Live API 原生音频的 Gemini 2.5 Flash
  preview预览版
• 支持 Live API 的 Gemini 2.0 Flash
  preview预览版
• Gemini 2.5 Flash

开始使用

如需试用实时 API，请前往 Vertex AI Studio，然后点击开始会话。

Live API 是一种使用 WebSockets 的有状态 API。

本部分展示了一个示例，说明如何使用 Live API 进行文本到文本生成（使用 Python 3.9 及更高版本）。

pip install --upgrade google-genai

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import (Content, HttpOptions, LiveConnectConfig,
                                Modality, Part)

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
model_id = "gemini-2.0-flash-live-preview-04-09"

async with client.aio.live.connect(
    model=model_id,
    config=LiveConnectConfig(response_modalities=[Modality.TEXT]),
) as session:
    text_input = "Hello? Gemini, are you there?"
    print("> ", text_input, "\n")
    await session.send_client_content(
        turns=Content(role="user", parts=[Part(text=text_input)])
    )

    response = []

    async for message in session.receive():
        if message.text:
            response.append(message.text)

    print("".join(response))
# Example output:
# >  Hello? Gemini, are you there?
# Yes, I'm here. What would you like to talk about?

集成指南

本部分介绍了集成如何与 Live API 搭配使用。

会话

WebSocket 连接会在客户端与 Gemini 服务器之间建立会话。

客户端发起新连接后，会话可以与服务器交换消息，以执行以下操作：

• 向 Gemini 服务器发送文本、音频或视频。
• 接收来自 Gemini 服务器的音频、文本或函数调用请求。

会话配置在连接后的第一条消息中发送。会话配置包括模型、生成参数、系统指令和工具。

请参阅以下示例配置：

{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object
  },

  "systemInstruction": string,
  "tools": [object]
}

如需了解详情，请参阅 BidiGenerateContentSetup。

发送消息

消息是通过 WebSocket 连接交换的 JSON 格式的对象。

如需发送消息，客户端必须通过打开的 WebSocket 连接发送 JSON 对象。JSON 对象必须包含以下对象集中的一个字段：

{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

支持的客户端消息

请参阅下表中的支持的客户端消息：

接收消息

如需接收来自 Gemini 的消息，请监听 WebSocket“message”事件，然后根据支持的服务器消息的定义解析结果。

请参阅以下内容：

ws.addEventListener("message", async (evt) => {
  if (evt.data instanceof Blob) {
    // Process the received data (audio, video, etc.)
  } else {
    // Process JSON response
  }
});

服务器消息将包含以下对象集中的一个字段：

{
  "setupComplete": BidiGenerateContentSetupComplete,
  "serverContent": BidiGenerateContentServerContent,
  "toolCall": BidiGenerateContentToolCall,
  "toolCallCancellation": BidiGenerateContentToolCallCancellation
  "usageMetadata": UsageMetadata
  "goAway": GoAway
  "sessionResumptionUpdate": SessionResumptionUpdate
  "inputTranscription": BidiGenerateContentTranscription
  "outputTranscription": BidiGenerateContentTranscription
}

支持的服务器消息

下表列出了支持的服务器消息：

增量内容更新

使用增量更新来发送文本输入、建立会话上下文或恢复会话上下文。对于简短的上下文，您可以发送逐轮互动来表示确切的事件序列。对于较长的上下文，建议提供单个消息摘要，以便为后续互动腾出上下文窗口。

请参阅以下示例上下文消息：

{
  "clientContent": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

请注意，虽然内容部分可以是 functionResponse 类型，但不应使用 BidiGenerateContentClientContent 来提供对模型发出的函数调用的回答。应改用 BidiGenerateContentToolResponse。BidiGenerateContentClientContent 仅应用于建立之前的对话背景信息或向对话提供文本输入。

流式音频和视频

代码执行

如需详细了解代码执行，请参阅代码执行。

函数调用

所有函数都必须在会话开始时声明，方法是将工具定义作为 BidiGenerateContentSetup 消息的一部分发送。

您可以使用 JSON（具体来说是 OpenAPI 架构格式的选定子集）来定义函数。单个函数声明可以包含以下参数：

• name（字符串）：API 调用中函数的唯一标识符。

• description（字符串）：对函数用途和功能的全面说明。

• parameters（对象）：定义函数所需的输入数据。

  • type（字符串）：指定总体数据类型，例如对象。

  • properties（对象）：列出各个参数，每个参数都具有以下属性：

    • type（字符串）：参数的数据类型，例如字符串、整数、布尔值。
    • 说明（字符串）：清楚地说明参数的用途和预期格式。

  • required（数组）：一个字符串数组，列出了函数运行所必需的参数名称。

如需查看使用 curl 命令进行函数声明的代码示例，请参阅使用 Gemini API 进行函数调用。 如需查看有关如何使用 Gemini API SDK 创建函数声明的示例，请参阅函数调用教程。

根据单个提示，模型可以生成多个函数调用以及将这些函数的输出串联起来所需的代码。此代码在沙盒环境中执行，生成后续的 BidiGenerateContentToolCall 消息。执行会暂停，直到每个函数调用的结果可用为止，从而确保顺序处理。

客户端应使用 BidiGenerateContentToolResponse 进行响应。

如需了解详情，请参阅函数调用简介。

音频格式

请参阅支持的音频格式列表。

系统指令

您可以提供系统指令，以便更好地控制模型的输出，并指定音频回答的语气和情感。

系统指令会在互动开始之前添加到提示中，并在整个会话期间保持有效。

系统指令只能在会话开始时设置，紧随初始连接之后。如需在会话期间向模型提供更多输入内容，请使用增量内容更新。

中断

用户可以随时中断模型的输出。当语音活动检测 (VAD) 检测到中断时，系统会取消并舍弃正在进行的生成操作。会话历史记录中仅保留已发送给客户端的信息。然后，服务器会发送 BidiGenerateContentServerContent 消息来报告中断。

此外，Gemini 服务器会舍弃所有待处理的函数调用，并发送一条 BidiGenerateContentServerContent 消息，其中包含已取消调用的 ID。

语音

如需指定语音，请在 speechConfig 对象中设置 voiceName，作为会话配置的一部分。

请参阅以下 speechConfig 对象的 JSON 表示法：

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "VOICE_NAME"
    }
  }
}

如需查看支持的语音列表，请参阅更改语音和语言设置。

限制

在规划项目时，请考虑 Live API 和 Gemini 2.0 的以下限制。

客户端身份验证

Live API 仅提供服务器到服务器的身份验证，不建议直接供客户端使用。客户端输入应通过中间应用服务器进行路由，以便通过 Live API 进行安全身份验证。

会话时长上限

对话会话的默认时长上限为 10 分钟。如需了解详情，请参阅会话时长。

语音活动检测 (VAD)

默认情况下，模型会对连续的音频输入流自动执行语音活动检测 (VAD)。可以使用设置消息的 RealtimeInputConfig.AutomaticActivityDetection 字段配置 VAD。

当音频流暂停超过一秒（例如，当用户关闭麦克风时），系统会发送 AudioStreamEnd 事件来清空所有缓存的音频。客户端可以随时恢复发送音频数据。

或者，您也可以在设置消息中将 RealtimeInputConfig.AutomaticActivityDetection.disabled 设置为 true，以关闭自动 VAD。在此配置中，客户端负责检测用户语音，并在适当的时间发送 ActivityStart 和 ActivityEnd 消息。此配置中未发送 AudioStreamEnd。而是会通过 ActivityEnd 消息标记任何流中断。

其他限制

不支持手动端点设置。

音频输入和音频输出会对模型使用函数调用的能力产生负面影响。

token 计数

不支持 token 计数。

速率限制

以下速率限制适用：

• 每个 API 密钥 5,000 个并发会话
• 每分钟 400 万个 token

消息和事件

后续步骤

• 详细了解函数调用。
• 如需查看示例，请参阅函数调用参考文档。