gemini-live-api-dev

Gemini Live API 开发技能

概述

Live API 支持通过 WebSocket 与 Gemini 进行低延迟、实时的语音和视频交互。它处理连续的音频、视频或文本流，以提供即时、类人的语音响应。

关键能力：

双向音频流 — 实时麦克风到扬声器的对话
视频流 — 在音频旁发送摄像头/屏幕帧
文本输入/输出 — 在实时会话中发送和接收文本
音频转录 — 获取输入和输出音频的文本转录
语音活动检测 (VAD) — 自动中断处理
原生音频 — 思考（可配置 thinkingLevel）
函数调用 — 同步工具使用
Google 搜索引用 — 基于实时搜索结果进行响应
会话管理 — 上下文压缩、会话恢复、GoAway 信号
临时令牌 — 安全的客户端身份验证

[!NOTE]
Live API 目前仅支持 WebSocket。如需 WebRTC 支持或简化集成，请使用合作伙伴集成。

模型

gemini-3.1-flash-live-preview — 针对低延迟实时对话进行了优化。原生音频输出，思考（通过 thinkingLevel）。128k 上下文窗口。这是所有 Live API 用例的推荐模型。
gemini-3.5-live-translate-preview — 实时流式翻译模型。

[!WARNING]
以下 Live API 模型已弃用，即将关闭。请迁移到 gemini-3.1-flash-live-preview。

gemini-2.5-flash-native-audio-preview-12-2025 — 迁移到 gemini-3.1-flash-live-preview。

gemini-live-2.5-flash-preview — 发布于 2025 年 6 月 17 日。关闭时间：2025 年 12 月 9 日。

gemini-2.0-flash-live-001 — 发布于 2025 年 4 月 9 日。关闭时间：2025 年 12 月 9 日。

SDK

Python：google-genai — pip install google-genai
JavaScript/TypeScript：@google/genai — npm install @google/genai

[!WARNING]
旧版 SDK google-generativeai (Python) 和 @google/generative-ai (JS) 已弃用。请使用上述新 SDK。

合作伙伴集成

为简化实时音频/视频应用开发，可使用支持 Gemini Live API 的第三方集成（通过 WebRTC 或 WebSocket）：

LiveKit — 将 Gemini Live API 与 LiveKit Agents 结合使用。
Pipecat by Daily — 使用 Gemini Live 和 Pipecat 创建实时 AI 聊天机器人。
Fishjam by Software Mansion — 使用 Fishjam 创建实时视频和音频流应用。
Vision Agents by Stream — 使用 Vision Agents 构建实时语音和视频 AI 应用。
Voximplant — 使用 Voximplant 将入站和出站呼叫连接到 Live API。
Firebase AI SDK — 使用 Firebase AI Logic 开始使用 Gemini Live API。

音频格式

输入：原始 PCM，小端序，16 位，单声道。16kHz 原生（其他采样率将重新采样）。MIME 类型：audio/pcm;rate=16000
输出：原始 PCM，小端序，16 位，单声道。24kHz 采样率。

[!IMPORTANT]
对所有实时用户输入（音频、视频和文本）使用 send_realtime_input / sendRealtimeInput。send_client_content / sendClientContent 仅支持用于播种初始上下文历史（需要在 history_config 中设置 initial_history_in_client_content）。不要在对话期间使用它发送新的用户消息。

[!WARNING]
不要在 sendRealtimeInput 中使用 media。请使用特定键：audio 用于音频数据，video 用于图像/视频帧，text 用于文本输入。

快速开始

身份验证

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 API

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.1-flash-live-preview", config=config) as session:
    pass  # 会话已激活

JavaScript

const session = await ai.live.connect({
  model: 'gemini-3.1-flash-live-preview',
  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?")

JavaScript

session.sendRealtimeInput({ text: 'Hello, how are you?' });

发送音频

Python

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

JavaScript

session.sendRealtimeInput({
  audio: { data: chunk.toString('base64'), mimeType: 'audio/pcm;rate=16000' }
});

发送视频

Python

# frame: 原始 JPEG 编码字节
await session.send_realtime_input(
    video=types.Blob(data=frame, mime_type="image/jpeg")
)

JavaScript

session.sendRealtimeInput({
  video: { data: frame.toString('base64'), mimeType: 'image/jpeg' }
});

接收音频和文本

[!IMPORTANT]
单个服务器事件可以同时包含多个内容部分（例如，音频块和转录）。始终处理每个事件中的所有部分，以免丢失内容。

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"用户: {content.input_transcription.text}")
        if content.output_transcription:
            print(f"Gemini: {content.output_transcription.text}")
        # 中断
        if content.interrupted is True:
            pass  # 停止播放，清除音频队列

JavaScript

// 在 onmessage 回调内部
const content = response.serverContent;
if (content?.modelTurn?.parts) {
  for (const part of content.modelTurn.parts) {
    if (part.inlineData) {
      const audioData = part.inlineData.data; // Base64 编码
    }
  }
}
if (content?.inputTranscription) console.log('用户:', content.inputTranscription.text);
if (content?.outputTranscription) console.log('Gemini:', content.outputTranscription.text);
if (content?.interrupted) { /* 停止播放，清除音频队列 */ }

实时翻译 (Gemini Live Translate)

Live API 支持对 70 多种语言的语音（音频）进行实时、低延迟的流式翻译。有关选项和功能的完整详细信息，请参阅实时翻译指南。

模型

gemini-3.5-live-translate-preview — 所有 Live Translate 用例的推荐翻译模型。

配置 (`TranslationConfig`)

要启用翻译，请在实时会话设置中指定一个 TranslationConfig 对象：

Python SDK：使用 LiveConnectConfig 上的 translation_config 配置连接：

config = types.LiveConnectConfig(
    response_modalities=[types.Modality.AUDIO],
    translation_config=types.TranslationConfig(
        target_language_code="es",  # 目标语言代码（例如 es, fr, pl）
        echo_target_language=True,
    ),
    input_audio_transcription=types.AudioTranscriptionConfig(),
    output_audio_transcription=types.AudioTranscriptionConfig(),
)

原始 WebSocket：将 translationConfig 放在 generationConfig 内部：

{
  "setup": {
    "model": "models/gemini-3.5-live-translate-preview",
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "translationConfig": {
        "targetLanguageCode": "es",
        "echoTargetLanguage": true
      }
    }
  }
}

限制

响应模态 — 每个会话仅支持 TEXT 或 AUDIO，不能同时支持两者。原生音频模型仅支持音频。
纯音频会话 — 无压缩时最长 15 分钟
音频+视频会话 — 无压缩时最长 2 分钟
连接生命周期 — 约 10 分钟（使用会话恢复）
上下文窗口 — 128k 令牌（原生音频）/ 32k 令牌（标准）
异步函数调用 — 尚不支持；函数调用仅支持同步。模型在收到工具响应之前不会开始响应。
主动音频 — Gemini 3.1 Flash Live 尚不支持。请移除该功能的任何配置。
情感对话 — Gemini 3.1 Flash Live 尚不支持。请移除该功能的任何配置。
代码执行 — 不支持
URL 上下文 — 不支持

从 Gemini 2.5 Flash Live 迁移

从 gemini-2.5-flash-native-audio-preview-12-2025 迁移到 gemini-3.1-flash-live-preview 时：

模型字符串 — 从 gemini-2.5-flash-native-audio-preview-12-2025 更新为 gemini-3.1-flash-live-preview。
思考配置 — 使用 thinkingLevel（minimal、low、medium、high）代替 thinkingBudget。默认值为 minimal，以实现最低延迟。
服务器事件 — 单个事件可以同时包含多个内容部分（音频 + 转录）。处理每个事件中的所有部分。
客户端内容 — send_client_content 仅用于播种初始上下文历史（在 history_config 中设置 initial_history_in_client_content）。在对话期间使用 send_realtime_input 发送文本。
轮次覆盖 — 默认为 TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO，而不是 TURN_INCLUDES_ONLY_ACTIVITY。如果持续发送视频帧，请考虑仅在音频活动期间发送以降低成本。
异步函数调用 — 尚不支持。函数调用仅支持同步。
主动音频和情感对话 — 尚不支持。请移除这些功能的任何配置。

最佳实践

测试麦克风音频时使用耳机，以防止回声/自我中断
对于超过 15 分钟的会话，启用上下文窗口压缩
实现会话恢复以优雅地处理连接重置
对于客户端部署，使用临时令牌 — 切勿在浏览器中暴露 API 密钥
对所有实时用户输入（音频、视频、文本）使用 send_realtime_input。仅将 send_client_content 保留用于播种初始上下文历史
当麦克风暂停时，发送 audioStreamEnd 以刷新缓存的音频
在收到中断信号时清除音频播放队列
处理每个服务器事件中的所有部分 — 事件可能包含多个内容部分

文档查找

已安装 MCP 时（推荐）

如果 search_docs 工具（来自 Google MCP 服务器）可用，请将其作为唯一文档来源：

使用查询调用 search_docs
阅读返回的文档
信任 MCP 结果作为 API 细节的权威来源 — 它们始终是最新的。

[!IMPORTANT]
当 MCP 工具存在时，切勿手动获取 URL。MCP 提供最新、已索引的文档，比 URL 获取更准确且令牌效率更高。

未安装 MCP 时（仅回退）

如果没有可用的 MCP 文档工具，请从官方文档索引获取：

llms.txt URL：https://ai.google.dev/gemini-api/docs/llms.txt

此索引包含所有文档页面的链接，格式为 .md.txt。使用网络获取工具：

获取 llms.txt 以发现可用的文档页面
获取特定页面（例如 https://ai.google.dev/gemini-api/docs/live-session.md.txt）

关键文档页面

[!IMPORTANT]
这些并非所有文档页面。请使用 llms.txt 索引发现可用的文档页面

Live API 概述 — 入门、原始 WebSocket 使用
实时翻译 — 翻译的配置选项和功能
Live API 功能指南 — 语音配置、转录配置、原生音频（思考）、VAD 配置、媒体分辨率
Live API 工具使用 — 函数调用（同步和异步）、Google 搜索引用
会话管理 — 上下文窗口压缩、会话恢复、GoAway 信号
临时令牌 — 浏览器/移动端的安全客户端身份验证
WebSocket API 参考 — 原始 WebSocket 协议细节

支持的语言

Live API 支持 70 种语言，包括：英语、西班牙语、法语、德语、意大利语、葡萄牙语、中文、日语、韩语、印地语、阿拉伯语、俄语等。原生音频模型会自动检测并切换语言。

你可能还喜欢

cloudflare-one

2.2Kmcp-integrations

Guides Cloudflare One Zero Trust and SASE work across Access, Gateway, WARP, Tunnel, Cloudflare WAN, DLP, CASB, device posture, and identity. Use when designing, configuring, troubleshooting, or reviewing Cloudflare One deployments. Retrieval-first: use current Cloudflare docs/API schemas instead of embedded product docs.

cloudflare

获取

nutrient-document-processing

230Kmcp-integrations

Process, convert, OCR, extract, redact, sign, and fill documents using the Nutrient DWS API. Works with PDFs, DOCX, XLSX, PPTX, HTML, and images.

affaan-m

获取

chrome-devtools

47Kmcp-integrations

Uses Chrome DevTools via MCP for efficient debugging, troubleshooting and browser automation. Use when debugging web pages, automating browser interactions, analyzing performance, or inspecting network requests. This skill does not apply to `--slim` mode (MCP configuration).

chromedevtools

获取

继续探索

浏览 mcp-integrations 热门 Skills 最近更新

gemini-live-api-dev

相关 Skills

Gemini Live API 开发技能

概述

模型

SDK

合作伙伴集成

音频格式

快速开始

身份验证

Python

JavaScript

连接到 Live API

Python

JavaScript

发送文本

Python

JavaScript

发送音频

Python

JavaScript

发送视频

Python

JavaScript

接收音频和文本

Python

JavaScript

实时翻译 (Gemini Live Translate)

模型

配置 (TranslationConfig)

限制

从 Gemini 2.5 Flash Live 迁移

最佳实践

文档查找

已安装 MCP 时（推荐）

未安装 MCP 时（仅回退）

关键文档页面

支持的语言

你可能还喜欢

cloudflare-one

nutrient-document-processing

chrome-devtools

继续探索

配置 (`TranslationConfig`)