gemini-live-api-dev

Name: gemini-live-api-dev
Author: google-gemini

github.com/google-gemini开发4.4k10.3k 次安装2 周前更新

代码仓库

关于 gemini-live-api-dev

用于 Gemini Live API 实时语音和视频应用开发的技能，面向 Python 与 JavaScript/TypeScript 开发者，涵盖 WebSocket 会话、媒体流、转录、翻译及异步工具调用。

主要功能

01双向音频流
02实时音频与视频输入
03流式转录与翻译
04多种语音活动检测模式
05异步工具执行
06会话恢复与管理

适用场景

01构建实时语音 Agent
02转录实时音频
03在实时会话中翻译语音
04随音频发送摄像头或屏幕画面

安装

复制下面的命令，在终端中运行。

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

安装后在 Claude Code 中输入/gemini-live-api-dev确认已加载。

附带文件references/migration.md

详细介绍

Gemini Live API 开发技能

概述

Live API 可通过 WebSockets 与 Gemini 进行低延迟实时语音和视频交互。它会处理连续的音频、视频或文本流，提供即时、自然如真人的语音回复和后台推理。

主要功能：

双向音频流 — 实时麦克风到扬声器的对话
后台推理（扩展思考） — 多步骤后台推理，并穿插口语化的对话填充语
实时流式转录 — 实时语音转文本，支持中间结果和最终结果
视频流 — 在发送音频的同时发送摄像头／屏幕帧
文本输入／输出 — 在实时会话中发送和接收文本
音频转录 — 获取输入和输出音频的文本转录
语音活动检测（VAD） — 自动服务端 VAD、客户端混合 VAD，以及手动按住说话
异步函数调用 — 在音频持续流式传输期间，以非阻塞方式执行工具
完整会话客户端内容 — 在流式传输期间注入并更新对话轮次
会话管理 — 上下文压缩、会话恢复、GoAway 信号
临时令牌 — 安全的客户端身份验证

说明

Live API 通过 WebSockets 直接连接。如需 WebRTC 支持或简化集成，请使用合作伙伴集成。

模型

当前模型（请使用这些模型）

gemini-3.8-live — 大多数低延迟语音 Agent 体验和无推理延迟实时对话的默认选项。支持交错推理、默认异步函数调用（behavior: NON_BLOCKING），以及完整会话客户端内容更新。
gemini-3.8-live-extended-thinking — 高推理能力的音频到音频模型，适用于实时交互中需要更强后台推理的场景。在持续输出对话语音填充语的同时处理后台推理和异步工具调用（必须设置 behavior: NON_BLOCKING）；生命周期通过 interaction_status（IN_PROGRESS 与 IDLE）管理。
gemini-3.5-transcribe-live — 实时流式语音转文本，支持中间假设、最终转录结果、智能格式化和混合 VAD。
gemini-3.5-live-translate-preview — 支持 70 多种语言的实时语音到语音流式翻译。

警告

旧版模型（gemini-3.1-flash-live-preview、gemini-2.5-flash-native-audio-*、gemini-live-2.5-flash-preview、gemini-2.0-flash-live-001）：有关会导致不兼容的协议变更（behavior: "NON_BLOCKING"、thinking_level、interaction_status、send_client_content），请阅读 references/migration.md。

SDK

Python：google-genai >= 2.3.0 — pip install -U google-genai
JavaScript/TypeScript：@google/genai >= 2.3.0 — npm install @google/genai

警告

旧版 SDK google-generativeai（Python）和 @google/generative-ai（JS）已弃用。切勿使用。

合作伙伴集成

为了简化实时音频／视频应用开发，请使用支持通过 WebRTC 或 WebSockets 调用 Gemini Live API 的第三方集成：

LiveKit — 使用 LiveKit Agents 调用 Gemini Live API。
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 位、单声道。原生采样率为 16 kHz（其他采样率会重新采样）。MIME 类型：audio/pcm;rate=16000
输出：原始 PCM、小端序、16 位、单声道。采样率为 24 kHz。

重要

所有实时流式用户输入（音频、视频和文本）都使用 send_realtime_input / sendRealtimeInput。在 Gemini 3.8 模型上，整个会话生命周期均支持 send_client_content / sendClientContent，可通过显式角色（user 或 model）注入对话上下文（turn_complete=true 会无条件中断当前生成）。

警告

请勿在 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.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?")

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: raw JPEG-encoded bytes
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' }
});

接收音频和文本

重要

单个服务端事件可能同时包含多个内容部分（例如，音频块和转录文本）。请始终处理每个事件中的所有部分，以免遗漏内容。

Python

async for response in session.receive():
    content = response.server_content
    if content:
        # Audio — process ALL parts in each event
        if content.model_turn:
            for part in content.model_turn.parts:
                if part.inline_data:
                    audio_data = part.inline_data.data
        # Transcription
        if content.input_transcription:
            print(f"User: {content.input_transcription.text}")
        if content.output_transcription:
            print(f"Gemini: {content.output_transcription.text}")
        # Interruption
        if content.interrupted is True:
            pass  # Stop playback, clear audio queue

JavaScript

// Inside the onmessage callback
const content = response.serverContent;
if (content?.modelTurn?.parts) {
  for (const part of content.modelTurn.parts) {
    if (part.inlineData) {
      const audioData = part.inlineData.data; // Base64 encoded
    }
  }
}
if (content?.inputTranscription) console.log('User:', content.inputTranscription.text);
if (content?.outputTranscription) console.log('Gemini:', content.outputTranscription.text);
if (content?.interrupted) { /* Stop playback, clear audio queue */ }

后台推理（扩展思考）

当语音 Agent 需要评估复杂数据、规划多个步骤或处理长时间运行的工具时，请使用 gemini-3.8-live-extended-thinking。模型会在后台执行异步工具的同时，使用自然的对话填充语（例如 “正在检查航班选项……”）。

关键要求：

思考配置：设置 thinking_config=types.ThinkingConfig(thinking_level="low")（"minimal" | "low" | "medium" | "high"）。
非阻塞工具：所有函数声明必须设置 behavior="NON_BLOCKING"。不支持同步阻塞模式，并会返回错误。
生命周期跟踪（interaction_status）：请勿仅依赖 turn_complete=True 来判断轮次是否完成。监控 message.interaction_status（Python）／message.interactionStatus（JS）：
- "IN_PROGRESS"：服务端正在推理、说出对话填充语，或等待异步工具响应。
- "IDLE"：服务端已完成所有后台推理和工具调用；会话已准备好接收用户输入。

如需查看完整的 Python 和 JavaScript 实现示例，请参阅 references/migration.md 和 Live API 思考指南。

实时翻译（Gemini Live Translate）

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

模型

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",  # Target language code (e.g. es, fr, pl)
        echo_target_language=True,
    ),
    input_audio_transcription=types.AudioTranscriptionConfig(),
    output_audio_transcription=types.AudioTranscriptionConfig(),
)

原始 WebSockets：将 translationConfig 放在 generationConfig 中：

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

实时流式转录（Gemini Live Transcribe）

Live API 支持通过 WebSockets 进行低延迟的实时流式语音转文本，提供临时假设结果、最终转录文本和 Hybrid VAD。有关完整详情，请参阅 Live Transcription 指南和 Colab Cookbook。

模型

gemini-3.5-transcribe-live

模式

smart：清理填充词、处理语句中的自我更正，并整理格式。
verbatim（默认）：逐字转录。

Python

config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    input_audio_transcription=types.AudioTranscriptionConfig(),
)

async with client.aio.live.connect(model="gemini-3.5-transcribe-live", config=config) as session:
    # Stream audio
    await session.send_realtime_input(audio=types.Blob(data=chunk, mime_type="audio/pcm;rate=16000"))
    # Hybrid VAD: notify turn end on client-detected silence for zero latency
    await session.send_realtime_input(audio_stream_end=True)

JavaScript

const session = await ai.live.connect({
  model: 'gemini-3.5-transcribe-live',
  config: {
    responseModalities: ['text'],
    inputAudioTranscription: { mode: 'smart' }
  },
  callbacks: {
    onmessage: (msg) => {
      if (msg.serverContent?.interimInputTranscription) {
        console.log('Interim:', msg.serverContent.interimInputTranscription.text);
      }
      if (msg.serverContent?.inputTranscription) {
        console.log('Final:', msg.serverContent.inputTranscription.text);
      }
    }
  }
});

session.sendRealtimeInput({ audio: { data: chunkBase64, mimeType: 'audio/pcm;rate=16000' } });
session.sendRealtimeInput({ audioStreamEnd: true }); // Hybrid VAD

原始 WebSockets

{
  "setup": {
    "model": "models/gemini-3.5-transcribe-live",
    "generationConfig": {
      "responseModalities": ["TEXT"],
      "speechConfig": {
        "voiceConfig": {}
      }
    },
    "inputAudioTranscription": {
      "mode": "smart"
    }
  }
}

限制

响应模态 — 每个会话只能使用 TEXT 或 AUDIO，不能同时使用。原生音频模型会输出音频（response_modalities=["AUDIO"]）；如果需要文本转录，请启用 output_audio_transcription。
纯音频会话 — 不压缩时为 15 min
音频+视频会话 — 不压缩时为 2 min
连接时长 — 约 10 min（使用会话恢复）
上下文窗口 — 128k 个输入令牌 / 64k 个输出令牌
代码执行 / URL 上下文 — 不支持

升级与迁移

从 gemini-3.1-flash-live-preview、gemini-2.5-flash-native-audio-* 或 gemini-2.0-flash-live-001 升级到 Gemini 3.8 Live 或 Gemini 3.8 Live Extended Thinking 时，如需分步迁移检查清单和协议差异，请阅读 references/migration.md。

最佳实践

测试麦克风音频时使用耳机，以防止回声或相互打断
会话超过 15 分钟时启用上下文窗口压缩
实现会话恢复，以妥善处理连接重置
在客户端部署中使用临时令牌 — 切勿在浏览器中暴露 API 密钥
对实时用户输入（音频、视频、文本）使用 send_realtime_input。使用 send_client_content 和明确的 user/model 角色，在流进行期间注入上下文轮次
麦克风暂停或用户说完时发送 audioStreamEnd / audio_stream_end（Hybrid VAD）
收到中断信号（interrupted: true）时清空音频播放队列
处理每个服务器事件中的所有部分 — 事件可能包含多个内容部分
使用 gemini-3.8-live-extended-thinking 时监控 interaction_status（IN_PROGRESS 与 IDLE），不要只依赖 turn_complete

文档查询

已安装 MCP 时（首选）

如果可以使用 Google MCP 服务提供的 search_docs 工具，请将其作为唯一的文档来源：

使用你的查询调用 search_docs
阅读返回的文档
以 MCP 结果作为 API 详情的准确信息来源 — 它们始终保持最新。

重要

存在 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）

主要文档页面

重要

这些并非全部文档页面。请使用 llms.txt 索引发现可用的文档页面

Live API 概览 — 入门指南、原始 WebSocket 用法
理解 Live API — 后台推理、对话填充语、interaction_status、非阻塞工具
模型卡：Gemini 3.8 Live — 默认的低延迟语音 Agent 模型和迁移指南
模型卡：Gemini 3.8 Live Extended Thinking — 高推理能力语音模型和升级指南
实时转录 — 实时语音转文本、中间假设、智能格式化和 Hybrid VAD
实时翻译 — 翻译的配置选项和功能
Live API 功能指南 — 语音配置、转录配置、VAD 配置、媒体分辨率
Live API 工具调用 — 函数调用（同步和异步）、Google Search grounding
会话管理 — 上下文窗口压缩、会话恢复、GoAway 信号
临时令牌 — 面向浏览器/移动设备的安全客户端身份验证
WebSockets API 参考 — 原始 WebSocket 协议详情
迁移与升级指南 — Gemini 3.8 Live 和 Extended Thinking 的分步检查清单和代码示例

支持的语言

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

支持 Markdown

登录后评论

基本信息

作者: google-gemini
仓库: google-gemini/gemini-skills
分类: 开发
安装次数: 10,263
GitHub Stars: 4,353

报告问题

gemini-live-api-dev

关于 gemini-live-api-dev

主要功能

适用场景

安装

详细介绍

Gemini Live API 开发技能

概述

模型

当前模型（请使用这些模型）

SDK

合作伙伴集成

音频格式

快速入门

身份验证

Python

JavaScript

连接 Live API

Python

JavaScript

发送文本

Python

JavaScript

发送音频

Python

JavaScript

发送视频

Python

JavaScript

接收音频和文本

Python

JavaScript

后台推理（扩展思考）

实时翻译（Gemini Live Translate）

模型

配置（TranslationConfig）

实时流式转录（Gemini Live Transcribe）

模型

模式

Python

JavaScript

原始 WebSockets

限制

升级与迁移

最佳实践

文档查询

已安装 MCP 时（首选）

未安装 MCP 时（仅作备用）

主要文档页面

支持的语言

评论

配置（`TranslationConfig`）