Live API - WebSockets API reference

Live API 是一种使用 WebSockets 的有状态 API。在本部分中，您将找到有关 WebSockets API 的更多详细信息。

会话

WebSocket 连接会在客户端与 Gemini 服务器之间建立会话。客户端发起新连接后，会话可以与服务器交换消息，以执行以下操作：

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

WebSocket 连接

如需开始会话，请连接到以下 WebSocket 端点：

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent

会话配置

建立 WebSocket 连接后发送的初始消息会设置会话配置，其中包括模型、生成参数、系统指令和工具。

连接处于打开状态时，您无法更新配置。不过，当通过会话恢复机制暂停和恢复时，您可以更改配置参数（模型除外）。

请参阅以下示例配置。请注意，SDK 中的名称大小写可能有所不同。您可以点击此处查看 Python SDK 配置选项。


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

如需详细了解此 API 字段，请参阅 generationConfig。

发送消息

如需通过 WebSocket 连接交换消息，客户端必须通过打开的 WebSocket 连接发送 JSON 对象。JSON 对象必须恰好具有以下对象集中的其中一个字段：


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

支持的客户端消息

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

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

接收消息

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

请参阅以下内容：

async with client.aio.live.connect(model='...', config=config) as session:
    await session.send(input='Hello world!', end_of_turn=True)
    async for message in session.receive():
        print(message)

服务器消息可能具有 usageMetadata 字段，但除此之外，还会包含 BidiGenerateContentServerMessage 消息中的其他字段，且这些字段恰好只有一个。（messageType 并集未在 JSON 中表示，因此该字段将显示在消息的顶层。）

消息和事件

ActivityEnd

此类型没有字段。

标记用户活动的结束。

ActivityHandling

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

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

ActivityStart

此类型没有字段。

标记用户活动的开始。

AudioTranscriptionConfig

此类型没有字段。

音频转写配置。

AutomaticActivityDetection

配置活动自动检测。

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

BidiGenerateContentClientContent

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

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

字段

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

turns[]

Content

可选。附加到与模型当前对话的内容。

对于单轮查询，这是单个实例。对于多轮查询，这是包含对话历史记录和最新请求的重复字段。

turnComplete

bool

可选。如果为 true，则表示服务器内容生成应从当前累积的提示开始。否则，服务器会等待更多消息，然后再开始生成。

BidiGenerateContentRealtimeInput

实时发送的用户输入。

不同的模态（音频、视频和文本）被视为并发流进行处理。无法保证这些数据流的顺序。

这与 BidiGenerateContentClientContent 有以下几点不同：

可以连续发送，不会中断模型生成。
如果需要混合使用交织分布在 BidiGenerateContentClientContent 和 BidiGenerateContentRealtimeInput 中的数据，服务器会尝试优化以获得最佳回答，但无法保证。
回合结束未明确指定，而是从用户活动（例如，语音结束）中推导得出。
即使在回合结束之前，系统也会以增量方式处理数据，以优化模型快速开始生成回答。

字段
`mediaChunks[]`	`Blob` 可选。媒体输入的内嵌字节数据。不支持多个 `mediaChunks`，除第一个之外的所有其他 `mediaChunks` 都会被忽略。已弃用：请改用 `audio`、`video` 或 `text`。
`audio`	`Blob` 可选。这些数据构成了实时音频输入流。
`video`	`Blob` 可选。这些帧构成了实时视频输入流。
`activityStart`	`ActivityStart` 可选。标记用户活动的开始。只有在停用自动（即服务器端）活动检测时，才能发送此事件。
`activityEnd`	`ActivityEnd` 可选。标记用户活动的结束。只有在停用自动（即服务器端）活动检测时，才能发送此事件。
`audioStreamEnd`	`bool` 可选。表示音频流已结束，例如，因为麦克风已关闭。只有在启用自动活动检测（默认设置）时，才应发送此事件。客户端可以通过发送音频消息来重新打开流。
`text`	`string` 可选。这些内容构成了实时文本输入流。

BidiGenerateContentServerContent

模型响应客户端消息而生成的增量服务器更新。

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

字段
`generationComplete`	`bool` 仅限输出。如果为 true，则表示模型已完成生成。当模型在生成过程中被中断时，中断的回合中将不会出现“generation_complete”消息，而是会经历“interrupted > turn_complete”。如果模型假设是实时播放，那么 generation_complete 和 turn_complete 之间会存在延迟，这是因为模型在等待播放完成。
`turnComplete`	`bool` 仅限输出。如果为 true，则表示模型已完成其回合。只有在收到其他客户端消息后，才会开始生成。
`interrupted`	`bool` 仅限输出。如果为 true，则表示客户端消息已中断当前的模型生成。如果客户端正在实时播放内容，则这是一个很好的信号，表明应停止并清空当前的播放队列。
`groundingMetadata`	`GroundingMetadata` 仅限输出。生成内容的依据元数据。
`inputTranscription`	`BidiGenerateContentTranscription` 仅限输出。输入音频转写。转写内容会独立于其他服务器消息发送，并且无法保证顺序。
`outputTranscription`	`BidiGenerateContentTranscription` 仅限输出。输出音频转写。转写内容会独立于其他服务器消息发送，并且不保证顺序，尤其是在 `serverContent` 和此 `outputTranscription` 之间。
`urlContextMetadata`	`UrlContextMetadata`
`modelTurn`	`Content` 仅限输出。模型在与用户当前对话中生成的内容。

BidiGenerateContentServerMessage

针对 BidiGenerateContent 调用的响应消息。

字段
`usageMetadata`	`UsageMetadata` 仅限输出。有关回答的用量元数据。
联合字段 `messageType`。消息的类型。`messageType` 只能是下列其中一项：
`setupComplete`	`BidiGenerateContentSetupComplete` 仅限输出。在设置完成后，发送以响应来自客户端的 `BidiGenerateContentSetup` 消息。
`serverContent`	`BidiGenerateContentServerContent` 仅限输出。模型响应客户端消息而生成的内容。
`toolCall`	`BidiGenerateContentToolCall` 仅限输出。请求客户端执行 `functionCalls` 并返回具有匹配 `id` 的响应。
`toolCallCancellation`	`BidiGenerateContentToolCallCancellation` 仅限输出。通知客户端，先前发出的具有指定 `id` 的 `ToolCallMessage` 应取消。
`goAway`	`GoAway` 仅限输出。服务器即将断开连接的通知。
`sessionResumptionUpdate`	`SessionResumptionUpdate` 仅限输出。更新会话恢复状态。

BidiGenerateContentSetup

要在第一个（也是唯一一个）BidiGenerateContentClientMessage 中发送的消息。包含将在整个流式 RPC 期间应用的配置。

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

字段
`model`	`string` 必需。模型的资源名称。用作要使用的模型的 ID。格式：`models/{model}`
`generationConfig`	`GenerationConfig` 可选。生成配置。不支持以下字段： `responseLogprobs` `responseMimeType` `logprobs` `responseSchema` `stopSequence` `routingConfig` `audioTimestamp`
`systemInstruction`	`Content` 可选。用户为模型提供的系统指令。注意：各部分中只能使用文本，并且每个部分中的内容都将位于单独的段落中。
`tools[]`	`Tool` 可选。模型可能用于生成下一个回答的 `Tools` 列表。 `Tool` 是一段代码，可让系统与外部系统进行交互，以在模型知识和范围之外执行操作或一组操作。
`realtimeInputConfig`	`RealtimeInputConfig` 可选。配置实时输入的处理。
`sessionResumption`	`SessionResumptionConfig` 可选。配置会话恢复机制。如果包含，服务器将发送 `SessionResumptionUpdate` 消息。
`contextWindowCompression`	`ContextWindowCompressionConfig` 可选。配置上下文窗口压缩机制。如果包含此参数，当上下文超出配置的长度时，服务器会自动减小上下文的大小。
`inputAudioTranscription`	`AudioTranscriptionConfig` 可选。如果已设置，则启用语音输入的转写功能。如果已配置，转写会与输入音频语言保持一致。
`outputAudioTranscription`	`AudioTranscriptionConfig` 可选。如果设置，则启用模型音频输出的转写。如果已配置，转写会与为输出音频指定的语言代码保持一致。
`proactivity`	`ProactivityConfig` 可选。配置模型的主动性。这样，模型就可以主动响应输入，并忽略无关的输入。

BidiGenerateContentSetupComplete

此类型没有字段。

发送以响应来自客户端的 BidiGenerateContentSetup 消息。

BidiGenerateContentToolCall

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

字段

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

functionCalls[]

FunctionCall

仅限输出。要执行的函数调用。

BidiGenerateContentToolCallCancellation

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

字段

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

ids[]

string

仅限输出。要取消的工具调用的 ID。

BidiGenerateContentToolResponse

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

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

字段

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

functionResponses[]

FunctionResponse

可选。对函数调用的响应。

BidiGenerateContentTranscription

音频（输入或输出）的转写内容。

字段

字段
`text`	`string` 转写文本。

text

string

转写文本。

ContextWindowCompressionConfig

启用上下文窗口压缩功能，这是一种用于管理模型上下文窗口的机制，可确保上下文窗口不超过给定的长度。

字段

字段
联合字段 `compressionMechanism`。所用的上下文窗口压缩机制。`compressionMechanism` 只能是下列其中一项：
`slidingWindow`	`SlidingWindow` 滑动窗口机制。
`triggerTokens`	`int64` 触发上下文窗口压缩所需的 token 数量（在运行对话轮次之前）。这可用于平衡质量与延迟时间，因为较短的上下文窗口可能会加快模型响应速度。不过，任何压缩操作都会导致暂时性延迟增加，因此不应频繁触发。如果未设置，则默认为模型上下文窗口限制的 80%。这样一来，剩余 20% 的时间可用于下一个用户请求/模型响应。

联合字段 compressionMechanism。所用的上下文窗口压缩机制。compressionMechanism 只能是下列其中一项：

slidingWindow

SlidingWindow

滑动窗口机制。

triggerTokens

int64

触发上下文窗口压缩所需的 token 数量（在运行对话轮次之前）。

这可用于平衡质量与延迟时间，因为较短的上下文窗口可能会加快模型响应速度。不过，任何压缩操作都会导致暂时性延迟增加，因此不应频繁触发。

如果未设置，则默认为模型上下文窗口限制的 80%。这样一来，剩余 20% 的时间可用于下一个用户请求/模型响应。

EndSensitivity

确定如何检测语音结束。

枚举
`END_SENSITIVITY_UNSPECIFIED`	默认值为 END_SENSITIVITY_HIGH。
`END_SENSITIVITY_HIGH`	自动检测结束语音的频率较高。
`END_SENSITIVITY_LOW`	自动检测结束语音的频率较低。

GoAway

服务器即将断开连接的通知。

字段

字段
`timeLeft`	`Duration` 连接在以 ABORTED 状态终止之前的剩余时间。此时长永远不会低于特定于模型的最小值，该最小值将与模型的速率限制一起指定。

timeLeft

Duration

连接在以 ABORTED 状态终止之前的剩余时间。

此时长永远不会低于特定于模型的最小值，该最小值将与模型的速率限制一起指定。

ProactivityConfig

主动性功能的配置。

字段

字段
`proactiveAudio`	`bool` 可选。如果启用，模型可以拒绝回复上一条提示。例如，这样一来，模型就可以忽略不合语境的语音，或者在用户尚未提出请求时保持静默。

proactiveAudio

bool

可选。如果启用，模型可以拒绝回复上一条提示。例如，这样一来，模型就可以忽略不合语境的语音，或者在用户尚未提出请求时保持静默。

RealtimeInputConfig

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

字段

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

automaticActivityDetection

AutomaticActivityDetection

可选。如果未设置，则默认启用自动活动检测。如果自动语音检测已停用，客户端必须发送活动信号。

activityHandling

ActivityHandling

可选。定义活动的具体效果。

turnCoverage

TurnCoverage

可选。定义用户回合中包含哪些输入。

SessionResumptionConfig

会话恢复配置。

此消息包含在会话配置中，如 BidiGenerateContentSetup.sessionResumption 所示。如果已配置，服务器将发送 SessionResumptionUpdate 消息。

字段

字段
`handle`	`string` 之前会话的句柄。如果不存在，则会创建新会话。会话句柄来自之前连接中的 `SessionResumptionUpdate.token` 值。

handle

string

之前会话的句柄。如果不存在，则会创建新会话。

会话句柄来自之前连接中的 SessionResumptionUpdate.token 值。

SessionResumptionUpdate

更新会话恢复状态。

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

字段

字段
`newHandle`	`string` 表示可恢复状态的新句柄。如果 `resumable`=false，则为空。
`resumable`	`bool` 如果此时可以恢复当前会话，则为 true。在会话中的某些时间点，无法恢复会话。例如，当模型正在执行函数调用或生成内容时。在此类状态下恢复会话（使用之前的会话令牌）会导致一些数据丢失。在这些情况下，`newHandle` 将为空，而 `resumable` 将为 false。

newHandle

string

表示可恢复状态的新句柄。如果 resumable=false，则为空。

resumable

bool

如果此时可以恢复当前会话，则为 true。

在会话中的某些时间点，无法恢复会话。例如，当模型正在执行函数调用或生成内容时。在此类状态下恢复会话（使用之前的会话令牌）会导致一些数据丢失。在这些情况下，newHandle 将为空，而 resumable 将为 false。

SlidingWindow

SlidingWindow 方法通过舍弃上下文窗口开头的内容来运行。生成的上下文始终从用户角色回合的开头开始。系统指令和任何 BidiGenerateContentSetup.prefixTurns 将始终位于结果的开头。

字段

字段
`targetTokens`	`int64` 要保留的目标令牌数量。默认值为 trigger_tokens/2。舍弃部分上下文窗口会导致暂时性延迟增加，因此应校准此值，以避免频繁的压缩操作。

targetTokens

int64

要保留的目标令牌数量。默认值为 trigger_tokens/2。

舍弃部分上下文窗口会导致暂时性延迟增加，因此应校准此值，以避免频繁的压缩操作。

StartSensitivity

确定如何检测语音开始。

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

TurnCoverage

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

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

UrlContextMetadata

与网址上下文检索工具相关的元数据。

字段

urlMetadata[]

UrlMetadata

网址上下文列表。

UsageMetadata

有关回答的用量元数据。

字段
`promptTokenCount`	`int32` 仅限输出。提示中的 token 数量。如果设置了 `cachedContent`，这仍然是有效提示的总大小，这意味着它包含缓存内容中的词元数。
`cachedContentTokenCount`	`int32` 提示的缓存部分（即缓存的内容）中的 token 数量
`responseTokenCount`	`int32` 仅限输出。所有生成的回答候选项中的 token 总数。
`toolUsePromptTokenCount`	`int32` 仅限输出。工具使用提示中的 token 数量。
`thoughtsTokenCount`	`int32` 仅限输出。思考模型的想法词元数。
`totalTokenCount`	`int32` 仅限输出。生成请求（提示 + 回答候选）的总 token 数。
`promptTokensDetails[]`	`ModalityTokenCount` 仅限输出。请求输入中处理的模态列表。
`cacheTokensDetails[]`	`ModalityTokenCount` 仅限输出。请求输入中缓存内容的模态列表。
`responseTokensDetails[]`	`ModalityTokenCount` 仅限输出。响应中返回的模态列表。
`toolUsePromptTokensDetails[]`	`ModalityTokenCount` 仅限输出。为工具使用请求输入处理的模态列表。

临时身份验证令牌

可以通过调用 AuthTokenService.CreateToken 获取临时身份验证令牌，然后通过在 access_token 查询参数中传递令牌或在 HTTP Authorization 标头中传递令牌（以“Token”作为前缀）将该令牌与 GenerativeService.BidiGenerateContentConstrained 搭配使用。

CreateAuthTokenRequest

创建临时身份验证令牌。

字段

字段
`authToken`	`AuthToken` 必需。要创建的令牌。

authToken

AuthToken

必需。要创建的令牌。

AuthToken

用于创建临时身份验证令牌的请求。

字段
`name`	`string` 仅限输出。标识符。令牌本身。
`expireTime`	`Timestamp` 可选。仅限输入。不可变。一个可选时间，在此时间之后，如果使用生成的令牌，BidiGenerateContent 会话中的消息将被拒绝。（Gemini 可能会在此时间后抢先关闭会话。）如果未设置，则此值默认为未来 30 分钟。如果设置了此值，则该值必须是未来 20 小时内的时间。
`newSessionExpireTime`	`Timestamp` 可选。仅限输入。不可变。使用此请求生成的令牌的新 Live API 会话将被拒绝的时间。如果未设置，则默认为未来 60 秒。如果设置了此值，则该值必须是未来 20 小时内的时间。
`fieldMask`	`FieldMask` 可选。仅限输入。不可变。如果 field_mask 为空，且不存在 `bidiGenerateContentSetup`，则有效 `BidiGenerateContentSetup` 消息将从 Live API 连接中获取。如果 field_mask 为空，且存在 `bidiGenerateContentSetup` ，则有效的 `BidiGenerateContentSetup` 消息完全取自此请求中的 `bidiGenerateContentSetup`。来自 Live API 连接的设置消息会被忽略。如果 field_mask 不为空，则 `bidiGenerateContentSetup` 中的相应字段将覆盖 Live API 连接中设置消息的字段。
联合字段 `config`。生成的令牌的方法特定配置。`config` 只能是下列其中一项：
`bidiGenerateContentSetup`	`BidiGenerateContentSetup` 可选。仅限输入。不可变。特定于 `BidiGenerateContent` 的配置。
`uses`	`int32` 可选。仅限输入。不可变。相应令牌可使用的次数。如果此值为零，则不应用任何限制。恢复 Live API 会话不计为一次使用。如果未指定，则默认值为 1。

有关常见类型的更多信息

如需详细了解常用的 API 资源类型 Blob、Content、FunctionCall、FunctionResponse、GenerationConfig、GroundingMetadata、ModalityTokenCount 和 Tool，请参阅生成内容。