Tai-ch0802 Gemini Live API 開發技能
概述
Live API 支援透過 WebSockets 與 Gemini 進行低延遲、即時的語音和視訊互動。它能處理連續的音訊、視訊或文字串流，並提供即時、擬真的口語回應。
主要功能：
- 雙向音訊串流 — 即時的麥克風對喇叭對話
- 視訊串流 — 將攝影機/螢幕畫面與音訊一起傳送
- 文字輸入/輸出 — 在即時會話中傳送和接收文字
- 音訊轉錄 — 取得輸入和輸出音訊的文字轉錄
- 語音活動偵測 (VAD) — 自動處理中斷
- 原生音訊 — 思考（透過可設定的
thinkingLevel） - 函式呼叫 — 同步的工具使用
- Google 搜尋背景資訊 (Grounding) — 將回應建立在即時的搜尋結果上
- 會話管理 — 上下文壓縮、會話恢復、GoAway 訊號
- 臨時權杖 — 安全的用戶端身分驗證
[!NOTE] Live API 目前僅支援 WebSockets。如需 WebRTC 支援或簡化的整合，請使用合作夥伴整合。
模型
gemini-3.1-flash-live-preview— 針對低延遲、即時對話進行最佳化。原生音訊輸出、思考（透過thinkingLevel）。128k 上下文視窗。這是所有 Live API 案例的建議模型。
[!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 日。
SDKs
- 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 或 WebSockets）：
- 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，小端序 (little-endian)，16 位元，單聲道。原生為 16kHz（將重新取樣其他頻率）。MIME 類型：
audio/pcm;rate=16000 - 輸出：原始 PCM，小端序 (little-endian)，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="你是一個樂於助人的助手。")]
)
)
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: '你是一個樂於助人的助手。' }] }
},
callbacks: {
onopen: () => console.log('已連接'),
onmessage: (response) => console.log('訊息:', response),
onerror: (error) => console.error('錯誤:', error),
onclose: () => console.log('已關閉')
}
});
傳送文字
Python
await session.send_realtime_input(text="你好，你好嗎？")
JavaScript
session.sendRealtimeInput({ text: '你好，你好嗎？' });
傳送音訊
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"User: {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('User:', content.inputTranscription.text);
if (content?.outputTranscription) console.log('Gemini:', content.outputTranscription.text);
if (content?.interrupted) { /* 停止播放，清除音訊佇列 */ }
限制
- 回應模態 — 每個會話僅限
TEXT或AUDIO，無法兩者兼具 - 純音訊會話 — 不壓縮情況下可達 15 分鐘
- 音訊+視訊會話 — 不壓縮情況下可達 2 分鐘
- 連線壽命 — 約 10 分鐘（請使用會話恢復）
- 上下文視窗 — 128k 個 token（原生音訊）/ 32k 個 token（標準）
- 非同步函式呼叫 — 尚未支援；函式呼叫僅為同步。模型會等到你回傳 tool 回應後才開始回覆。
- 主動式音訊（Proactive audio） — Gemini 3.1 Flash Live 尚未支援，請移除相關設定。
- 情感對話（Affective dialogue） — 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以取得最低延遲。 - 伺服器事件 — 單一事件可同時包含多個 content parts（音訊 + 轉錄）。請處理每個事件中的所有 parts。
- Client content —
send_client_content僅用於注入初始上下文歷史記錄（需在history_config中設定initial_history_in_client_content）。對話期間傳送文字請使用send_realtime_input。 - Turn coverage — 預設由
TURN_INCLUDES_ONLY_ACTIVITY改為TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO。若會持續送出視訊影格，請考慮只在有音訊活動時送出，以降低成本。 - 非同步函式呼叫 — 尚未支援，函式呼叫僅為同步。
- 主動式音訊與情感對話 — 尚未支援，請移除相關設定。
最佳實踐
- 測試麥克風音訊時請使用耳機，以防產生回音/自我中斷
- 針對超過 15 分鐘的會話啟用上下文視窗壓縮
- 實作會話恢復以優雅地處理連線重設
- 為用戶端部署使用臨時權杖 — 切勿在瀏覽器中暴露 API 金鑰
- 針對所有即時使用者輸入使用
send_realtime_input（音訊、視訊、文字）。僅保留send_client_content來注入對話歷史記錄 - 在麥克風暫停時傳送
audioStreamEnd以排空快取的音訊 - 在收到中斷訊號時清除音訊播放佇列
- 處理每個事件中的所有 parts — 一個事件可同時包含多個 content parts
文件查詢
已安裝 MCP（建議）
若有 search_docs 工具（來自 Google MCP 伺服器）可用，請將其作為唯一文件來源：
- 以你的查詢呼叫
search_docs - 閱讀回傳的文件
- 以 MCP 結果為信任來源取得 API 細節 —— 它們始終是最新的。
[!IMPORTANT] 當有 MCP 工具時，絕不要手動 fetch URL。MCP 提供最新且已索引的文件，比 URL fetching 更精準也更省 token。
未安裝 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 訊號
- 臨時權杖 — 適用於瀏覽器/行動裝置的安全用戶端身分驗證
- WebSockets API 參考 — 原始 WebSocket 協定詳細資料
支援語言
Live API 支援 70 種語言，包括：英文、西班牙文、法文、德文、義大利文、葡萄牙文、中文、日文、韓文、印地文、阿拉伯文、俄文等。原生音訊模型會自動偵測並切換語言。