Gemini Live API 实战指南基于 Agent Skills 仓库的实时双向流式交互开发【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本指南以 skills/cloud/gemini-api/references/live_api.md 为核心骨架结合本仓库 gemini-live-api 技能中的 WebSocket 线协议文档与 proto 定义进行深度展开。读者将掌握如何用 Google Gen AI SDKPython建立 Live API 会话、配置LiveConnectConfig、发送文本与实时音频/视频输入、理解ClientMessage/ServerMessage双向消息协议、以及如何实现会话恢复与语音/转写处理最终构建出低延迟的交互式语音与视频应用。一、Live API 是什么Gemini Live API 是 Gemini API 面向实时交互场景的能力分支。与一次性请求/响应的generate_content不同Live API 通过WebSocket 提供实时、低延迟的双向流式传输bidirectional streaming专门服务于交互式语音和视频应用——例如语音助手、实时口译、屏幕共享讲解、人机多轮对话等。在本仓库中Live API 属于 gemini-api 技能所覆盖的核心能力之一该技能同时覆盖文本生成、多模态理解、函数调用、结构化输出、上下文缓存、Embeddings、批量预测等仓库还为 Live API 单独提供了 gemini-live-api 技能用于生成一个完整的 LiveAPI 客户端服务类其中包含会话建立/恢复、Bearer Token 刷新、ClientMessage/ServerMessageproto 收发等能力。本指南聚焦直接用 SDK 上手 Live API并向下延伸到仓库中沉淀的底层协议细节。核心特点一览实时双向客户端与服务端通过 WebSocket 同时收发消息延迟低至亚秒级多模态输入支持连续音频流PCM、视频帧JPEG/PNG/WebP与文本流流式输出模型以音频块24 kHz PCM和/或文本流式返回支持中途打断会话恢复支持透明会话恢复transparent session resumption断线自动重连不丢上下文。二、环境准备与 SDK 选型根据 gemini-api 的说明Live API 统一使用Gen AI SDKPythonpip install google-genaiJavaScript/TypeScriptgoogle/genaiGogoogle.golang.org/genaiJavacom.google.genai:google-genaiC#/.NETGoogle.GenAI[!IMPORTANT] 不要使用google-cloud-aiplatform、google-cloud/vertexai、google-generativeai等旧版 SDK仓库明确标注其为已弃用deprecated方案。认证上推荐使用环境变量 应用默认凭据ADC初始化客户端时不传参即可自动拾取export GOOGLE_CLOUD_PROJECTyour-project-id export GOOGLE_CLOUD_LOCATIONglobal export GOOGLE_GENAI_USE_ENTERPRISEtrue若使用 Express ModeAPI Key则设置export GOOGLE_API_KEYyour-api-key export GOOGLE_GENAI_USE_ENTERPRISEtrueLive API 专用模型仓库 gemini-api 中明确列出Live Realtime API含原生音频应使用gemini-live-2.5-flash-native-audio该模型支持原生音频输入输出可在对话中自动切换语言对于非原生音频模型则需要在speechConfig.languageCode中显式指定输出语言。三、最小可运行示例Python 文本会话references/live_api.md 给出的第一个完整示例即是一个文本模式的 Live 会话import asyncio from google import genai from google.genai import types async def generate_content(): client genai.Client() model_id gemini-live-2.5-flash-native-audio config types.LiveConnectConfig( response_modalities[types.LiveModality.TEXT], # Change to AUDIO for voice responses ) async with client.aio.live.connect(modelmodel_id, configconfig) as session: text_input Hello? Gemini, are you there? await session.send_client_content( turnstypes.Content(roleuser, parts[types.Part.from_text(texttext_input)]) ) async for message in session.receive(): if message.text: print(message.text, end) asyncio.run(generate_content())逐段拆解代码片段作用genai.Client()创建客户端自动读取环境变量中的项目、区域与企业模式配置types.LiveConnectConfig(response_modalities[...])声明会话的响应模态。TEXT为纯文本回复改为AUDIO则返回语音client.aio.live.connect(...)异步上下文管理器负责建立 WebSocket 连接并在退出时关闭会话session.send_client_content(...)发送回合制turn-based内容写入对话历史并触发生成session.receive()异步迭代服务端消息流message.text提取文本片段[!NOTE]client.aio是 SDK 的异步入口send_client_content发送的消息会进入对话历史属于clientContent帧与后面要讲的send_realtime_input实时流不入历史是两种不同的输入通道。四、发送实时音频send_realtime_input在语音应用场景中麦克风采集的音频需要以连续流的方式送入模型。原文档给出了核心用法await session.send_realtime_input( mediaBlob(dataaudio_bytes, mime_typeaudio/pcm;rate16000) )结合仓库中的线协议文档 client_server_messages.md 与 client_server_messages.protorealtimeInput帧的关键约束如下输入音频格式PCM16-bit 有符号16 kHz 采样率单声道小端序base64 编码MIME 类型为audio/pcm;rate16000输出音频格式24 kHz16-bit 有符号 PCM单声道服务端下发的modelTurn.parts[].inlineData中mimeType 为audio/pcm;rate24000不入历史realtimeInput不会写入对话历史属于瞬时信号轮次边界默认由**服务端 VAD语音活动检测**决定若在setup中关闭自动 VAD则需自行发送activityStart/activityEnd逐块发送以约 20–100 ms 为一帧逐个发送麦克风关闭在自动 VAD 开启时麦克风关闭应发送{ realtimeInput: { audioStreamEnd: true } }提交流结束。对应 proto见 client_server_messages.proto 中BidiGenerateContentRealtimeInputmessage BidiGenerateContentRealtimeInput { repeated Blob media_chunks 1 [deprecated true]; // 已弃用 Blob audio 2; // PCM 16-bit, 16 kHz mono Blob video 3; // image/jpeg|png|webp string text 4; bool audio_stream_end 5; ActivityStart activity_start 6; // 仅自动 VAD 关闭时 ActivityEnd activity_end 7; // 仅自动 VAD 关闭时 }同时realtimeInput也支持视频帧与实时文本# 视频帧1 fps 采样JPEG/PNG/WebP 单帧 await session.send_realtime_input(mediaBlob(datajpeg_frame, mime_typeimage/jpeg)) # 实时文本 await session.send_realtime_input(text切换为更平静的语气。)仓库文档特别提醒视频在 Live API 中不是编码容器mp4/webm而是客户端按约 1 fps 采样后逐帧发送的内联图片。五、realtimeInput 与 clientContent两种输入通道的选择从 client_server_messages.md 的完整对照表可以清晰看到两种输入方式的定位差异维度realtimeInput实时输入clientContent添加上下文目标持续流式传输麦克风/摄像头数据向对话追加一个离散轮次延迟尽可能低亚秒级普通请求/响应延迟是否写入历史否瞬时信号是持久对话轮次边界服务端 VAD或显式activityStart/activityEnd显式turnComplete: true对模型的影响流式送入VAD 触发时自动开始一轮turnComplete: true立即触发生成并打断正在进行的模型输出典型用途实时语音 屏幕共享、按键说话打字聊天、上传图片/片段、恢复时回放历史两条重要规则同一逻辑轮次内两种方式二选一不要混用clientContent会打断正在进行的生成允许在同一会话内交替使用——例如先发一条clientContent系统提示再持续流式发送realtimeInput。SDK 层面session.send_client_content(...)对应clientContent帧session.send_realtime_input(...)对应realtimeInput帧session.receive()消费服务端帧。六、底层线协议ClientMessage / ServerMessageLive API 的每条 WebSocket 帧都是JSON 序列化的 protobuf 消息要么是ClientMessage客户端→服务端要么是ServerMessage服务端→客户端。两者都是oneof 信封——每帧恰好设置一个字段。proto 定义见 client_server_messages.proto。ClientMessage客户端 → 服务端字段类型使用时机setupBidiGenerateContentSetup仅第一帧。配置会话clientContentBidiGenerateContentClientContent追加对话历史回合制输入会打断模型realtimeInputBidiGenerateContentRealtimeInput连续低延迟音频/视频/文本输入不入历史toolResponseBidiGenerateContentToolResponse回复服务端发出的toolCallServerMessage服务端 → 客户端字段类型含义setupCompleteBidiGenerateContentSetupCompletesetup被接受后发送一次。后续发送必须以收到它为门槛serverContentBidiGenerateContentServerContent流式模型输出音频/文本与轮次生命周期toolCallBidiGenerateContentToolCall模型请求执行工具toolCallCancellationBidiGenerateContentToolCallCancellation取消之前发出的工具调用如用户打断usageMetadataUsageMetadataToken / 时长统计goAwayGoAway连接即将终止sessionResumptionUpdateSessionResumptionUpdate供重连使用的恢复句柄音频转写transcription不是独立帧而是内嵌在serverContent中inputTranscription/outputTranscription字段。会话生命周期Client Server │ │ ├── ClientMessage{ setup } ──────────► │ │ │ │ ◄────── ServerMessage{ setupComplete } │ │ ├── realtimeInput / clientContent ────► │ │ (audio frames, text, etc.) │ │ │ │ ◄────── serverContent (audio chunks, modelTurn parts ...) │ ◄────── serverContent { generationComplete: true } │ ◄────── serverContent { turnComplete: true } │ │ │ ◄────── toolCall { functionCalls[] } ├── toolResponse { functionResponses[] } ► │ │ │ │ ◄────── serverContent ... │ ◄────── goAway { timeLeft } (eventually) │ │ │ (close reconnect using sessionResumptionUpdate.newHandle)生命周期规则来自 client_server_messages.md第一帧必须是setup在收到setupComplete之前不要发送任何其他帧回合制、影响历史的输入用clientContent发送它会打断当前生成连续音频/视频用realtimeInput不入历史轮次边界由 VAD 或显式活动事件决定回复toolCall必须用toolResponse绝不能用clientContent收到goAway后使用最近的sessionResumptionUpdate.newHandle重连。连接端点后端WebSocket URIGemini Enterprise Agent Platform区域wss://{LOCATION}-aiplatform.googleapis.com/ws/google.cloud.aiplatform.v1beta1.LlmBidiService/BidiGenerateContentGemini Enterprise Agent Platform全局wss://aiplatform.googleapis.com/ws/google.cloud.aiplatform.v1beta1.LlmBidiService/BidiGenerateContent认证方式为请求头Authorization: Bearer ADC tokenExpress Mode 下使用 API Key。这一点也在 gemini-live-api 的校验清单中强调不要在查询字符串中用 API Key 认证也不要指向generativelanguage.googleapis.com。七、setup 配置详解setup帧proto 类型BidiGenerateContentSetup是会话的唯一一次初始化配置。字段如下见 client_server_messages.md 第 4 节字段类型说明modelstring必填projects/{p}/locations/{l}/publishers/google/models/{m}generationConfigGenerationConfig注意 Live 下不支持responseLogprobs、responseMimeType、logprobs、responseSchema、stopSequence、routingConfig、audioTimestampsystemInstructionContent仅文本 partstools[]repeatedTool函数声明与内建工具Search、代码执行sessionResumptionSessionResumptionConfig{ handle?, transparent? }提供handle表示恢复省略则开启新的可恢复会话contextWindowCompressionContextWindowCompressionConfig{ triggerTokens?, slidingWindow? }realtimeInputConfigRealtimeInputConfig见下方 VAD 说明inputAudioTranscriptionAudioTranscriptionConfig{}开启用户语音输入转写outputAudioTranscriptionAudioTranscriptionConfig{}开启模型语音输出转写一个完整的 setup JSON 示例仓库文档原样提供{ setup: { model: projects/my-proj/locations/us-central1/publishers/google/models/gemini-2.0-flash-live-preview-04-09, generationConfig: { responseModalities: [AUDIO], speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: Aoede } } } }, systemInstruction: { parts: [{ text: You are a concise voice assistant. }] }, realtimeInputConfig: { automaticActivityDetection: { disabled: false } }, sessionResumption: {}, outputAudioTranscription: {} } }generationConfig 的 Live 子集字段类型说明responseModalities[]repeated enumTEXT或AUDIO。每个会话只选一个不支持混用默认AUDIOtemperaturefloat0.0–2.0topP/topK/maxOutputTokens各种标准采样与长度控制speechConfigSpeechConfig声音/语言仅在responseModalities[AUDIO]时生效mediaResolutionenumMEDIA_RESOLUTION_LOW/MEDIUM/HIGH控制输入图像/视频帧的 token 成本与质量权衡thinkingConfigThinkingConfig{ thinkingBudget?: int }仅在支持思考的模型上生效设为 0 可禁用在 SDKPython中这些配置通过types.LiveConnectConfig传入其中response_modalities[types.LiveModality.AUDIO]即对应上述responseModalities[AUDIO]。声音与语言配置SpeechConfigLive API 是单说话人single-speaker输出支持30 个预置声音名称区分大小写Voice风格Voice风格Voice风格ZephyrBrightPuckUpbeatCharonInformativeKoreFirmFenrirExcitableLedaYouthfulOrusFirmAoedeBreezyCallirrhoeEasy-goingAutonoeBrightEnceladusBreathyIapetusClearUmbrielEasy-goingAlgiebaSmoothDespinaSmoothErinomeClearAlgenibGravellyRasalgethiInformativeLaomedeiaUpbeatAchernarSoftAlnilamFirmSchedarEvenGacruxMaturePulcherrimaForwardAchirdFriendlyZubenelgenubiCasualVindemiatrixGentleSadachbiaLivelySadaltagerKnowledgeableSulafatWarm支持24 种 BCP-47 输出语言ar-EG、bn-BD、de-DE、en-IN与hi-IN捆绑、en-US、es-US、fr-FR、hi-IN、id-ID、it-IT、ja-JP、ko-KR、mr-IN、nl-NL、pl-PL、pt-BR、ro-RO、ru-RU、ta-IN、te-IN、th-TH、tr-TR、uk-UA、vi-VN。[!WARNING]voiceName大小写敏感且随模型而异。如果 setup 中被拒绝WebSocket 会直接关闭而不是返回setupComplete。speechConfig在responseModalities[TEXT]时会被静默忽略。语音配置示例固定为德语、Charon 声音{ setup: { model: ..., generationConfig: { responseModalities: [AUDIO], speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: Charon } }, languageCode: de-DE } } } }VAD语音活动检测配置realtimeInputConfig.automaticActivityDetection控制服务端 VAD未设置服务端 VAD 默认启用disabled: true客户端必须自行发送activityStart/activityEnd划定轮次startOfSpeechSensitivitySTART_SENSITIVITY_HIGH/LOWendOfSpeechSensitivityEND_SENSITIVITY_HIGH/LOWprefixPaddingMs提交语音起始所需的最短语音时长silenceDurationMs提交语音结束所需的最短静音时长。手动 VAD 的帧序列示例{ realtimeInput: { activityStart: {} } } { realtimeInput: { audio: { mimeType: audio/pcm;rate16000, data: ... } } } { realtimeInput: { audio: { mimeType: audio/pcm;rate16000, data: ... } } } { realtimeInput: { activityEnd: {} } }八、多模态输入完整示例实时音频 视频 文本对着屏幕说话场景每种模态以独立帧发送{ realtimeInput: { video: { mimeType: image/jpeg, data: frame_t0 } } } { realtimeInput: { audio: { mimeType: audio/pcm;rate16000, data: pcm_t0 } } } { realtimeInput: { video: { mimeType: image/jpeg, data: frame_t1 } } } { realtimeInput: { audio: { mimeType: audio/pcm;rate16000, data: pcm_t1 } } } { realtimeInput: { text: Focus on the chart in the upper-right. } } { realtimeInput: { audio: { mimeType: audio/pcm;rate16000, data: pcm_t2 } } } { realtimeInput: { audioStreamEnd: true } }回合制多模态clientContent追加一条携带文本 图片 音频的完整用户轮次{ clientContent: { turns: [{ role: user, parts: [ { text: Compare what Im saying with what Im showing: }, { inlineData: { mimeType: image/jpeg, data: image } }, { inlineData: { mimeType: audio/pcm;rate16000, data: clip } } ] }], turnComplete: true } }clientContent也支持多轮历史回放如断线恢复后重建上下文turns[]按旧→新排序role取user或model{ clientContent: { turns: [ { role: user, parts: [{ text: Hi, my name is Sam. }] }, { role: model, parts: [{ text: Nice to meet you, Sam! }] }, { role: user, parts: [{ text: Whats my name? }] } ], turnComplete: true } }远程文件GCS URI也可通过fileData引用{ clientContent: { turns: [{ role: user, parts: [ { text: Describe this image. }, { fileData: { mimeType: image/jpeg, fileUri: gs://my-bucket/cat.jpg } } ] }], turnComplete: true } }服务端输出与打断处理服务端以serverContent流式返回模型输出{ serverContent: { modelTurn: { role: model, parts: [{ inlineData: { mimeType: audio/pcm;rate24000, data: base64-pcm-bytes } }] } } }serverContent关键字段字段含义modelTurn流式模型输出 parts文本和/或inlineData音频generationComplete模型已结束生成播放可能仍在冲刷turnComplete轮次逻辑结束interrupted生成被客户端输入打断——丢弃排队中的音频播放groundingMetadata使用 grounding如 Google Search时的元数据inputTranscription用户语音输入转写需在 setup 中开启inputAudioTranscriptionoutputTranscription模型语音输出转写需在 setup 中开启outputAudioTranscription播放注意音频块到达modelTurn.parts[].inlineData24 kHz PCM边到达边拼接一旦收到interrupted: true必须冲刷播放队列否则残留音频会盖过用户下一次说话。工具调用toolCall / toolResponse服务端发起工具调用{ toolCall: { functionCalls: [ { id: call_42, name: get_weather, args: { city: Paris } } ] } }客户端必须用toolResponse回复id 必须匹配否则请求被拒{ toolResponse: { functionResponses: [ { id: call_42, name: get_weather, response: { tempC: 18, summary: Partly cloudy } } ] } }若用户中途打断导致模型取消工具调用服务端会发送toolCallCancellation含ids[]客户端应停止相应工作且不再为这些 id 发送toolResponse。九、会话恢复Session ResumptionLive API 会话有最大时长限制服务端可能随时以goAway通知终止。仓库专门提供了 session_manager.md 指导实现健壮的会话管理器核心逻辑如下1. 开启透明会话恢复在初始setup的session_resumption中设置transparent: true{ setup: { model: ..., sessionResumption: { transparent: true } } }只有开启transparent服务端才会在SessionResumptionUpdate中返回lastConsumedClientMessageIndex用于更新发送缓冲区。2. 监听会话句柄更新服务端随时可能下发sessionResumptionUpdate{ goAway: { timeLeft: 10s } } { sessionResumptionUpdate: { newHandle: ses_xyz, resumable: true } }resumable为 true 且提供了new_handle时保存该句柄该句柄是重连到同一会话的凭证。3. 消息缓冲与剪枝用户消息索引必须从 1 开始——服务端将索引 0 保留给初始配置消息之后每发送一条消息索引 1使用服务端返回的last_consumed_client_message_index从缓冲区删除已被确认的消息每次重连后新连接上发送的第一条消息索引重置为 1这一点至关重要。4. 断线处理主动重连收到goAway后使用最新句柄主动重连错误处理发送与接收循环中捕获 WebSocket 错误码1000 / 1006触发重连流程意外错误其他错误应停止会话管理器并立刻抛出后续 send/receive 调用以停止原因抛异常重连失败重连过程本身也可能失败应实现带指数退避的重试或优雅降级。5. 重连与消息重放建立新 WebSocket 连接并携带已存储的会话句柄{ setup: { model: ..., sessionResumption: { handle: ses_xyz } } }在收发任何其他消息之前先重放缓冲区中剩余的所有消息重放期间不要修改缓冲区因为可能再次断连需要重试新连接上重放的第一条消息索引必须标记为1。常见坑Gotchas索引 0 禁令用户消息绝不使用索引 0并发循环即使发送循环空闲接收循环也必须能检测断连并触发重连反之亦然句柄过期会话句柄可能过期若用过期句柄重连失败应优雅地开启一个全新会话。十、语音转写与打断的前端处理来自 gemini-live-api 技能gemini-live-api 技能在生成演示前端时对转写与打断提出了明确的行为规范这些规范同样适用于任何 Live API 客户端实现打断interrupted: true时立即停止当前正在播放的模型音频停止向进行中的转写气泡追加内容清空未播放的音频缓冲与未渲染的转写防止残留内容泄漏到下一轮为下一个用户轮次与模型轮次新建对话气泡保证已播放音频与其对应转写保持时间对齐。转写finished信号流式input_transcription/output_transcription分片在finished未置位时持续追加到当前气泡观察到finished时关闭当前气泡并开启新气泡input_transcription文本归入 user 角色气泡output_transcription文本归入 model 角色气泡。在 protoclient_server_messages.proto中转写消息带有finished布尔字段message Transcription { string text 1; bool finished 2; }十一、常见问题与避坑清单综合 live_api.md 与 client_server_messages.md 的常见陷阱汇总如下在setupComplete之前发送数据——服务端会直接关闭连接同一逻辑轮次混用clientContent与realtimeInput——二选一clientContent会打断正在进行的生成忽略interrupted: true——残留排队音频会盖过用户下一次说话用clientContent回复toolCall——必须用toolResponse遗漏FunctionResponse.id——请求会被拒绝音频格式错误——输入必须是 16 kHz PCM输出是 24 kHz PCM不处理重连——会话有时长上限必须尊重goAway并持久化最新SessionResumptionUpdate.newHandle用旧 SDK 或 API Key 走查询字符串认证——应使用 Gen AI SDK ADC Bearer Tokengemini-live-api 校验清单明确禁止指向generativelanguage.googleapis.com。十二、仓库配套资源导航gemini-apiGemini API 总技能包含模型清单、认证配置、各语言 SDK 快速开始live_api.md本指南的核心文档Live API 最小示例与音频发送示例text_and_multimodal.md文本生成、多轮对话、同步流式与多模态输入的对照参考advanced_features.md上下文缓存、批量预测、Thinking 配置与 MCP 支持等进阶能力gemini-live-api生成 LiveAPI 客户端服务类与演示前端的完整技能包含会话恢复、Bearer Token 刷新等工程化要求client_server_messages.mdLive API WebSocket 线协议的权威参考连接端点、帧结构、生命周期、setup 全字段、多模态输入示例与常见陷阱client_server_messages.proto上述线协议的 proto3 定义是自行实现客户端时生成代码的基础session_manager.md透明会话恢复与断线重连的完整实现指引。结语从 references/live_api.md 的最小示例出发结合本仓库沉淀的线协议与会话管理文档可以看到 Gemini Live API 的完整技术画像SDK 层的LiveConnectConfigaio.live.connect封装了 WebSocket 连接的复杂性send_client_content与send_realtime_input分别对应历史性回合与低延迟实时流两种输入通道setup中的responseModalities、speechConfig、VAD 与转写配置决定了语音交互的行为边界而goAwaysessionResumptionUpdate 消息缓冲重放构成了生产环境必备的断线恢复能力。对于任何要构建实时语音助手、屏幕共享讲解或多模态交互应用的开发者这套SDK 快速上手 协议级深度理解的组合即是完整的工程路线图。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/13 17:25:13 · 阅读 1.2k Gemini Live API 实战指南：基于 Agent Skills 仓库的实时双向流式交互开发
Gemini Live API 实战指南基于 Agent Skills 仓库的实时双向流式交互开发【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本指南以 skills/cloud/gemini-api/references/live_api.md 为核心骨架结合本仓库 gemini-live-api 技能中的 WebSocket 线协议文档与 proto 定义进行深度展开。读者将掌握如何用 Google Gen AI SDKPython建立 Live API 会话、配置LiveConnectConfig、发送文本与实时音频/视频输入、理解ClientMessage/ServerMessage双向消息协议、以及如何实现会话恢复与语音/转写处理最终构建出低延迟的交互式语音与视频应用。一、Live API 是什么Gemini Live API 是 Gemini API 面向实时交互场景的能力分支。与一次性请求/响应的generate_content不同Live API 通过WebSocket 提供实时、低延迟的双向流式传输bidirectional streaming专门服务于交互式语音和视频应用——例如语音助手、实时口译、屏幕共享讲解、人机多轮对话等。在本仓库中Live API 属于 gemini-api 技能所覆盖的核心能力之一该技能同时覆盖文本生成、多模态理解、函数调用、结构化输出、上下文缓存、Embeddings、批量预测等仓库还为 Live API 单独提供了 gemini-live-api 技能用于生成一个完整的 LiveAPI 客户端服务类其中包含会话建立/恢复、Bearer Token 刷新、ClientMessage/ServerMessageproto 收发等能力。本指南聚焦直接用 SDK 上手 Live API并向下延伸到仓库中沉淀的底层协议细节。核心特点一览实时双向客户端与服务端通过 WebSocket 同时收发消息延迟低至亚秒级多模态输入支持连续音频流PCM、视频帧JPEG/PNG/WebP与文本流流式输出模型以音频块24 kHz PCM和/或文本流式返回支持中途打断会话恢复支持透明会话恢复transparent session resumption断线自动重连不丢上下文。二、环境准备与 SDK 选型根据 gemini-api 的说明Live API 统一使用Gen AI SDKPythonpip install google-genaiJavaScript/TypeScriptgoogle/genaiGogoogle.golang.org/genaiJavacom.google.genai:google-genaiC#/.NETGoogle.GenAI[!IMPORTANT] 不要使用google-cloud-aiplatform、google-cloud/vertexai、google-generativeai等旧版 SDK仓库明确标注其为已弃用deprecated方案。认证上推荐使用环境变量 应用默认凭据ADC初始化客户端时不传参即可自动拾取export GOOGLE_CLOUD_PROJECTyour-project-id export GOOGLE_CLOUD_LOCATIONglobal export GOOGLE_GENAI_USE_ENTERPRISEtrue若使用 Express ModeAPI Key则设置export GOOGLE_API_KEYyour-api-key export GOOGLE_GENAI_USE_ENTERPRISEtrueLive API 专用模型仓库 gemini-api 中明确列出Live Realtime API含原生音频应使用gemini-live-2.5-flash-native-audio该模型支持原生音频输入输出可在对话中自动切换语言对于非原生音频模型则需要在speechConfig.languageCode中显式指定输出语言。三、最小可运行示例Python 文本会话references/live_api.md 给出的第一个完整示例即是一个文本模式的 Live 会话import asyncio from google import genai from google.genai import types async def generate_content(): client genai.Client() model_id gemini-live-2.5-flash-native-audio config types.LiveConnectConfig( response_modalities[types.LiveModality.TEXT], # Change to AUDIO for voice responses ) async with client.aio.live.connect(modelmodel_id, configconfig) as session: text_input Hello? Gemini, are you there? await session.send_client_content( turnstypes.Content(roleuser, parts[types.Part.from_text(texttext_input)]) ) async for message in session.receive(): if message.text: print(message.text, end) asyncio.run(generate_content())逐段拆解代码片段作用genai.Client()创建客户端自动读取环境变量中的项目、区域与企业模式配置types.LiveConnectConfig(response_modalities[...])声明会话的响应模态。TEXT为纯文本回复改为AUDIO则返回语音client.aio.live.connect(...)异步上下文管理器负责建立 WebSocket 连接并在退出时关闭会话session.send_client_content(...)发送回合制turn-based内容写入对话历史并触发生成session.receive()异步迭代服务端消息流message.text提取文本片段[!NOTE]client.aio是 SDK 的异步入口send_client_content发送的消息会进入对话历史属于clientContent帧与后面要讲的send_realtime_input实时流不入历史是两种不同的输入通道。四、发送实时音频send_realtime_input在语音应用场景中麦克风采集的音频需要以连续流的方式送入模型。原文档给出了核心用法await session.send_realtime_input( mediaBlob(dataaudio_bytes, mime_typeaudio/pcm;rate16000) )结合仓库中的线协议文档 client_server_messages.md 与 client_server_messages.protorealtimeInput帧的关键约束如下输入音频格式PCM16-bit 有符号16 kHz 采样率单声道小端序base64 编码MIME 类型为audio/pcm;rate16000输出音频格式24 kHz16-bit 有符号 PCM单声道服务端下发的modelTurn.parts[].inlineData中mimeType 为audio/pcm;rate24000不入历史realtimeInput不会写入对话历史属于瞬时信号轮次边界默认由**服务端 VAD语音活动检测**决定若在setup中关闭自动 VAD则需自行发送activityStart/activityEnd逐块发送以约 20–100 ms 为一帧逐个发送麦克风关闭在自动 VAD 开启时麦克风关闭应发送{ realtimeInput: { audioStreamEnd: true } }提交流结束。对应 proto见 client_server_messages.proto 中BidiGenerateContentRealtimeInputmessage BidiGenerateContentRealtimeInput { repeated Blob media_chunks 1 [deprecated true]; // 已弃用 Blob audio 2; // PCM 16-bit, 16 kHz mono Blob video 3; // image/jpeg|png|webp string text 4; bool audio_stream_end 5; ActivityStart activity_start 6; // 仅自动 VAD 关闭时 ActivityEnd activity_end 7; // 仅自动 VAD 关闭时 }同时realtimeInput也支持视频帧与实时文本# 视频帧1 fps 采样JPEG/PNG/WebP 单帧 await session.send_realtime_input(mediaBlob(datajpeg_frame, mime_typeimage/jpeg)) # 实时文本 await session.send_realtime_input(text切换为更平静的语气。)仓库文档特别提醒视频在 Live API 中不是编码容器mp4/webm而是客户端按约 1 fps 采样后逐帧发送的内联图片。五、realtimeInput 与 clientContent两种输入通道的选择从 client_server_messages.md 的完整对照表可以清晰看到两种输入方式的定位差异维度realtimeInput实时输入clientContent添加上下文目标持续流式传输麦克风/摄像头数据向对话追加一个离散轮次延迟尽可能低亚秒级普通请求/响应延迟是否写入历史否瞬时信号是持久对话轮次边界服务端 VAD或显式activityStart/activityEnd显式turnComplete: true对模型的影响流式送入VAD 触发时自动开始一轮turnComplete: true立即触发生成并打断正在进行的模型输出典型用途实时语音 屏幕共享、按键说话打字聊天、上传图片/片段、恢复时回放历史两条重要规则同一逻辑轮次内两种方式二选一不要混用clientContent会打断正在进行的生成允许在同一会话内交替使用——例如先发一条clientContent系统提示再持续流式发送realtimeInput。SDK 层面session.send_client_content(...)对应clientContent帧session.send_realtime_input(...)对应realtimeInput帧session.receive()消费服务端帧。六、底层线协议ClientMessage / ServerMessageLive API 的每条 WebSocket 帧都是JSON 序列化的 protobuf 消息要么是ClientMessage客户端→服务端要么是ServerMessage服务端→客户端。两者都是oneof 信封——每帧恰好设置一个字段。proto 定义见 client_server_messages.proto。ClientMessage客户端 → 服务端字段类型使用时机setupBidiGenerateContentSetup仅第一帧。配置会话clientContentBidiGenerateContentClientContent追加对话历史回合制输入会打断模型realtimeInputBidiGenerateContentRealtimeInput连续低延迟音频/视频/文本输入不入历史toolResponseBidiGenerateContentToolResponse回复服务端发出的toolCallServerMessage服务端 → 客户端字段类型含义setupCompleteBidiGenerateContentSetupCompletesetup被接受后发送一次。后续发送必须以收到它为门槛serverContentBidiGenerateContentServerContent流式模型输出音频/文本与轮次生命周期toolCallBidiGenerateContentToolCall模型请求执行工具toolCallCancellationBidiGenerateContentToolCallCancellation取消之前发出的工具调用如用户打断usageMetadataUsageMetadataToken / 时长统计goAwayGoAway连接即将终止sessionResumptionUpdateSessionResumptionUpdate供重连使用的恢复句柄音频转写transcription不是独立帧而是内嵌在serverContent中inputTranscription/outputTranscription字段。会话生命周期Client Server │ │ ├── ClientMessage{ setup } ──────────► │ │ │ │ ◄────── ServerMessage{ setupComplete } │ │ ├── realtimeInput / clientContent ────► │ │ (audio frames, text, etc.) │ │ │ │ ◄────── serverContent (audio chunks, modelTurn parts ...) │ ◄────── serverContent { generationComplete: true } │ ◄────── serverContent { turnComplete: true } │ │ │ ◄────── toolCall { functionCalls[] } ├── toolResponse { functionResponses[] } ► │ │ │ │ ◄────── serverContent ... │ ◄────── goAway { timeLeft } (eventually) │ │ │ (close reconnect using sessionResumptionUpdate.newHandle)生命周期规则来自 client_server_messages.md第一帧必须是setup在收到setupComplete之前不要发送任何其他帧回合制、影响历史的输入用clientContent发送它会打断当前生成连续音频/视频用realtimeInput不入历史轮次边界由 VAD 或显式活动事件决定回复toolCall必须用toolResponse绝不能用clientContent收到goAway后使用最近的sessionResumptionUpdate.newHandle重连。连接端点后端WebSocket URIGemini Enterprise Agent Platform区域wss://{LOCATION}-aiplatform.googleapis.com/ws/google.cloud.aiplatform.v1beta1.LlmBidiService/BidiGenerateContentGemini Enterprise Agent Platform全局wss://aiplatform.googleapis.com/ws/google.cloud.aiplatform.v1beta1.LlmBidiService/BidiGenerateContent认证方式为请求头Authorization: Bearer ADC tokenExpress Mode 下使用 API Key。这一点也在 gemini-live-api 的校验清单中强调不要在查询字符串中用 API Key 认证也不要指向generativelanguage.googleapis.com。七、setup 配置详解setup帧proto 类型BidiGenerateContentSetup是会话的唯一一次初始化配置。字段如下见 client_server_messages.md 第 4 节字段类型说明modelstring必填projects/{p}/locations/{l}/publishers/google/models/{m}generationConfigGenerationConfig注意 Live 下不支持responseLogprobs、responseMimeType、logprobs、responseSchema、stopSequence、routingConfig、audioTimestampsystemInstructionContent仅文本 partstools[]repeatedTool函数声明与内建工具Search、代码执行sessionResumptionSessionResumptionConfig{ handle?, transparent? }提供handle表示恢复省略则开启新的可恢复会话contextWindowCompressionContextWindowCompressionConfig{ triggerTokens?, slidingWindow? }realtimeInputConfigRealtimeInputConfig见下方 VAD 说明inputAudioTranscriptionAudioTranscriptionConfig{}开启用户语音输入转写outputAudioTranscriptionAudioTranscriptionConfig{}开启模型语音输出转写一个完整的 setup JSON 示例仓库文档原样提供{ setup: { model: projects/my-proj/locations/us-central1/publishers/google/models/gemini-2.0-flash-live-preview-04-09, generationConfig: { responseModalities: [AUDIO], speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: Aoede } } } }, systemInstruction: { parts: [{ text: You are a concise voice assistant. }] }, realtimeInputConfig: { automaticActivityDetection: { disabled: false } }, sessionResumption: {}, outputAudioTranscription: {} } }generationConfig 的 Live 子集字段类型说明responseModalities[]repeated enumTEXT或AUDIO。每个会话只选一个不支持混用默认AUDIOtemperaturefloat0.0–2.0topP/topK/maxOutputTokens各种标准采样与长度控制speechConfigSpeechConfig声音/语言仅在responseModalities[AUDIO]时生效mediaResolutionenumMEDIA_RESOLUTION_LOW/MEDIUM/HIGH控制输入图像/视频帧的 token 成本与质量权衡thinkingConfigThinkingConfig{ thinkingBudget?: int }仅在支持思考的模型上生效设为 0 可禁用在 SDKPython中这些配置通过types.LiveConnectConfig传入其中response_modalities[types.LiveModality.AUDIO]即对应上述responseModalities[AUDIO]。声音与语言配置SpeechConfigLive API 是单说话人single-speaker输出支持30 个预置声音名称区分大小写Voice风格Voice风格Voice风格ZephyrBrightPuckUpbeatCharonInformativeKoreFirmFenrirExcitableLedaYouthfulOrusFirmAoedeBreezyCallirrhoeEasy-goingAutonoeBrightEnceladusBreathyIapetusClearUmbrielEasy-goingAlgiebaSmoothDespinaSmoothErinomeClearAlgenibGravellyRasalgethiInformativeLaomedeiaUpbeatAchernarSoftAlnilamFirmSchedarEvenGacruxMaturePulcherrimaForwardAchirdFriendlyZubenelgenubiCasualVindemiatrixGentleSadachbiaLivelySadaltagerKnowledgeableSulafatWarm支持24 种 BCP-47 输出语言ar-EG、bn-BD、de-DE、en-IN与hi-IN捆绑、en-US、es-US、fr-FR、hi-IN、id-ID、it-IT、ja-JP、ko-KR、mr-IN、nl-NL、pl-PL、pt-BR、ro-RO、ru-RU、ta-IN、te-IN、th-TH、tr-TR、uk-UA、vi-VN。[!WARNING]voiceName大小写敏感且随模型而异。如果 setup 中被拒绝WebSocket 会直接关闭而不是返回setupComplete。speechConfig在responseModalities[TEXT]时会被静默忽略。语音配置示例固定为德语、Charon 声音{ setup: { model: ..., generationConfig: { responseModalities: [AUDIO], speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: Charon } }, languageCode: de-DE } } } }VAD语音活动检测配置realtimeInputConfig.automaticActivityDetection控制服务端 VAD未设置服务端 VAD 默认启用disabled: true客户端必须自行发送activityStart/activityEnd划定轮次startOfSpeechSensitivitySTART_SENSITIVITY_HIGH/LOWendOfSpeechSensitivityEND_SENSITIVITY_HIGH/LOWprefixPaddingMs提交语音起始所需的最短语音时长silenceDurationMs提交语音结束所需的最短静音时长。手动 VAD 的帧序列示例{ realtimeInput: { activityStart: {} } } { realtimeInput: { audio: { mimeType: audio/pcm;rate16000, data: ... } } } { realtimeInput: { audio: { mimeType: audio/pcm;rate16000, data: ... } } } { realtimeInput: { activityEnd: {} } }八、多模态输入完整示例实时音频 视频 文本对着屏幕说话场景每种模态以独立帧发送{ realtimeInput: { video: { mimeType: image/jpeg, data: frame_t0 } } } { realtimeInput: { audio: { mimeType: audio/pcm;rate16000, data: pcm_t0 } } } { realtimeInput: { video: { mimeType: image/jpeg, data: frame_t1 } } } { realtimeInput: { audio: { mimeType: audio/pcm;rate16000, data: pcm_t1 } } } { realtimeInput: { text: Focus on the chart in the upper-right. } } { realtimeInput: { audio: { mimeType: audio/pcm;rate16000, data: pcm_t2 } } } { realtimeInput: { audioStreamEnd: true } }回合制多模态clientContent追加一条携带文本 图片 音频的完整用户轮次{ clientContent: { turns: [{ role: user, parts: [ { text: Compare what Im saying with what Im showing: }, { inlineData: { mimeType: image/jpeg, data: image } }, { inlineData: { mimeType: audio/pcm;rate16000, data: clip } } ] }], turnComplete: true } }clientContent也支持多轮历史回放如断线恢复后重建上下文turns[]按旧→新排序role取user或model{ clientContent: { turns: [ { role: user, parts: [{ text: Hi, my name is Sam. }] }, { role: model, parts: [{ text: Nice to meet you, Sam! }] }, { role: user, parts: [{ text: Whats my name? }] } ], turnComplete: true } }远程文件GCS URI也可通过fileData引用{ clientContent: { turns: [{ role: user, parts: [ { text: Describe this image. }, { fileData: { mimeType: image/jpeg, fileUri: gs://my-bucket/cat.jpg } } ] }], turnComplete: true } }服务端输出与打断处理服务端以serverContent流式返回模型输出{ serverContent: { modelTurn: { role: model, parts: [{ inlineData: { mimeType: audio/pcm;rate24000, data: base64-pcm-bytes } }] } } }serverContent关键字段字段含义modelTurn流式模型输出 parts文本和/或inlineData音频generationComplete模型已结束生成播放可能仍在冲刷turnComplete轮次逻辑结束interrupted生成被客户端输入打断——丢弃排队中的音频播放groundingMetadata使用 grounding如 Google Search时的元数据inputTranscription用户语音输入转写需在 setup 中开启inputAudioTranscriptionoutputTranscription模型语音输出转写需在 setup 中开启outputAudioTranscription播放注意音频块到达modelTurn.parts[].inlineData24 kHz PCM边到达边拼接一旦收到interrupted: true必须冲刷播放队列否则残留音频会盖过用户下一次说话。工具调用toolCall / toolResponse服务端发起工具调用{ toolCall: { functionCalls: [ { id: call_42, name: get_weather, args: { city: Paris } } ] } }客户端必须用toolResponse回复id 必须匹配否则请求被拒{ toolResponse: { functionResponses: [ { id: call_42, name: get_weather, response: { tempC: 18, summary: Partly cloudy } } ] } }若用户中途打断导致模型取消工具调用服务端会发送toolCallCancellation含ids[]客户端应停止相应工作且不再为这些 id 发送toolResponse。九、会话恢复Session ResumptionLive API 会话有最大时长限制服务端可能随时以goAway通知终止。仓库专门提供了 session_manager.md 指导实现健壮的会话管理器核心逻辑如下1. 开启透明会话恢复在初始setup的session_resumption中设置transparent: true{ setup: { model: ..., sessionResumption: { transparent: true } } }只有开启transparent服务端才会在SessionResumptionUpdate中返回lastConsumedClientMessageIndex用于更新发送缓冲区。2. 监听会话句柄更新服务端随时可能下发sessionResumptionUpdate{ goAway: { timeLeft: 10s } } { sessionResumptionUpdate: { newHandle: ses_xyz, resumable: true } }resumable为 true 且提供了new_handle时保存该句柄该句柄是重连到同一会话的凭证。3. 消息缓冲与剪枝用户消息索引必须从 1 开始——服务端将索引 0 保留给初始配置消息之后每发送一条消息索引 1使用服务端返回的last_consumed_client_message_index从缓冲区删除已被确认的消息每次重连后新连接上发送的第一条消息索引重置为 1这一点至关重要。4. 断线处理主动重连收到goAway后使用最新句柄主动重连错误处理发送与接收循环中捕获 WebSocket 错误码1000 / 1006触发重连流程意外错误其他错误应停止会话管理器并立刻抛出后续 send/receive 调用以停止原因抛异常重连失败重连过程本身也可能失败应实现带指数退避的重试或优雅降级。5. 重连与消息重放建立新 WebSocket 连接并携带已存储的会话句柄{ setup: { model: ..., sessionResumption: { handle: ses_xyz } } }在收发任何其他消息之前先重放缓冲区中剩余的所有消息重放期间不要修改缓冲区因为可能再次断连需要重试新连接上重放的第一条消息索引必须标记为1。常见坑Gotchas索引 0 禁令用户消息绝不使用索引 0并发循环即使发送循环空闲接收循环也必须能检测断连并触发重连反之亦然句柄过期会话句柄可能过期若用过期句柄重连失败应优雅地开启一个全新会话。十、语音转写与打断的前端处理来自 gemini-live-api 技能gemini-live-api 技能在生成演示前端时对转写与打断提出了明确的行为规范这些规范同样适用于任何 Live API 客户端实现打断interrupted: true时立即停止当前正在播放的模型音频停止向进行中的转写气泡追加内容清空未播放的音频缓冲与未渲染的转写防止残留内容泄漏到下一轮为下一个用户轮次与模型轮次新建对话气泡保证已播放音频与其对应转写保持时间对齐。转写finished信号流式input_transcription/output_transcription分片在finished未置位时持续追加到当前气泡观察到finished时关闭当前气泡并开启新气泡input_transcription文本归入 user 角色气泡output_transcription文本归入 model 角色气泡。在 protoclient_server_messages.proto中转写消息带有finished布尔字段message Transcription { string text 1; bool finished 2; }十一、常见问题与避坑清单综合 live_api.md 与 client_server_messages.md 的常见陷阱汇总如下在setupComplete之前发送数据——服务端会直接关闭连接同一逻辑轮次混用clientContent与realtimeInput——二选一clientContent会打断正在进行的生成忽略interrupted: true——残留排队音频会盖过用户下一次说话用clientContent回复toolCall——必须用toolResponse遗漏FunctionResponse.id——请求会被拒绝音频格式错误——输入必须是 16 kHz PCM输出是 24 kHz PCM不处理重连——会话有时长上限必须尊重goAway并持久化最新SessionResumptionUpdate.newHandle用旧 SDK 或 API Key 走查询字符串认证——应使用 Gen AI SDK ADC Bearer Tokengemini-live-api 校验清单明确禁止指向generativelanguage.googleapis.com。十二、仓库配套资源导航gemini-apiGemini API 总技能包含模型清单、认证配置、各语言 SDK 快速开始live_api.md本指南的核心文档Live API 最小示例与音频发送示例text_and_multimodal.md文本生成、多轮对话、同步流式与多模态输入的对照参考advanced_features.md上下文缓存、批量预测、Thinking 配置与 MCP 支持等进阶能力gemini-live-api生成 LiveAPI 客户端服务类与演示前端的完整技能包含会话恢复、Bearer Token 刷新等工程化要求client_server_messages.mdLive API WebSocket 线协议的权威参考连接端点、帧结构、生命周期、setup 全字段、多模态输入示例与常见陷阱client_server_messages.proto上述线协议的 proto3 定义是自行实现客户端时生成代码的基础session_manager.md透明会话恢复与断线重连的完整实现指引。结语从 references/live_api.md 的最小示例出发结合本仓库沉淀的线协议与会话管理文档可以看到 Gemini Live API 的完整技术画像SDK 层的LiveConnectConfigaio.live.connect封装了 WebSocket 连接的复杂性send_client_content与send_realtime_input分别对应历史性回合与低延迟实时流两种输入通道setup中的responseModalities、speechConfig、VAD 与转写配置决定了语音交互的行为边界而goAwaysessionResumptionUpdate 消息缓冲重放构成了生产环境必备的断线恢复能力。对于任何要构建实时语音助手、屏幕共享讲解或多模态交互应用的开发者这套SDK 快速上手 协议级深度理解的组合即是完整的工程路线图。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考