前言¶

要做麥克風到揚聲器的低延遲語音對話、邊播音頻邊推攝像頭畫面，或者把舊版 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