实时 API 参考文档

预览版

此功能受服务专用条款的“通用服务条款”部分中的“非正式版产品条款”的约束。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

如需试用教程，了解如何使用语音和摄像头通过 Live API 与 Gemini 对话，请参阅 websocket-demo-app 教程。

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

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

功能

Live API 包含以下主要功能：

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

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

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

支持的模型

• Gemini 2.5 Flash（支持 Live API 原生音频功能）（预览版）
• 支持 Live API 的 Gemini 2.0 Flash（预览版）
• Gemini 2.5 Flash

开始使用

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

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

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

Python

安装

pip install --upgrade google-genai

如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：

# 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
}

支持的客户端消息

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

消息	说明
BidiGenerateContentSetup	要在第一条消息中发送的会话配置
BidiGenerateContentClientContent	从客户端传送的当前对话的增量内容更新
BidiGenerateContentRealtimeInput	实时音频或视频输入
BidiGenerateContentToolResponse	对从服务器收到的 ToolCallMessage 的响应

接收消息

如需接收来自 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
}

支持的服务器消息

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

消息	说明
BidiGenerateContentSetupComplete	来自客户端的 BidiGenerateContentSetup 消息，在设置完成后发送
BidiGenerateContentServerContent	模型根据客户消息生成的内容
BidiGenerateContentToolCall	请求客户端运行函数调用并返回具有匹配 ID 的响应
BidiGenerateContentToolCallCancellation	当函数调用因用户中断模型输出而被取消时发送
UsageMetadata	报告会话到目前为止使用的令牌数
GoAway	表示当前连接即将终止的信号
SessionResumptionUpdate	可恢复的会话检查点
BidiGenerateContentTranscription	用户或模型的语音转写内容

增量内容更新

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

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

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

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

流式音频和视频

如需查看如何以流式音频和视频格式使用 Live API 的示例，请在以下任一环境中运行“使用 Gen AI SDK 开始使用 Live API”笔记本：

在 Colab 中打开 | 在 Colab Enterprise 中打开 | 在 Vertex AI Workbench 中打开 | 在 GitHub 上查看

代码执行

如需查看代码执行示例，请在以下任一环境中运行“使用 Gemini 2.0 生成和执行 Python 代码简介”笔记本：

在 Colab 中打开 | 在 Colab Enterprise 中打开 | 在 Vertex AI Workbench 中打开 | 在 GitHub 上查看

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

函数调用

如需查看函数调用的示例，请在以下任一环境中运行“使用 Gemini API 调用函数简介”笔记本：

在 Colab 中打开 | 在 Colab Enterprise 中打开 | 在 Vertex AI Workbench 中打开 | 在 GitHub 上查看

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

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

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

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

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

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

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

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

  • 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

消息和事件

BidiGenerateContentClientContent

从客户端传送的当前对话的增量更新。此处的所有内容都会无条件附加到对话历史记录中，并用作提示的一部分，以供模型生成内容。

此处的任何消息都会中断当前的模型生成。

字段
turns[]	Content 可选。附加到与模型当前对话的内容。 对于单轮查询，这是单个实例。对于多轮查询，这是包含对话历史记录和最新请求的重复字段。
turn_complete	bool 可选。如果为 true，则表示服务器内容生成应从当前累积的提示开始。否则，服务器将等待更多消息，然后才开始生成。

BidiGenerateContentRealtimeInput

实时发送的用户输入。

这与 ClientContentUpdate 有以下几点不同：

• 可以连续发送，不会中断模型生成。
• 如果需要混合使用交织在 ClientContentUpdate 和 RealtimeUpdate 中的数据，服务器会尝试优化以获得最佳响应，但无法保证。
• 回合结束未明确指定，而是从用户活动（例如，语音结束）中推导得出。
• 即使在回合结束之前，系统也会以增量方式处理数据，以优化模型快速开始生成回答。
• 始终假定为用户输入（不能用于填充对话历史记录）。

字段
media_chunks[]	Blob 可选。媒体输入的内嵌字节数据。
activity_start	ActivityStart 可选。标记用户活动的开始。只有在停用自动（即服务器端）活动检测功能时，才能发送此事件。
activity_end	ActivityEnd 可选。标记用户活动的结束。只有在停用自动（即服务器端）活动检测功能时，才能发送此事件。

ActivityEnd

此类型没有字段。

标记用户 activity 的结束。

ActivityStart

此类型没有字段。

此消息中一次只能设置一个字段。标记用户活动的开始。

BidiGenerateContentServerContent

模型根据客户端消息生成的增量服务器更新。

内容会尽快生成，但不是实时生成。客户端可以选择缓冲并实时播放。

字段
turn_complete	bool 仅限输出。如果为 true，则表示模型已完成生成。只有在收到其他客户端消息后，才会开始生成。可与 content 一起设置，表示 content 是回合中的最后一个。
interrupted	bool 仅限输出。如果为 true，表示客户端消息已中断当前模型生成。如果客户端正在实时播放内容，则这是一个很好的信号，表明应停止并清空当前队列。如果客户端正在实时播放内容，则这是一个停止并清空当前播放队列的好信号。
generation_complete	bool 仅限输出。如果为 true，则表示模型已完成生成。 如果模型在生成过程中被中断，则中断的轮次中不会有“generation_complete”消息，而是会经历“interrupted > turn_complete”。 如果模型假设是实时播放，那么 generation_complete 和 turn_complete 之间会存在延迟，这是因为模型在等待播放完成。
grounding_metadata	GroundingMetadata 仅限输出。元数据用于指定用于为生成的内容提供依据的来源。
input_transcription	Transcription 可选。输入转写内容。转写独立于模型轮次，这意味着转写和模型轮次之间没有任何顺序关系。
output_transcription	Transcription 可选。输出转写内容。转写独立于模型轮次，这意味着转写和模型轮次之间没有任何顺序关系。
model_turn	Content 仅限输出。模型在与用户的当前对话中生成的内容。

转录

音频转写消息。

字段
text	string 可选。转写文本。
finished	bool 可选。该布尔值表示转写结束。

BidiGenerateContentSetup

要在第一个也是唯一一个客户端消息中发送的消息。包含将在整个流式会话期间应用的配置。

客户端应先等待 BidiGenerateContentSetupComplete 消息，然后再发送任何其他消息。

字段
model	string 必需。发布商模型的完全限定名称。 发布方模型格式：projects/{project}/locations/{location}/publishers/\*/models/\*
generation_config	GenerationConfig 可选。生成配置。 不支持以下字段： response_logprobs response_mime_type logprobs response_schema stop_sequence routing_config audio_timestamp
system_instruction	Content 可选。用户为模型提供的系统指令。注意：各部分中只能使用文本，并且每个部分中的内容都将位于单独的段落中。
tools[]	Tool 可选。模型可能用于生成下一个回答的 Tools 列表。 Tool 是一段代码，可让系统与外部系统进行交互，以在模型知识和范围之外执行操作或一组操作。
session_resumption	SessionResumptionConfig 可选。配置会话恢复机制。如果包含，服务器将定期向客户端发送 SessionResumptionUpdate 消息。
context_window_compression	ContextWindowCompressionConfig 可选。配置上下文窗口压缩机制。 如果包含此参数，服务器会将上下文窗口压缩到指定长度。
realtime_input_config	RealtimeInputConfig 可选。配置实时输入的处理方式。
input_audio_transcription	AudioTranscriptionConfig 可选。输入内容的转写与输入音频的语言一致。
output_audio_transcription	AudioTranscriptionConfig 可选。输出的转写内容与为输出音频指定的语言代码保持一致。

AudioTranscriptionConfig

此类型没有字段。

音频转写配置。

BidiGenerateContentSetupComplete

此类型没有字段。

为响应客户端发送的 BidiGenerateContentSetup 消息而发送。

BidiGenerateContentToolCall

请求客户端执行 function_calls 并返回具有匹配 id 的响应。

字段
function_calls[]	FunctionCall 仅限输出。要执行的函数调用。

BidiGenerateContentToolCallCancellation

通知客户端，之前发布的具有指定 id 的 ToolCallMessage 应该未执行，并且应该取消。如果这些工具调用存在副作用，客户端可能会尝试撤消这些工具调用。此消息仅在客户端中断服务器回合时出现。

字段
ids[]	string 仅限输出。要取消的工具调用的 ID。

BidiGenerateContentToolResponse

客户端针对从服务器收到的 ToolCall 生成的响应。各个 FunctionResponse 对象通过 id 字段与各自的 FunctionCall 对象匹配。

请注意，在一元和服务器流式 GenerateContent API 中，函数调用是通过交换 Content 部分实现的，而在双向 GenerateContent API 中，函数调用是通过这些专用消息集实现的。

字段
function_responses[]	FunctionResponse 可选。对函数调用的响应。

RealtimeInputConfig

配置 BidiGenerateContent 中的实时输入行为。

字段
automatic_activity_detection	AutomaticActivityDetection 可选。如果未设置，则默认启用自动活动检测。如果自动语音检测功能已停用，客户端必须发送活动信号。
activity_handling	ActivityHandling 可选。定义效果活动具有的效果。
turn_coverage	TurnCoverage 可选。定义用户回合中包含哪些输入。

ActivityHandling

处理用户活动的不同方式。

枚举
ACTIVITY_HANDLING_UNSPECIFIED	如果未指定，则默认行为为 START_OF_ACTIVITY_INTERRUPTS。
START_OF_ACTIVITY_INTERRUPTS	如果为 true，则 activity 的启动会中断模型的响应（也称为“抢占”）。模型当前的回答将在中断时被截断。这是默认行为。
NO_INTERRUPTION	模型不会中断回答。

AutomaticActivityDetection

配置活动自动检测。

字段
start_of_speech_sensitivity	StartSensitivity 可选。确定检测到语音的可能性。
end_of_speech_sensitivity	EndSensitivity 可选。确定检测到的语音结束的可能性。
prefix_padding_ms	int32 可选。在提交语音开头之前检测到的所需语音时长。此值越低，语音开始检测的灵敏度越高，可识别的语音越短。不过，这也会增加出现假正例的概率。
silence_duration_ms	int32 可选。在提交语音结束之前检测到的静音（或非语音）的所需时长。此值越大，语音间断时间越长，而不会中断用户活动，但会增加模型的延迟时间。
disabled	bool 可选。如果启用，检测到的语音和文本输入将计为活动。如果停用，客户端必须发送活动信号。

EndSensitivity

结束语音识别的灵敏度。

枚举
END_SENSITIVITY_UNSPECIFIED	默认值为 END_SENSITIVITY_LOW。
END_SENSITIVITY_HIGH	自动检测功能更频繁地结束语音。
END_SENSITIVITY_LOW	自动检测功能结束语音的频率较低。

StartSensitivity

开始语音识别的灵敏度。

枚举
START_SENSITIVITY_UNSPECIFIED	默认值为 START_SENSITIVITY_LOW。
START_SENSITIVITY_HIGH	自动检测功能会更频繁地检测到语音的开始。
START_SENSITIVITY_LOW	自动检测功能检测到语音开始的频率会降低。

TurnCoverage

有关用户回合中包含哪些输入的选项。

枚举
TURN_COVERAGE_UNSPECIFIED	如果未指定，则默认行为为 TURN_INCLUDES_ALL_INPUT。
TURN_INCLUDES_ONLY_ACTIVITY	用户轮次仅包括自上一个轮次以来的活动，不包括不活动（例如音频流中的静音）。
TURN_INCLUDES_ALL_INPUT	用户轮次包括自上一个轮次以来的所有实时输入，包括不活动状态（例如音频流中的静音）。这是默认行为。

UsageMetadata

有关缓存内容使用情况的元数据。

字段
total_token_count	int32 缓存内容消耗的令牌总数。
text_count	int32 文本字符数。
image_count	int32 图片数量。
video_duration_seconds	int32 视频时长（以秒为单位）。
audio_duration_seconds	int32 音频时长（以秒为单位）。

GoAway

服务器很快将无法为客户端提供服务。

字段
time_left	Duration 连接在终止为 ABORTED 状态之前的剩余时间。此处返回的最小时间与给定模型的速率限制一起以不同的方式指定。

SessionResumptionUpdate

更新会话恢复状态。

仅当设置了 BidiGenerateContentSetup.session_resumption 时才发送。

字段
new_handle	string 表示可恢复状态的新句柄。如果 resumable=false，则为空。
resumable	bool 如果会话可以在此点恢复，则为 true。 在某些情况下，可能无法恢复会话。在这种情况下，我们会发送更新后的空 new_handle，并将 resumable 设置为 false。此类情况的示例可以是模型执行函数调用或仅生成内容。在此状态下恢复会话（使用之前的会话令牌）会导致一些数据丢失。
last_consumed_client_message_index	int64 相应会话恢复令牌所表示的状态中包含的客户端发送的最后一条消息的索引。仅在设置了 SessionResumptionConfig.transparent 时发送。 有了此索引，用户可以透明地重新连接，避免丢失部分实时音频输入/视频。如果客户端希望暂时断开连接（例如，由于收到 GoAway 而断开连接），则可以通过缓冲自上次 SessionResmumptionTokenUpdate 以来发送的消息来断开连接，而不会丢失状态。此字段将使他们能够限制缓冲（避免将所有请求都保留在 RAM 中）。 它不会用于稍后的“恢复以还原状态”；在这些情况下，可能不需要部分音频和视频帧。

后续步骤

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