Gemini Live API(实时双向音视频流)开发入门:WebSocket 低延迟语音视频对话、打断检测与会话时长限制

想开发像真人通话一样随时打断、还能看摄像头画面的实时语音助手?本文按 Gemini Live API 官方文档整理 WebSocket 异步连接代码、16kHz/24kHz 音频流格式、VAD 打断处理与 10/15 分钟时长上限突破方案。

NNathaniel bigo··原创首发·AI 辅助撰写
11 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 其他 账号

结论先说

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

Gemini Live API 会话与采样规格表

图:本站根据 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),无需客户端手动切分「按住说话、松开发送」:

  1. 客户端即时清空播放队列:当模型正在朗读长段回复而用户突然开口说「停一下,换个方案」时,服务端会立即切断当前生成流,并在消息中返回 response.server_content.interrupted == True。你的前端播放器一旦读到该布尔值,必须立刻丢弃内存里排队的剩余 PCM 音频块,否则用户会觉得打断慢半拍。
  2. 必须开启硬件或浏览器回声消除(AEC):如果用户不戴耳机直接外放,扬声器播出的模型声音又会被麦克风录进去当成用户插话,导致模型自己打断自己。Web 端采集麦克风时务必在 getUserMedia 开启 echoCancellation: true 与 noiseSuppression: true。
  3. 手动按键说话场景可关闭自动 VAD:在嘈杂展会或对讲机交互场景下,可通过 realtime_input_config 关闭服务端自动活动检测,改由客户端显式发送 activity_start 与 activity_end 信号精准控场。
谷歌开发账号与主力编程订阅提示:调试 Gemini Live API 与绑定按量结算需要状态正常的个人谷歌账号,若注册卡在手机验证可在本站选购带 2FA 的 谷歌邮箱成品号(说明见 谷歌账号购买页);日常编写 WebAudio 前端流处理与异步后端代码,还可搭配 Claude Code 或 ChatGPT Plus。

Gemini Live 断连与打断异常排查

图:本站根据 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 付款,会员充值支持免交密码卡密兑换,企业团队可申请开具国内增值税发票;实时价格与售后细则(掉订阅按剩余天数折退,封号不在质保范围)以页面展示为准。

相关教程

参考资料

  • 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

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同模型

  1. 01

    用 Google Takeout 单独备份导出 NotebookLM 笔记本与 Gemini 记录:只勾选指定服务不下载整个云端硬盘的步骤

    想把 NotebookLM 里的几十个研究笔记本、来源副本与音频概览,连同 Gemini 聊天记录一起备份到本地,又怕 Google Takeout 把整个云端硬盘和相册全打包?本文讲清先取消全选、精准勾选两项服务、解压目录查看与跨号迁移的做法。

    Gemini0
  2. 02

    Google Workspace 企业/教育版管理员怎么在后台给成员开启 Gemini 应用、NotebookLM 与设置年龄访问权限

    团队成员或学校师生登录 Google Workspace 账号时提示无权使用 Gemini 或打不开 NotebookLM?本文按 Google 管理控制台官方文档整理服务开关路径、组织部门(OU)与群组放行、18 岁年龄访问权限设置及对话保留合规配置。

    Gemini0
  3. 03

    安卓手机默认助手换成 Gemini 后设闹钟、发短信或控制智能家居失灵怎么办:Workspace 与实用程序扩展开启步骤

    安卓手机把默认语音助手从 Google Assistant 换成 Gemini 后,喊它定闹钟、开手电筒、发短信或开关智能灯全都没反应?本文按官方帮助中心整理实用程序(Utilities)、Google Home 与 Workspace 关联应用开启步骤及锁屏放行设置。

    Gemini0
  4. 04

    Gemini 写长代码或长文档到一半突然停住、格式截断怎么无缝续写:锚点接续指令与 Canvas 分块修改技巧

    让 Gemini 写几百行代码或万字长文时经常写到一半突然停住、Markdown 代码块没闭合,直接回「继续」又重头抄一遍?本文整理字面锚点续写指令、代码块防乱码补齐法与 Canvas 局部圈选修改工作流。

    Gemini0
  5. 05

    NotebookLM 中文音频播客(Audio Overview)高阶玩法:用自定义引导词控制对谈深度、受众水平与重点章节(附模板)

    NotebookLM 生成的中文音频播客总是泛泛而谈、漏掉核心章节或夹杂生僻英文缩写?本文按官方帮助中心整理来源勾选过滤、四种播客格式搭配与三维自定义引导词写法,附 4 套可直接复制的中文控场模板。

    Gemini0
  6. 06

    NotebookLM 添加 YouTube 视频、网页或扫描版 PDF 提示「无法导入来源」怎么办:无字幕、反爬与纯图 PDF 逐项解决

    往 NotebookLM(Gemini Notebook)塞 YouTube 链接、外文网页或扫描教材时总是亮红叹号提示无法导入来源?本文按官方帮助中心逐项排查无字幕视频、反爬动态页与加密纯图 PDF 的替代导入步骤。

    Gemini0

同产品的其他教程

  1. 01

    iPhone 操作按钮(Action Button)或锁屏小组件一键开启 ChatGPT / Gemini 实时语音对话配置教程

    每次在 iPhone 上练口语或语音提问都要解锁、找图标、再点耳机按钮太繁琐?本文整理利用 iPhone 操作按钮(Action Button)、iOS 18 锁屏底部控制项、控制中心与背面轻点一键直达 ChatGPT 实时语音或 Gemini Live 的完整步骤。

    ChatGPTGemini0
  2. 02

    Firebase Studio(原 Project IDX)是什么、怎么用:浏览器云端全栈开发环境搭配 Gemini 智能体实战

    以前收藏的 Project IDX 网址为什么跳到了 Firebase Studio?本文按 Google 官方文档讲清它的全栈云端定位、App Prototyping 原型智能体、Code 视图切换、.idx/dev.nix 环境定制与免费工作区上限。

    Gemini其他 AI 工具0
  3. 03

    Google Colab 内置 Gemini 编程助手怎么用:免费云端 GPU 笔记本自动生成数据分析代码、修报错与限额说明

    不用配本地 Python 环境,怎么在 Google Colab 云端笔记本里免费用 Gemini 自动写数据分析代码、一键修复红字报错并跑 Data Science Agent?本文整理四大入口用法、Secrets 密钥管理与免费版限额。

    Gemini其他 AI 工具0
  4. 04

    Gemini API Token 计数(count_tokens)与多模态计费规则:图片分辨率、音频秒数与视频帧率怎么折算 Token

    传一张高清截图或一段 10 分钟视频给 Gemini API 到底扣多少 Token?本文按官方文档拆解 258 图片切片、每秒 32 音频与每秒 263 视频折算公式,附 count_tokens 免费预估与降本代码。

    Gemini0
  5. 05

    Gemini API 回答被安全策略拦截(SAFETY / PROHIBITED_CONTENT)怎么办:阈值调节边界与合规提示词排查

    调用 Gemini API 翻译文档或分析安全日志时返回空白、报 finish_reason: SAFETY 或 PROHIBITED_CONTENT 怎么办?本文详解四类可调安全阈值代码写法、不可关闭的硬性红线区别与误报排查步骤。

    Gemini0
  6. 06

    Gemini API 图像生成与多轮改图怎么调:用 google-genai SDK 出图、局部修改与宽高比控制参数

    怎么用 Python 代码调用 Gemini API 生成高清配图并像聊天一样连续局部改图?本文详解 google-genai SDK 原生生图代码、多轮对话改图、参考图融合与 aspect_ratio 宽高比配置。

    Gemini0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~