前言¶

要做麦克风到扬声器的低延迟语音对话、边播音频边推摄像头画面，或者把旧版 Live 模型迁到 Gemini 3.8，通常要同时啃 WebSocket 协议、音频格式、VAD 和会话恢复等多处文档。下面介绍 Google Gemini 官方仓库里的 gemini-live-api-dev Skill：它把 Live API 从建连、送流、收包到会话与鉴权的关键模式收在一套 Agent Skill 里，面向 Python google-genai 与 JavaScript/TypeScript @google/genai。

这是什么¶

gemini-live-api-dev 是 google-gemini/gemini-skills 下的开发型 Skill。官方描述为：在构建 Gemini Live API 实时双向流式应用，或从旧版 Live 模型（2.0 / 2.5 / 3.1）迁移到 Gemini 3.8 Live 时使用。

连接方式是 WebSocket（资料中说明：若需要 WebRTC 或更简集成，可走合作伙伴方案）。Skill 覆盖的能力包括：基于 WebSocket 的音视频/文本流、语音活动检测（VAD）、后台推理（extended thinking）、异步函数调用、会话管理、临时令牌（ephemeral tokens）、实时转写与实时翻译等。

核心功能¶

以下能力均来自官方 SKILL 说明，按主题归纳。

实时交互与多模态¶

• 双向音频流：麦克风输入到模型语音输出的实时对话。
• 视频流：在会话中 alongside 音频发送摄像头或屏幕帧。
• 文本输入/输出：在 Live 会话内发送与接收文本。
• 实时流式转写：语音转文字，含 interim 与 finalized 流。
• 音频转写：可对输入、输出音频分别拿到文本转写。

推理、工具与会话¶

• 后台推理（extended thinking）：多步后台推理，并可配合口语化填充语。
• 异步函数调用：工具执行不阻塞，音频可继续流式传输。
• 全会话客户端内容：可在流式过程中注入或更新对话轮次（Gemini 3.8 支持 send_client_content / sendClientContent，需明确 user 或 model 角色；turn_complete=true 会无条件打断当前生成）。
• 会话管理：上下文压缩、会话恢复、GoAway 信号等。
• 临时令牌：面向客户端的安全鉴权方式，避免在浏览器侧长期暴露 API Key。

语音活动检测（VAD）¶

• 服务端自动 VAD、客户端 Hybrid VAD、以及手动 Push-to-Talk。

推荐模型（当前）¶

旧版模型（如 gemini-3.1-flash-live-preview、gemini-2.5-flash-native-audio-* 等）需参考 Skill 内 references/migration.md，关注 behavior: "NON_BLOCKING"、thinking_level、interaction_status、send_client_content 等协议变更。

SDK 与音频格式¶

• Python：google-genai >= 2.3.0，安装：pip install -U google-genai
• JavaScript/TypeScript：@google/genai >= 2.3.0，安装：npm install @google/genai

勿使用已弃用的 google-generativeai（Python）与 @google/generative-ai（JS）。

音频约定（官方 Quick Start）：

• 输入：Raw PCM，little-endian，16-bit，mono；原生 16kHz（其他采样率会重采样）；MIME：audio/pcm;rate=16000
• 输出：Raw PCM，little-endian，16-bit，mono；24kHz

实时用户输入（音频、视频、文本）应统一走 send_realtime_input / sendRealtimeInput；在 sendRealtimeInput 中不要用 media 键，应使用 audio、video、text。

合作伙伴集成（可选）¶

官方列出通过 WebRTC 或 WebSocket 简化集成的方案，例如 LiveKit、Pipecat、Fishjam、Vision Agents、Voximplant、Firebase AI SDK 等；Skill 正文中有对应文档链接。

安装与启用¶

在支持 Agent Skills 的环境里，可用 officialskills.sh 记载的命令安装：

npx skills add https://github.com/google-gemini/gemini-skills --skill gemini-live-api-dev

也可将 Skill 目录链接交给编码助手安装：

https://github.com/google-gemini/gemini-skills/tree/main/skills/gemini-live-api-dev

安装后，在「构建 Live API 实时应用」或「迁移旧 Live 模型」相关任务中引用该 Skill，助手会按 SKILL.md 与 references 中的模式作答。Cursor、Codex CLI、Claude Code 等对 npx skills add 的支持以各自当前文档为准；未在官方资料中分项说明的差异此处不展开。

典型用法¶

下列片段来自官方 Quick Start，展示最小建连与送流路径；完整错误处理、VAD 与异步工具配置见 Skill 仓库内文档。

鉴权¶

Python：

from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

JavaScript：

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });

连接 Live 会话¶

Python（异步上下文管理）：

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=[types.Modality.AUDIO],
    system_instruction=types.Content(
        parts=[types.Part(text="You are a helpful assistant.")]
    )
)

async with client.aio.live.connect(model="gemini-3.8-live", config=config) as session:
    pass  # Session is active

JavaScript（回调）：

const session = await ai.live.connect({
  model: 'gemini-3.8-live',
  config: {
    responseModalities: ['audio'],
    systemInstruction: { parts: [{ text: 'You are a helpful assistant.' }] }
  },
  callbacks: {
    onopen: () => console.log('Connected'),
    onmessage: (response) => console.log('Message:', response),
    onerror: (error) => console.error('Error:', error),
    onclose: () => console.log('Closed')
  }
});

发送文本与音频¶

文本（Python）：

await session.send_realtime_input(text="Hello, how are you?")

音频分片（Python，PCM 16kHz）：

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

视频帧（Python，JPEG）：

await session.send_realtime_input(
    video=types.Blob(data=frame, mime_type="image/jpeg")
)

接收响应¶

官方强调：单个服务端事件可能同时包含多类 content parts（例如音频块与转写）。应对每个事件处理全部 parts，避免漏内容。

Python 接收循环示意：

async for response in session.receive():
    content = response.server_content
    if content:
        if content.model_turn:
            for part in content.model_turn.parts:
                if part.inline_data:
                    audio_data = part.inline_data.data
        if content.input_transcription:
            print(f"User: {content.input_transcription.text}")
        if content.output_transcription:
            print(f"Gemini: {content.output_transcription.text}")

适用场景与注意¶

适合谁

• 做实时语音助手：麦克风输入、模型语音即时回复。
• 多模态 Live 对话：音频流与摄像头/屏幕帧同会话发送。
• 需要会话恢复、连接重置后继续上下文。
• 浏览器部署：用 ephemeral tokens 降低 API Key 暴露面。
• 配置 VAD，处理用户打断模型播报等交互。

限制与注意

• Live API 直连为 WebSocket；WebRTC 或托管式集成需走合作伙伴或 Firebase 等路径。
• 迁移 2.0 / 2.5 / 3.1 Live 时务必对照 Skill 内 migration 说明，避免旧字段与新版 NON_BLOCKING、状态机不一致。
• SDK 版本需满足 >= 2.3.0，且勿混用已弃用包名。

结尾¶

gemini-live-api-dev 把 Gemini Live API 的 WebSocket 流式全链路——模型选择、PCM 格式、送流 API、收包解析、VAD、会话与临时令牌——整理成可被编码助手调用的 Skill，适合作为 2026 年实时语音与多模态 Agent 开发的对照手册。官方仓库：

https://github.com/google-gemini/gemini-skills/tree/main/skills/gemini-live-api-dev