结论先说
- Live API 走有状态 WebSocket 双向流,不再走单次 HTTP 请求:在 Python
google-genaiSDK 中通过异步上下文async with client.aio.live.connect(...)建立长连接,边发麦克风流边收语音包。 - 输入输出采样率不对称是最常见的变声根源:官方要求客户端上传音频为
16-bit PCM、16 kHz、单声道,而服务端下发的语音流固定为24 kHz,播放端若按 16 kHz 播就会明显慢放变粗。 - 原生支持随时打断(VAD),但前端必须配合清空队列:服务端检测到用户开口插话时会中止生成并下发
interrupted标记,客户端收到后必须立刻停播本地尚未播完的音频缓冲块。 - 注意两个硬时间边界:单条 WebSocket 连接约 10 分钟会断开(提前下发
GoAway预警);不开启上下文压缩时,纯语音会话约 15 分钟、音视频混合约 2 分钟就会触及窗口上限,长对话需同时打开context_window_compression与session_resumption。 - 谷歌开发账号与多工具订阅入口:在 Google AI Studio 测试实时流与开通 API 需准备个人谷歌账号,缺号可查看本站 谷歌账号购买说明(含即买即发的 谷歌邮箱成品号),跨平台主力编程会员总览见 AI 会员充值中心。

图:本站根据 Google Gemini API 文档:Session management 整理的示意图
本文根据 Google Gemini API 官方文档《Get started with Live API》《Live API capabilities guide》《Session management》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Google 官方网站。
适用于谁
- 想构建低延迟 AI 口语陪练、智能客服语音通话或实时共享屏幕/摄像头视觉问答应用的开发者;
- 接通了语音流但听起来像倍速变调噪音,或者用户一插话前端还在继续念旧台词的人;
- 遇到通话刚满 2 分钟或 10 分钟就莫名断线,不清楚上下文压缩与会话重连机制的工程团队。
一、最小可用异步连接与音色配置示例
若只想零代码体验官方实时语音画面,可先进入网页工作台试跑(入门见 Google AI Studio 怎么用,若在手机 App 遇到语音不可用见 Gemini 语音对话用不了怎么办)。进入代码开发时,先安装 google-genai(环境准备见 Gemini API Python 调用教程),最小异步文本入、音频出闭环如下:
python
import asyncio
from google import genai
from google.genai import types
client = genai.Client()
MODEL = "gemini-2.5-flash-native-audio-preview-09-2025" # 以官方当前支持 bidiGenerateContent 的模型为准
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
speech_config=types.SpeechConfig(
voice_config=types.VoiceConfig(
prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Puck")
)
),
system_instruction="你是一名语速精炼的中文技术顾问,每次回答不超过三句话。",
)
async def main():
async with client.aio.live.connect(model=MODEL, config=config) as session:
await session.send_client_content(
turns={"role": "user", "parts": [{"text": "用两句话解释什么是 WebSocket"}]},
turn_complete=True,
)
async for response in session.receive():
if response.data is not None:
# response.data 为 24kHz 16-bit 单声道原始 PCM 字节流,送入本地声卡队列即可播放
print(f"收到音频分片: {len(response.data)} bytes")
asyncio.run(main())
实时发送麦克风流与摄像头帧时,改调 await session.send_realtime_input(audio=types.Blob(data=pcm_bytes, mime_type="audio/pcm;rate=16000"));传视频画面则按每秒约 1 帧 把压缩后的 image/jpeg 帧持续送入同一方法即可。
二、自然打断检测(VAD)与防回声自激要点
Live API 默认在服务端开启了自动语音活动检测(Voice Activity Detection),无需客户端手动切分「按住说话、松开发送」:
- 客户端即时清空播放队列:当模型正在朗读长段回复而用户突然开口说「停一下,换个方案」时,服务端会立即切断当前生成流,并在消息中返回
response.server_content.interrupted == True。你的前端播放器一旦读到该布尔值,必须立刻丢弃内存里排队的剩余 PCM 音频块,否则用户会觉得打断慢半拍。 - 必须开启硬件或浏览器回声消除(AEC):如果用户不戴耳机直接外放,扬声器播出的模型声音又会被麦克风录进去当成用户插话,导致模型自己打断自己。Web 端采集麦克风时务必在
getUserMedia开启echoCancellation: true与noiseSuppression: true。 - 手动按键说话场景可关闭自动 VAD:在嘈杂展会或对讲机交互场景下,可通过
realtime_input_config关闭服务端自动活动检测,改由客户端显式发送activity_start与activity_end信号精准控场。
谷歌开发账号与主力编程订阅提示:调试 Gemini Live API 与绑定按量结算需要状态正常的个人谷歌账号,若注册卡在手机验证可在本站选购带 2FA 的 谷歌邮箱成品号(说明见 谷歌账号购买页);日常编写 WebAudio 前端流处理与异步后端代码,还可搭配 Claude Code 或 ChatGPT Plus。

图:本站根据 Google Gemini API 文档:Live API capabilities guide 整理的示意图
三、突破 2 分钟 / 10 分钟 / 15 分钟限制:压缩与重连
很多团队上线后发现客服电话聊到第 10 分钟准时掉线,或者开了摄像头共享屏幕 2 分钟就报错退出,根源在于官方的会话窗口与连接周期双重限制(音频与视频每秒折算的 Token 成本见 Gemini API 价格说明):
- 突破 15 分钟音频 / 2 分钟音视频上下文上限:在
LiveConnectConfig中配置context_window_compression=types.ContextWindowCompressionConfig(sliding_window=types.SlidingWindow())。开启滑动窗口压缩后,当历史流接近阈值时系统会自动裁剪早期片段,使会话时长不再受硬上限封顶。 - 跨过 10 分钟单条 WebSocket 寿命上限:开启
session_resumption=types.SessionResumptionConfig(handle=saved_handle)。服务端会在对话期间不断下发最新恢复句柄(session_resumption_update.new_handle),并在连接即将满 10 分钟断开前约 60 秒发送go_away通知;客户端缓存最新handle发起新连接即可无缝续上刚才的对话上下文。
常见问题
问:为了降低延迟,能不能在 React / 小程序前端直接拿 API Key 连 Gemini 的 WebSocket?
答:严禁直接把主 GEMINI_API_KEY 放进前端代码,任何人打开浏览器抓包都能盗刷你的账单。官方提供两种合规架构:一是由你自己的后端服务器做 WebSocket 中继转发;二是由你的后端调用官方临时令牌(Ephemeral Tokens)接口签发仅单次会话有效、几分钟过期的受限短令牌交给前端直连。
问:Live API 里还能同时挂载 Function Calling 查业务数据库或调联网搜索吗?
答:支持。你可以在 LiveConnectConfig 的 tools 里声明自定义函数或 google_search;当语音对话触发工具调用时,服务端会下发 response.tool_call,你的代码执行完本地查询后再通过 session.send_tool_response(...) 把结果喂回实时流即可。
问:为什么摄像头传的是 30 帧高清视频,模型却看不清快速闪过的动作?
答:Live API 底层按约每秒 1 帧(1 FPS)的节奏采样视觉帧,更适合展示静态文档、桌面界面、商品外观或缓慢移动的场景,不适合分析毫秒级高速运动画面。
问:没有外币卡怎么买谷歌账号或开通 Claude Code、ChatGPT Plus 辅助开发,支持开发票吗?
答:可前往本站 谷歌账号购买页、Claude Code 充值页 或 AI 会员充值总览 自助选购,支持支付宝、微信支付及 AlipayHK 付款,会员充值支持免交密码卡密兑换,企业团队可申请开具国内增值税发票;实时价格与售后细则(掉订阅按剩余天数折退,封号不在质保范围)以页面展示为准。
相关教程
- Gemini API Python 调用教程:安装 google-genai SDK、流式输出与多轮对话
- Gemini 语音对话(Live)用不了怎么办:网页版与手机权限官方说明
- Gemini API 价格:各模型每百万 tokens 多少钱、免费层和付费层差在哪
- Google AI Studio 怎么用:界面入口、选模型、发第一条提示与获取代码
参考资料
- Google Gemini API 官方文档:Get started with Live API — https://ai.google.dev/gemini-api/docs/live
- Google Gemini API 官方文档:Live API capabilities guide — https://ai.google.dev/gemini-api/docs/live-guide
- Google Gemini API 官方文档:Live API session management — https://ai.google.dev/gemini-api/docs/live-session
0 条评论
还没有评论,来抢沙发~