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('已連線'),
    onmessage: (response) => console.log('訊息：', response),
    onerror: (error) => console.error('錯誤：', error),
    onclose: () => console.log('已關閉')
  }
});

傳送文字

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

相關技能

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`)