Gemini Live API

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Gemini Live API 支持使用文本、音频和视频输入进行低延迟的双向互动，并提供音频和文本输出。这有助于实现自然的、类似人类的语音对话，并能够随时中断模型。该模型的视频理解功能扩展了沟通模式，让您可以分享摄像头输入或屏幕投放内容，并提出相关问题。

功能

Live API 包含以下主要功能：

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

Live API 专用于服务器到服务器通信。

对于网站和移动应用，我们建议您使用 Daily 合作伙伴提供的集成服务。

开始使用

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

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

本部分通过示例介绍了如何使用 Python 3.9 及更高版本的 Live API 进行文本到文本生成。

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=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import (
    Content,
    LiveConnectConfig,
    HttpOptions,
    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（字符串）：全面说明函数的用途和功能。

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

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

  • properties（对象）：列出各个参数，每个参数包含：

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

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

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

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

客户端应返回 BidiGenerateContentToolResponse 响应。

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

音频格式

Live API 支持以下音频格式：

• 输入音频格式：16kHz 小端字节序的原始 16 位 PCM 音频
• 输出音频格式：24kHz 小端字节序的原始 16 位 PCM 音频

系统指令

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

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

系统说明只能在会话开始时（初始连接后立即）设置。如需在会话期间向模型提供更多输入，请使用增量内容更新。

中断

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

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

语音

Live API 支持以下语音：

• Puck
• Charon
• Kore
• Fenrir
• Aoede

如需指定语音，请在会话配置中，在 speechConfig 对象内设置 voiceName。

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

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

限制

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

客户端身份验证

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

对话记录

虽然该模型会跟踪会话内的互动，但不会存储对话记录。会话结束后，系统会清除相应上下文。

为了恢复之前的会话或向模型提供用户互动的历史上下文，应用应维护自己的对话日志，并在新的会话开始时使用 BidiGenerateContentClientContent 消息发送此信息。

会话时长上限

会话时长：音频不超过 15 分钟，音频和视频不超过 2 分钟。当会话时长超出限制时，连接会终止。

模型还受上下文大小的限制。在视频和音频流中发送大量内容可能会导致会话提前终止。

语音活动检测 (VAD)

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

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

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

其他限制

不支持手动端点设置。

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

token 计数

不支持 token 计数。

速率限制

以下速率限制适用：

• 每个 API 密钥 3 个并发会话
• 每分钟 400 万个 token

消息和事件

后续步骤

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