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 SDK（Python）建立 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 SDK：

• Python：pip install google-genai
• JavaScript/TypeScript：@google/genai
• Go：google.golang.org/genai
• Java：com.google.genai:google-genai
• C#/.NET：Google.GenAI

[!IMPORTANT] 不要使用google-cloud-aiplatform、@google-cloud/vertexai、google-generativeai等旧版 SDK，仓库明确标注其为已弃用（deprecated）方案。

认证上，推荐使用环境变量 + 应用默认凭据（ADC），初始化客户端时不传参即可自动拾取：

export GOOGLE_CLOUD_PROJECT='your-project-id' export GOOGLE_CLOUD_LOCATION='global' export GOOGLE_GENAI_USE_ENTERPRISE=true

若使用 Express Mode（API Key），则设置：

export GOOGLE_API_KEY='your-api-key' export GOOGLE_GENAI_USE_ENTERPRISE=true

Live 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(model=model_id, config=config) as session: text_input = "Hello? Gemini, are you there?" await session.send_client_content( turns=types.Content(role="user", parts=[types.Part.from_text(text=text_input)]) ) async for message in session.receive(): if message.text: print(message.text, end="") asyncio.run(generate_content())

逐段拆解：

[!NOTE]client.aio是 SDK 的异步入口；send_client_content发送的消息会进入对话历史，属于clientContent帧，与后面要讲的send_realtime_input（实时流，不入历史）是两种不同的输入通道。

四、发送实时音频：send_realtime_input

在语音应用场景中，麦克风采集的音频需要以连续流的方式送入模型。原文档给出了核心用法：

await session.send_realtime_input( media=Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000") )

结合仓库中的线协议文档 client_server_messages.md 与 client_server_messages.proto，realtimeInput帧的关键约束如下：

• 输入音频格式：PCM，16-bit 有符号，16 kHz 采样率，单声道，小端序，base64 编码；MIME 类型为audio/pcm;rate=16000；
• 输出音频格式：24 kHz，16-bit 有符号 PCM，单声道（服务端下发的modelTurn.parts[].inlineData中，mimeType 为audio/pcm;rate=24000）；
• 不入历史：realtimeInput不会写入对话历史，属于瞬时信号；轮次边界默认由**服务端 VAD（语音活动检测）**决定，若在setup中关闭自动 VAD，则需自行发送activityStart/activityEnd；
• 逐块发送：以约 20–100 ms 为一帧逐个发送；
• 麦克风关闭：在自动 VAD 开启时，麦克风关闭应发送{ "realtimeInput": { "audioStreamEnd": true } }提交流结束。

对应 proto（见 client_server_messages.proto 中BidiGenerateContentRealtimeInput）：

message 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(media=Blob(data=jpeg_frame, mime_type="image/jpeg")) # 实时文本 await session.send_realtime_input(text="切换为更平静的语气。")

仓库文档特别提醒：视频在 Live API 中不是编码容器（mp4/webm），而是客户端按约 1 fps 采样后逐帧发送的内联图片。

五、realtimeInput 与 clientContent：两种输入通道的选择

从 client_server_messages.md 的完整对照表可以清晰看到两种输入方式的定位差异：

两条重要规则：

1. 同一逻辑轮次内，两种方式二选一，不要混用（clientContent会打断正在进行的生成）；
2. 允许在同一会话内交替使用——例如先发一条clientContent系统提示，再持续流式发送realtimeInput。

SDK 层面，session.send_client_content(...)对应clientContent帧，session.send_realtime_input(...)对应realtimeInput帧，session.receive()消费服务端帧。

六、底层线协议：ClientMessage / ServerMessage

Live API 的每条 WebSocket 帧都是JSON 序列化的 protobuf 消息，要么是ClientMessage（客户端→服务端），要么是ServerMessage（服务端→客户端）。两者都是oneof 信封——每帧恰好设置一个字段。proto 定义见 client_server_messages.proto。

ClientMessage（客户端 → 服务端）

ServerMessage（服务端 → 客户端）

音频转写（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）：

1. 第一帧必须是setup；在收到setupComplete之前不要发送任何其他帧；
2. 回合制、影响历史的输入用clientContent（发送它会打断当前生成）；
3. 连续音频/视频用realtimeInput（不入历史，轮次边界由 VAD 或显式活动事件决定）；
4. 回复toolCall必须用toolResponse，绝不能用clientContent；
5. 收到goAway后，使用最近的sessionResumptionUpdate.newHandle重连。

连接端点

认证方式为请求头Authorization: Bearer <ADC token>（Express Mode 下使用 API Key）。这一点也在 gemini-live-api 的校验清单中强调：不要在查询字符串中用 API Key 认证，也不要指向generativelanguage.googleapis.com。

七、setup 配置详解

setup帧（proto 类型BidiGenerateContentSetup）是会话的唯一一次初始化配置。字段如下（见 client_server_messages.md 第 4 节）：

一个完整的 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 子集

在 SDK（Python）中，这些配置通过types.LiveConnectConfig传入，其中response_modalities=[types.LiveModality.AUDIO]即对应上述responseModalities=["AUDIO"]。

声音与语言配置（SpeechConfig）

Live API 是单说话人（single-speaker）输出，支持30 个预置声音（名称区分大小写）：

支持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划定轮次；
• startOfSpeechSensitivity：START_SENSITIVITY_HIGH/LOW；
• endOfSpeechSensitivity：END_SENSITIVITY_HIGH/LOW；
• prefixPaddingMs：提交语音起始所需的最短语音时长；
• silenceDurationMs：提交语音结束所需的最短静音时长。

手动 VAD 的帧序列示例：

{ "realtimeInput": { "activityStart": {} } } { "realtimeInput": { "audio": { "mimeType": "audio/pcm;rate=16000", "data": "..." } } } { "realtimeInput": { "audio": { "mimeType": "audio/pcm;rate=16000", "data": "..." } } } { "realtimeInput": { "activityEnd": {} } }

八、多模态输入完整示例

实时音频 + 视频 + 文本（"对着屏幕说话"场景）

每种模态以独立帧发送：

{ "realtimeInput": { "video": { "mimeType": "image/jpeg", "data": "<frame_t0>" } } } { "realtimeInput": { "audio": { "mimeType": "audio/pcm;rate=16000", "data": "<pcm_t0>" } } } { "realtimeInput": { "video": { "mimeType": "image/jpeg", "data": "<frame_t1>" } } } { "realtimeInput": { "audio": { "mimeType": "audio/pcm;rate=16000", "data": "<pcm_t1>" } } } { "realtimeInput": { "text": "Focus on the chart in the upper-right." } } { "realtimeInput": { "audio": { "mimeType": "audio/pcm;rate=16000", "data": "<pcm_t2>" } } } { "realtimeInput": { "audioStreamEnd": true } }

回合制多模态（clientContent）

追加一条携带文本 + 图片 + 音频的完整用户轮次：

{ "clientContent": { "turns": [{ "role": "user", "parts": [ { "text": "Compare what I'm saying with what I'm showing:" }, { "inlineData": { "mimeType": "image/jpeg", "data": "<image>" } }, { "inlineData": { "mimeType": "audio/pcm;rate=16000", "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": "What's 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;rate=24000", "data": "<base64-pcm-bytes>" } }] } } }

serverContent关键字段：

播放注意：音频块到达modelTurn.parts[].inlineData（24 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 Resumption）

Live 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. 重连与消息重放

1. 建立新 WebSocket 连接并携带已存储的会话句柄：

{ "setup": { "model": "...", "sessionResumption": { "handle": "ses_xyz" } } }

2. 在收发任何其他消息之前，先重放缓冲区中剩余的所有消息；
3. 重放期间不要修改缓冲区（因为可能再次断连需要重试）；
4. 新连接上重放的第一条消息索引必须标记为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 角色气泡。

在 proto（client_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 Token（gemini-live-api 校验清单明确禁止指向generativelanguage.googleapis.com）。

十二、仓库配套资源导航

• gemini-api：Gemini 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.md：Live API WebSocket 线协议的权威参考（连接端点、帧结构、生命周期、setup 全字段、多模态输入示例与常见陷阱）；
• client_server_messages.proto：上述线协议的 proto3 定义，是自行实现客户端时生成代码的基础；
• session_manager.md：透明会话恢复与断线重连的完整实现指引。

结语

从 references/live_api.md 的最小示例出发，结合本仓库沉淀的线协议与会话管理文档，可以看到 Gemini Live API 的完整技术画像：SDK 层的LiveConnectConfig+aio.live.connect封装了 WebSocket 连接的复杂性；send_client_content与send_realtime_input分别对应历史性回合与低延迟实时流两种输入通道；setup中的responseModalities、speechConfig、VAD 与转写配置决定了语音交互的行为边界；而goAway+sessionResumptionUpdate+ 消息缓冲重放构成了生产环境必备的断线恢复能力。对于任何要构建实时语音助手、屏幕共享讲解或多模态交互应用的开发者，这套"SDK 快速上手 + 协议级深度理解"的组合即是完整的工程路线图。

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills