Live API 是一种使用 WebSockets 的有状态 API。在本部分中，您将详细了解 WebSockets API。
会话
WebSocket 连接会在客户端和 Gemini 服务器之间建立会话。客户端发起新连接后，会话可以与服务器交换消息，以执行以下操作：
- 向 Gemini 服务器发送文本、音频或视频。
- 接收来自 Gemini 服务器的音频、文本或函数调用请求。
WebSocket 连接
如需启动会话，请连接到此 WebSocket 端点：
wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent
会话配置
连接后的初始消息会设置会话配置，其中包括模型、生成参数、系统说明和工具。
您可以在会话期间更改除模型以外的配置参数。
请参阅以下示例配置。请注意，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“message”事件，然后根据支持的服务器消息的定义解析结果。
请参阅以下内容：
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，activity 的开始将中断模型的响应（也称为“插入”）。模型的当前回答将在中断时中止。这是默认行为。 |
NO_INTERRUPTION |
模型的回答不会中断。 |
ActivityStart
此类型没有字段。
标记用户活动的开始时间。
AudioTranscriptionConfig
此类型没有字段。
音频转写配置。
AutomaticActivityDetection
配置自动检测活动。
| 字段 | |
|---|---|
disabled |
可选。如果启用（默认），系统会将检测到的语音和文本输入计为活动。如果停用，客户端必须发送活动信号。 |
startOfSpeechSensitivity |
可选。确定系统检测到语音的可能性。 |
prefixPaddingMs |
可选。在提交语音开始时间之前，检测到的语音所需的时长。此值越低，语音开始检测的灵敏度就越高，系统可以识别的语音越短。不过，这也会增加出现假正例的概率。 |
endOfSpeechSensitivity |
可选。确定检测到的语音结束的可能性。 |
silenceDurationMs |
可选。在提交语音结束时间之前，检测到的非语音（例如静音）所需的时长。此值越大，语音间隔时间可以越长，而不会中断用户的活动，但这会增加模型的延迟时间。 |
BidiGenerateContentClientContent
对客户端传送的当前对话进行增量更新。此处的所有内容都会无条件附加到对话历史记录中，并用作向模型发出的提示的一部分，以便模型生成内容。
此处显示消息会中断任何当前的模型生成。
| 字段 | |
|---|---|
turns[] |
可选。附加到与模型当前对话的内容。 对于单轮查询，这是单个实例。对于多轮查询，这是包含对话历史记录和最新请求的重复字段。 |
turnComplete |
可选。如果为 true，则表示服务器内容生成应从当前累积的提示开始。否则，服务器会等待其他消息，然后再开始生成。 |
BidiGenerateContentRealtimeInput
实时发送的用户输入。
系统会将不同的模态（音频、视频和文本）作为并发流进行处理。我们无法保证这些数据流的顺序。
这与 BidiGenerateContentClientContent 在以下几个方面有所不同：
- 可以连续发送，不会中断模型生成。
- 如果需要混合在
BidiGenerateContentClientContent和BidiGenerateContentRealtimeInput中交错的数据，服务器会尝试进行优化以获得最佳响应，但无法保证。 - 未明确指定转换结束，而是从用户活动（例如语音结束）派生而来。
- 即使在对话结束之前，系统也会增量处理数据，以便优化模型快速开始回答。
| 字段 | |
|---|---|
mediaChunks[] |
可选。媒体输入的内嵌字节数据。不支持多个 已弃用：请改用 |
audio |
可选。这些数据构成了实时音频输入流。 |
video |
可选。这些数据组成了实时视频输入流。 |
activityStart |
可选。标记用户活动的开始时间。只有在停用自动（即服务器端）活动检测后，系统才会发送此信号。 |
activityEnd |
可选。标记用户活动结束。只有在停用自动（即服务器端）活动检测后，系统才会发送此事件。 |
audioStreamEnd |
可选。表示音频流已结束，例如由于麦克风已关闭。 只有在启用自动活动检测（默认设置）时，才应发送此事件。 客户端可以通过发送音频消息来重新打开流式传输。 |
text |
可选。这些数据构成了实时文本输入流。 |
BidiGenerateContentServerContent
模型为响应客户端消息而生成的增量服务器更新。
内容会尽快生成，但不是实时生成。客户端可以选择缓冲并实时播放。
| 字段 | |
|---|---|
generationComplete |
仅限输出。如果为 true，则表示模型已生成完毕。 当模型在生成过程中被中断时，中断转弯中不会出现“generation_complete”消息，而是会经历“interrupted > turn_complete”。 当模型假定实时播放时，generation_complete 和 turn_complete 之间会出现延迟，这是由模型等待播放完成所致。 |
turnComplete |
仅限输出。如果为 true，则表示模型已完成其回合。系统仅会在响应其他客户端消息时开始生成。 |
interrupted |
仅限输出。如果为 true，则表示客户端消息中断了当前的模型生成。如果客户端正在实时播放内容，则表示可以停止并清空当前的播放队列。 |
groundingMetadata |
仅限输出。为生成的内容提供元数据依据。 |
outputTranscription |
仅限输出。输出音频转写内容。转写内容独立于其他服务器消息发送，并且无法保证顺序，尤其是 |
modelTurn |
仅限输出。模型在与用户的当前对话中生成的内容。 |
BidiGenerateContentServerMessage
BidiGenerateContent 调用的响应消息。
| 字段 | |
|---|---|
usageMetadata |
仅限输出。有关响应的使用情况元数据。 |
联合字段 messageType。消息的类型。messageType 只能是下列其中一项： |
|
setupComplete |
仅限输出。在设置完成后，作为对客户端发送的 |
serverContent |
仅限输出。模型为响应客户消息而生成的内容。 |
toolCall |
仅限输出。请求客户端执行 |
toolCallCancellation |
仅限输出。通知客户应取消之前使用指定 |
goAway |
仅限输出。服务器即将断开连接的通知。 |
sessionResumptionUpdate |
仅限输出。更新会话恢复状态。 |
BidiGenerateContentSetup
要在第一个（且仅在第一个）BidiGenerateContentClientMessage 中发送的消息。包含将在流式 RPC 期间应用的配置。
客户端应先等待 BidiGenerateContentSetupComplete 消息，然后才能发送任何其他消息。
| 字段 | |
|---|---|
model |
必需。模型的资源名称。此 ID 将用作模型的 ID。 格式： |
generationConfig |
可选。生成配置。 不支持以下字段：
|
systemInstruction |
可选。用户为模型提供的系统说明。 注意：部分中应仅使用文本，并且每个部分中的内容都应位于单独的段落中。 |
tools[] |
可选。模型可能用于生成下一个回答的
|
realtimeInputConfig |
可选。配置实时输入的处理方式。 |
sessionResumption |
可选。配置会话恢复机制。 如果包含，服务器将发送 |
contextWindowCompression |
可选。配置上下文窗口压缩机制。 如果包含，则当上下文超出配置的长度时，服务器会自动缩减上下文的大小。 |
outputAudioTranscription |
可选。如果设置，则启用模型音频输出的转写功能。转写内容与为输出音频指定的语言代码（如果已配置）保持一致。 |
BidiGenerateContentSetupComplete
此类型没有字段。
作为对客户端发送的 BidiGenerateContentSetup 消息的响应而发送。
BidiGenerateContentToolCall
请求客户端执行 functionCalls 并返回包含匹配 id 的响应。
| 字段 | |
|---|---|
functionCalls[] |
仅限输出。要执行的函数调用。 |
BidiGenerateContentToolCallCancellation
向客户端发送通知，告知之前使用指定 id 签发的 ToolCallMessage 不应执行，应予以取消。如果这些工具调用产生了副作用，客户端可能会尝试撤消工具调用。只有在客户端中断服务器转换时，才会出现此消息。
| 字段 | |
|---|---|
ids[] |
仅限输出。要取消的工具调用的 ID。 |
BidiGenerateContentToolResponse
客户端针对从服务器收到的 ToolCall 生成的响应。各个 FunctionResponse 对象会通过 id 字段与相应的 FunctionCall 对象进行匹配。
请注意，在单项和服务器流式 GenerateContent API 中，函数调用是通过交换 Content 部分进行的，而在双向 GenerateContent API 中，函数调用是通过这组专用消息进行的。
| 字段 | |
|---|---|
functionResponses[] |
可选。对函数调用的响应。 |
BidiGenerateContentTranscription
音频转写（输入或输出）。
| 字段 | |
|---|---|
text |
转写文本。 |
ContextWindowCompressionConfig
启用上下文窗口压缩 - 一种用于管理模型上下文窗口以使其不超过给定长度的机制。
| 字段 | |
|---|---|
联合字段 compressionMechanism。使用的上下文窗口压缩机制。compressionMechanism 只能是下列其中一项： |
|
slidingWindow |
滑动窗口机制。 |
triggerTokens |
触发上下文窗口压缩所需的令牌数量（在运行一轮之前）。 这可用于平衡质量和延迟时间，因为上下文窗口越短，模型响应速度就越快。不过，任何压缩操作都会导致暂时延迟增加，因此不应频繁触发。 如果未设置，则默认为模型上下文窗口限制的 80%。这样，系统会将 20% 的资源留给下一个用户请求/模型响应。 |
EndSensitivity
确定如何检测语音结束。
| 枚举 | |
|---|---|
END_SENSITIVITY_UNSPECIFIED |
默认值为 END_SENSITIVITY_HIGH。 |
END_SENSITIVITY_HIGH |
自动检测功能会更频繁地结束语音。 |
END_SENSITIVITY_LOW |
自动检测功能会更少地结束语音。 |
GoAway
服务器即将断开连接的通知。
| 字段 | |
|---|---|
timeLeft |
连接终止为“ABORTED”前的剩余时间。 此时长绝不会低于特定于模型的最小时长，该时长将与模型的速率限制一起指定。 |
RealtimeInputConfig
在 BidiGenerateContent 中配置实时输入行为。
| 字段 | |
|---|---|
automaticActivityDetection |
可选。如果未设置，则自动活动检测功能默认处于启用状态。如果停用了自动语音检测，客户端必须发送活动信号。 |
activityHandling |
可选。定义 activity 的效果。 |
turnCoverage |
可选。定义用户回合中包含哪些输入。 |
SessionResumptionConfig
会话恢复配置。
此消息会作为 BidiGenerateContentSetup.sessionResumption 包含在会话配置中。如果已配置，服务器将发送 SessionResumptionUpdate 消息。
| 字段 | |
|---|---|
handle |
上一个会话的句柄。如果不存在，则会创建新的会话。 会话句柄来自之前连接中的 |
SessionResumptionUpdate
更新会话恢复状态。
仅在设置了 BidiGenerateContentSetup.sessionResumption 时才发送。
| 字段 | |
|---|---|
newHandle |
表示可恢复状态的新句柄。如果 |
resumable |
如果当前会话在此时可以恢复，则为 true。 在会话的某些时间点无法恢复。例如，当模型执行函数调用或生成时。在这种状态下恢复会话（使用之前的会话令牌）会导致部分数据丢失。在这些情况下， |
SlidingWindow
SlidingWindow 方法的运作方式是丢弃上下文窗口开头的内容。生成的上下文始终从用户角色转换开始。系统说明和任何 BidiGenerateContentSetup.prefixTurns 始终会位于结果开头。
| 字段 | |
|---|---|
targetTokens |
要保留的目标令牌数。默认值为 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 |
用户回合包括自上次回合以来的所有实时输入，包括无活动（例如音频流中无声）。 |
UsageMetadata
与响应相关的使用情况元数据。
| 字段 | |
|---|---|
promptTokenCount |
仅限输出。提示中的令牌数量。设置 |
cachedContentTokenCount |
提示的缓存部分（缓存内容）中的词元数 |
responseTokenCount |
仅限输出。所有生成的候选回答中的词元总数。 |
toolUsePromptTokenCount |
仅限输出。工具使用提示中的词元数量。 |
thoughtsTokenCount |
仅限输出。思考模型的想法令牌数。 |
totalTokenCount |
仅限输出。生成请求的总令牌数（问题 + 回答候选）。 |
promptTokensDetails[] |
仅限输出。在请求输入中处理的模态列表。 |
cacheTokensDetails[] |
仅限输出。请求输入中缓存内容的模态列表。 |
responseTokensDetails[] |
仅限输出。响应中返回的模态列表。 |
toolUsePromptTokensDetails[] |
仅限输出。为工具使用请求输入处理的模态列表。 |
详细了解常见类型
如需详细了解常用的 API 资源类型 Blob、Content、FunctionCall、FunctionResponse、GenerationConfig、GroundingMetadata、ModalityTokenCount 和 Tool，请参阅生成内容。