Live API 是使用 WebSockets 的有狀態 API。本節將提供 WebSockets API 的其他詳細資料。
工作階段
WebSocket 連線會在用戶端和 Gemini 伺服器之間建立工作階段。用戶端啟動新連線後，工作階段可以與伺服器交換訊息，以便：
- 將文字、音訊或影片傳送至 Gemini 伺服器。
- 接收來自 Gemini 伺服器的音訊、文字或函式呼叫要求。
WebSocket 連線
如要啟動工作階段，請連線至這個 WebSocket 端點：
wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent
工作階段設定
建立 WebSocket 連線後傳送的初始訊息會設定工作階段設定，包括模型、生成參數、系統指令和工具。
連線開啟時無法更新設定。不過，透過工作階段續傳機制暫停及繼續時，您可以變更設定參數 (模型除外)。
請參閱以下設定範例。請注意，SDK 中的名稱大小寫可能有所不同。如要查詢 Python SDK 設定選項，請參閱這篇文章。
{
"model": string,
"generationConfig": {
"candidateCount": integer,
"maxOutputTokens": integer,
"temperature": number,
"topP": number,
"topK": integer,
"presencePenalty": number,
"frequencyPenalty": number,
"responseModalities": [string],
"speechConfig": object,
"mediaResolution": object,
"translationConfig": object
},
"systemInstruction": string,
"tools": [object]
}
如要進一步瞭解 API 欄位，請參閱「generationConfig」。
傳送訊息
如要透過 WebSocket 連線交換訊息，用戶端必須透過開啟的 WebSocket 連線傳送 JSON 物件。JSON 物件必須只包含下列物件集中的一個欄位：
{
"setup": BidiGenerateContentSetup,
"clientContent": BidiGenerateContentClientContent,
"realtimeInput": BidiGenerateContentRealtimeInput,
"toolResponse": BidiGenerateContentToolResponse
}
支援的用戶端訊息
請參閱下表，瞭解支援的用戶端訊息：
| 訊息 | 說明 |
|---|---|
BidiGenerateContentSetup |
要在第一則訊息中傳送的工作階段設定 |
BidiGenerateContentClientContent |
用戶端傳送的目前對話增量內容更新 |
BidiGenerateContentRealtimeInput |
即時音訊、影片或文字輸入 |
BidiGenerateContentToolResponse |
回應伺服器傳回的 ToolCallMessage |
接收訊息
如要接收 Gemini 傳送的訊息，請監聽 WebSocket 的「message」事件，然後根據支援的伺服器訊息定義剖析結果。
請參閱以下資訊：
async with client.aio.live.connect(model='...', config=config) as session:
await session.send(input='Hello world!', end_of_turn=True)
async for message in session.receive():
print(message)
伺服器訊息可能含有 usageMetadata 欄位，但會BidiGenerateContentServerMessage訊息中BidiGenerateContentServerMessage包含BidiGenerateContentServerMessage其他欄位。(messageType 聯集不會以 JSON 表示，因此欄位會顯示在訊息的頂層)。
訊息和活動
ActivityEnd
這個類型沒有任何欄位。
標記使用者活動的結束時間。
ActivityHandling
處理使用者活動的不同方式。
| 列舉 | |
|---|---|
ACTIVITY_HANDLING_UNSPECIFIED |
如未指定，預設行為為 START_OF_ACTIVITY_INTERRUPTS。 |
START_OF_ACTIVITY_INTERRUPTS |
如果設為 true，活動開始時會中斷模型的回覆 (也稱為「插話」)。模型目前的回覆會在您中斷時停止。此為預設行為。 |
NO_INTERRUPTION |
模型不會中斷回覆。 |
ActivityStart
這個類型沒有任何欄位。
標記使用者活動的開始時間。
AudioTranscriptionConfig
音訊轉錄設定。
| 欄位 | |
|---|---|
languageCodes[] |
(選用步驟) BCP-47 語言代碼，提供音訊中語言的提示。如果省略或留空，系統會預設為自動偵測語言。 |
customVocabulary[] |
(選用步驟) 自訂詞彙詞組清單，可引導語音辨識模型辨識特定字詞 (產品名稱、專有名詞、專業術語)。 |
wordTimestamp |
(選用步驟) 設定字詞層級時間戳記的產生方式。 |
diarization |
(選用步驟) 設定說話者分段標記。 |
mode |
(選用步驟) 設定轉錄模式。支援的值： |
模式
轉錄模式。
| 列舉 | |
|---|---|
MODE_UNSPECIFIED |
未指定轉錄模式。 |
VERBATIM |
逐字轉錄模式。 |
SMART |
智慧轉錄模式。 |
AutomaticActivityDetection
設定自動偵測活動。
| 欄位 | |
|---|---|
disabled |
(選用步驟) 啟用此覆寫值時 (預設為啟用)，系統會將偵測到的語音和文字輸入視為活動。如果停用，用戶端就必須傳送活動信號。 |
startOfSpeechSensitivity |
(選用步驟) 決定偵測到語音的機率。 |
prefixPaddingMs |
(選用步驟) 系統偵測到語音後，必須經過這段時間，才會開始轉錄語音。這個值越低，語音開始偵測的靈敏度就越高，可辨識的語音長度就越短。但這也會提高偽陽性的機率。 |
endOfSpeechSensitivity |
(選用步驟) 決定偵測到的語音結束的可能性。 |
silenceDurationMs |
(選用步驟) 系統偵測到非語音內容 (例如無聲) 的必要時間長度，之後才會提交語音結尾。這個值越大，語音間隔時間就越長，不會中斷使用者活動，但會增加模型延遲。 |
BidiGenerateContentClientContent
從用戶端傳送的目前對話增量更新。系統會將這裡的所有內容無條件附加至對話記錄，並做為提示的一部分，供模型生成內容。
在這裡傳送訊息會中斷目前模型的生成作業。
| 欄位 | |
|---|---|
turns[] |
(選用步驟) 附加至目前與模型對話的內容。 如果是單輪查詢，則為單一執行個體。如果是多輪查詢，這個重複欄位會包含對話記錄和最新要求。 |
turnComplete |
(選用步驟) 如果為 true，表示伺服器內容生成作業應從目前累積的提示開始。否則，伺服器會等待其他訊息，再開始生成內容。 |
BidiGenerateContentRealtimeInput
即時傳送的使用者輸入內容。
系統會將不同模態 (音訊、影片和文字) 視為並行串流處理。我們無法保證這些串流的順序。
這與 BidiGenerateContentClientContent 有幾項不同之處：
- 可持續傳送，不會中斷模型生成作業。
- 如果需要混合交錯於
BidiGenerateContentClientContent和BidiGenerateContentRealtimeInput的資料，伺服器會盡量提供最佳回應，但無法保證結果。 - 系統不會明確指定回合結束，而是根據使用者活動 (例如語音結束) 推斷。
- 即使在輪流對話結束前，系統也會逐步處理資料，盡快開始生成模型回覆。
| 欄位 | |
|---|---|
mediaChunks[] |
(選用步驟) 媒體輸入內容的內嵌位元組資料。系統不支援多個 已淘汰：請改用 |
audio |
(選用步驟) 這些會形成即時音訊輸入串流。 |
video |
(選用步驟) 這些會形成即時影片輸入串流。 |
activityStart |
(選用步驟) 標記使用者活動的開始時間。只有在停用自動 (即伺服器端) 活動偵測時，才能傳送這項資料。 |
activityEnd |
(選用步驟) 標記使用者活動的結束時間。只有在停用自動 (即伺服器端) 活動偵測功能時，才能傳送這項資料。 |
mediaResolution |
(選用步驟) 要使用的媒體解析度。如未指定，會使用 |
audioStreamEnd |
(選用步驟) 表示音訊串流已結束，例如麥克風已關閉。 只有在啟用自動活動偵測功能 (預設為啟用) 時，才應傳送這項資料。 用戶端可以傳送語音訊息，重新開啟串流。 |
text |
(選用步驟) 這些內容會構成即時文字輸入串流。 |
BidiGenerateContentServerContent
模型根據用戶端訊息產生的伺服器更新增量。
系統會盡快生成內容，但不會即時生成。用戶端可以選擇緩衝處理並即時播放。
| 欄位 | |
|---|---|
generationComplete |
僅供輸出。如為 true，表示模型已完成生成。 如果模型在生成內容時中斷，中斷的輪次中不會有「generation_complete」訊息，而是會經歷「interrupted > turn_complete」。 如果模型假設為即時播放，模型會等待播放完畢，因此 generation_complete 和 turn_complete 之間會出現延遲。 |
turnComplete |
僅供輸出。如為 true，表示模型已完成回合。只有在收到其他用戶端訊息時，系統才會開始生成回覆。請注意，啟用播放狀態回報功能後，只有在播放狀態顯示播放完畢時，系統才會發出這項事件。系統會忽略同一代裝置的後續播放狀態。 |
interrupted |
僅供輸出。如果為 true，表示用戶端訊息已中斷目前模型生成作業。如果用戶端正在即時播放內容，這就是停止並清空目前播放佇列的好時機。 |
groundingMetadata |
僅供輸出。生成內容的基礎中繼資料。 |
inputTranscription |
僅供輸出。輸入音訊轉錄稿。轉錄稿會獨立傳送，不會與其他伺服器訊息一起傳送，且無法保證順序。 |
interimInputTranscription |
僅供輸出。低延遲轉錄功能會在使用者說話時更新內容，這個欄位會經常更新。 |
outputTranscription |
僅供輸出。輸出音訊轉錄稿。這些轉錄稿是伺服器生成內容的一部分。系統會在 |
urlContextMetadata |
|
waitingForInput |
僅供輸出。如果為 true，表示模型正在等待使用者提供更多輸入內容，因此不會生成內容，例如等待使用者繼續對話。 |
interactionStatus |
僅供輸出。即時工作階段的目前活動狀態。一律與 |
modelTurn |
僅供輸出。模型在與使用者進行目前對話時生成的內容。 |
BidiGenerateContentServerMessage
BidiGenerateContent 呼叫的回應訊息。
| 欄位 | |
|---|---|
usageMetadata |
僅供輸出。回覆的使用情況中繼資料。 |
voiceActivity |
僅供輸出。音訊串流中偵測到語音活動。 |
聯集欄位 messageType。訊息類型。messageType 只能是下列其中一項： |
|
setupComplete |
僅供輸出。設定完成後，系統會傳送這則訊息，回應用戶端的 |
serverContent |
僅供輸出。模型根據用戶端訊息生成的內容。 |
toolCall |
僅供輸出。要求用戶端執行 |
toolCallCancellation |
僅供輸出。通知客戶先前核發的 |
goAway |
僅供輸出。伺服器即將中斷連線的通知。 |
sessionResumptionUpdate |
僅供輸出。更新工作階段續傳狀態。 |
BidiGenerateContentSetup
要在第一個 (且僅限第一個) BidiGenerateContentClientMessage 中傳送的訊息。包含在串流 RPC 期間套用的設定。
客戶應等待 BidiGenerateContentSetupComplete 訊息，再傳送任何其他訊息。
| 欄位 | |
|---|---|
model |
必填。模型的資源名稱。這是模型使用的 ID。 格式： |
generationConfig |
(選用步驟) 生成設定。 系統不支援下列欄位：
|
systemInstruction |
(選用步驟) 使用者為模型提供系統指令。 注意：各部分只能使用文字，且各部分的內容會分別顯示在不同段落。 |
tools[] |
(選用步驟) 模型可能用來生成下一個回覆的
|
realtimeInputConfig |
(選用步驟) 設定即時輸入內容的處理方式。 |
sessionResumption |
(選用步驟) 設定工作階段續傳機制。 如果包含，伺服器會傳送 |
contextWindowCompression |
(選用步驟) 設定內容視窗壓縮機制。 如果包含這項設定，伺服器會在脈絡超過設定長度時，自動縮減脈絡大小。 |
inputAudioTranscription |
(選用步驟) 如果設定此屬性，系統會啟用語音輸入轉錄功能。如果已設定，轉錄內容會與輸入音訊的語言一致。 |
outputAudioTranscription |
(選用步驟) 如果設定，系統會轉錄模型的音訊輸出內容。如果已設定，轉錄稿會與輸出音訊指定的語言代碼一致。 |
proactivity |
(選用步驟) 設定模型的積極程度。 模型就能主動回應輸入內容，並忽略無關的輸入內容。 |
historyConfig |
(選用步驟) 設定用戶端與伺服器之間的記錄交換作業。 |
labels |
(選用步驟) 要求的使用者定義中繼資料標籤。 (選用步驟) 標籤必須符合標準的統一 Cloud 標籤規定：- 標籤鍵開頭須為英文字母。- 標籤鍵與值的長度不得超過 63 個字元 (Unicode 碼位)，只能使用小寫英文字母、數字、底線和破折號。- 可以使用國際字元。 用法：- 匯總工具提供的安全 ID：使用 |
BidiGenerateContentSetupComplete
這個類型沒有任何欄位。
用來回應用戶端的 BidiGenerateContentSetup 訊息。
BidiGenerateContentToolCall
要求用戶端執行 functionCalls，並傳回相符 id 的回應。
| 欄位 | |
|---|---|
functionCalls[] |
僅供輸出。要執行的函式呼叫。 |
BidiGenerateContentToolCallCancellation
通知客戶先前發出的 ToolCallMessage (具有指定的 id) 不應執行，且應取消。如果這些工具呼叫產生副作用，用戶端可能會嘗試還原工具呼叫。只有在用戶端中斷伺服器回合時，才會出現這則訊息。
| 欄位 | |
|---|---|
ids[] |
僅供輸出。要取消的工具呼叫 ID。 |
BidiGenerateContentToolResponse
用戶端針對伺服器傳送的 ToolCall 產生回應。個別 FunctionResponse 物件會透過 id 欄位與對應的 FunctionCall 物件相符。
請注意，在 unary 和 server-streaming GenerateContent API 中，函式呼叫是透過交換 Content 部分進行，而在 bidi GenerateContent API 中，函式呼叫是透過這些專用訊息集進行。
| 欄位 | |
|---|---|
functionResponses[] |
(選用步驟) 函式呼叫的回應。 |
BidiGenerateContentTranscription
音訊 (輸入或輸出) 的轉錄稿。
| 欄位 | |
|---|---|
text |
轉錄稿文字。 |
languageCode |
轉錄稿的 BCP-47 語言代碼。 |
startOffset |
(選用步驟) 轉錄稿相對於音訊開頭的起始時間偏移。 |
endOffset |
(選用步驟) 轉錄稿相對於音訊開頭的結束時間偏移。 |
ContextWindowCompressionConfig
啟用脈絡窗口壓縮功能，管理模型的脈絡窗口，確保不會超過指定長度。
| 欄位 | |
|---|---|
聯集欄位 compressionMechanism。使用的背景期間壓縮機制。compressionMechanism 只能是下列其中一項： |
|
slidingWindow |
滑動視窗機制。 |
triggerTokens |
觸發脈絡窗口壓縮所需的權杖數量 (執行回合前)。 這可用於平衡品質與延遲，因為較短的脈絡窗口可能會加快模型回覆速度。不過，任何壓縮作業都會導致暫時延遲增加，因此不應頻繁觸發。 如未設定，預設值為模型內容視窗限制的 80%。這樣一來，下一個使用者要求/模型回應就會有 20% 的配額。 |
EndSensitivity
決定如何偵測語音結束。
| 列舉 | |
|---|---|
END_SENSITIVITY_UNSPECIFIED |
預設值為 END_SENSITIVITY_HIGH。 |
END_SENSITIVITY_HIGH |
自動偵測功能會更常結束語音。 |
END_SENSITIVITY_LOW |
自動偵測功能較少中斷語音。 |
GoAway
伺服器即將中斷連線的通知。
| 欄位 | |
|---|---|
timeLeft |
連線終止 (ABORTED) 前的剩餘時間。 這段時間絕不會低於模型專屬的最低時間，且會與模型的頻率限制一併指定。 |
HistoryConfig
記錄設定。
這則訊息會以 BidiGenerateContentSetup.historyConfig 的形式納入工作階段設定。設定歷史訊息的交換作業。
| 欄位 | |
|---|---|
initialHistoryInClientContent |
(選用步驟) 如果為 true，伺服器會在傳送 |
InteractionStatus
即時工作階段的不同活動狀態。這個欄位一律會與 turnComplete 一併傳送，指出伺服器是否已完成所有處理作業。
| 列舉 | |
|---|---|
INTERACTION_STATUS_UNSPECIFIED |
未指定互動狀態。 |
IN_PROGRESS |
伺服器仍在積極處理使用者輸入內容或執行背景推理。模型可能會繼續輸出內容。 |
REQUIRES_ACTION |
已淘汰：請改用 IDLE。 |
IDLE |
伺服器已完成所有處理和背景推理作業。 |
ProactivityConfig
主動式功能設定。
| 欄位 | |
|---|---|
proactiveAudio |
(選用步驟) 啟用後，模型可以拒絕回應最後一個提示。舉例來說，這可讓模型忽略與情境無關的語音，或在使用者尚未提出要求時保持靜默。 |
RealtimeInputConfig
設定 BidiGenerateContent 中的即時輸入行為。
| 欄位 | |
|---|---|
automaticActivityDetection |
(選用步驟) 如未設定，系統預設會啟用自動活動偵測功能。如果自動語音偵測功能已停用，用戶端必須傳送活動信號。 |
activityHandling |
(選用步驟) 定義活動的影響。 |
turnCoverage |
(選用步驟) 定義使用者回合中包含的輸入內容。 |
interimTranscriptTimestampEnabled |
(選用步驟) 設定臨時轉錄稿時間戳記。 |
SessionResumptionConfig
繼續工作階段設定。
這則訊息會以 BidiGenerateContentSetup.sessionResumption 的形式納入工作階段設定。如果已設定，伺服器會傳送 SessionResumptionUpdate 訊息。
| 欄位 | |
|---|---|
handle |
上一個工作階段的控制代碼。如果沒有，系統會建立新的工作階段。 工作階段控制代碼來自先前連線中的 |
SessionResumptionUpdate
更新工作階段續傳狀態。
只有在設定 BidiGenerateContentSetup.sessionResumption 時才會傳送。
| 欄位 | |
|---|---|
newHandle |
代表可繼續狀態的新控制代碼。如果 |
resumable |
如果目前的工作階段可以在這個時間點恢復，則為 True。 在工作階段的某些時間點無法繼續。例如模型正在執行函式呼叫或生成內容時。在這種狀態下繼續工作階段 (使用先前的工作階段權杖) 會導致部分資料遺失。在這些情況下， |
SlidingWindow
SlidingWindow 方法的運作方式是捨棄內容視窗開頭的內容。產生的背景資訊一律會從 USER 角色回合的開頭開始。系統指令和任何 BidiGenerateContentSetup.prefixTurns 一律會顯示在結果開頭。
| 欄位 | |
|---|---|
targetTokens |
要保留的目標權杖數量。預設值為 trigger_tokens/2。 捨棄部分內容視窗會導致暫時延遲增加，因此應校準這個值，避免頻繁的壓縮作業。 |
StartSensitivity
決定如何偵測語音的開始。
| 列舉 | |
|---|---|
START_SENSITIVITY_UNSPECIFIED |
預設值為 START_SENSITIVITY_HIGH。 |
START_SENSITIVITY_HIGH |
自動偵測功能會更常偵測到語音開始。 |
START_SENSITIVITY_LOW |
自動偵測功能會減少偵測到語音開始的時間。 |
TurnCoverage
選項：使用者回合中包含哪些輸入內容。
| 列舉 | |
|---|---|
TURN_COVERAGE_UNSPECIFIED |
如未指定，系統會根據模型選取預設行為。舉例來說，Gemini 2.5 的預設值為 TURN_INCLUDES_ONLY_ACTIVITY，Gemini 3.1 以上版本則為 TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO。 |
TURN_INCLUDES_ONLY_ACTIVITY |
包括上次輪流發言後的活動，但不包括閒置狀態 (例如音訊串流靜音)。 |
TURN_INCLUDES_ALL_INPUT |
包括自上次輪流發言以來的所有即時輸入內容，包括無活動狀態 (例如音訊串流中的無聲狀態)。 |
TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO |
包括音訊活動和上回合以來的所有影片。如果啟用自動活動偵測功能，音訊活動是指語音，不包括無聲狀態。 |
TranslationConfig
翻譯功能設定。
| 欄位 | |
|---|---|
targetLanguageCode |
必填。譯文語言。支援的值為 BCP-47 語言代碼 (例如「en」、「es」、「fr」)。 |
echoTargetLanguage |
(選用步驟) 如果為 true，模型會在說出目標語言時生成音訊，基本上會模仿輸入內容。如果設為 False，系統就不會為目標語言生成音訊。 |
UrlContextMetadata
與網址背景資訊擷取工具相關的中繼資料。
| 欄位 | |
|---|---|
urlMetadata[] |
網址背景資訊清單。 |
UsageMetadata
回覆的使用情況中繼資料。
| 欄位 | |
|---|---|
promptTokenCount |
僅供輸出。提示中的權杖數量。設定 |
cachedContentTokenCount |
提示快取部分 (快取內容) 的權杖數量 |
responseTokenCount |
僅供輸出。所有生成的候選回覆的詞元總數。 |
toolUsePromptTokenCount |
僅供輸出。工具使用提示中的權杖數量。 |
thoughtsTokenCount |
僅供輸出。思考型模型的思考過程所用的權杖數量。 |
totalTokenCount |
僅供輸出。生成要求 (提示 + 回覆候選項目) 的權杖總數。 |
promptTokensDetails[] |
僅供輸出。要求輸入內容中處理的模態清單。 |
cacheTokensDetails[] |
僅供輸出。要求輸入中快取內容的模式清單。 |
responseTokensDetails[] |
僅供輸出。回應中傳回的模態清單。 |
toolUsePromptTokensDetails[] |
僅供輸出。處理工具使用要求輸入內容的模態清單。 |
VoiceActivity
音訊串流中偵測到語音活動。
| 欄位 | |
|---|---|
type |
僅供輸出。VAD(語音活動偵測) 信號的類型。 |
audioOffset |
僅供輸出。在音訊時間中偵測到語音活動的時間，相對於音訊串流的開始時間。 |
類型
VAD 信號的類型。
| 列舉 | |
|---|---|
TYPE_UNSPECIFIED |
預設值為 UNSPECIFIED。 |
ACTIVITY_START |
句子開頭信號。 |
ACTIVITY_END |
句子結尾信號。 |
暫時性驗證權杖
呼叫 AuthTokenService.CreateToken 即可取得暫時性驗證權杖，然後透過 access_token 查詢參數或 HTTP Authorization 標頭 (權杖前置字串為「Token」)，將權杖傳遞至 GenerativeService.BidiGenerateContentConstrained。
CreateAuthTokenRequest
建立臨時驗證權杖。
| 欄位 | |
|---|---|
authToken |
必填。要建立的權杖。 |
AuthToken
要求建立臨時驗證權杖。
| 欄位 | |
|---|---|
name |
僅供輸出。ID。權杖本身。 |
expireTime |
(選用步驟) 僅限輸入。不可變動。(選用) 產生權杖後，如果使用該權杖，系統會拒絕 BidiGenerateContent 工作階段中的訊息。(Gemini 可能會在時間到期後提前關閉工作階段)。 如未設定，預設值為 30 分鐘後。如果設定這個值，必須比目前時間晚不到 20 小時。 |
newSessionExpireTime |
(選用步驟) 僅限輸入。不可變動。這項要求產生的權杖失效後，新的 Live API 工作階段將遭到拒絕。 如未設定，預設值為 60 秒。如果設定這個值，必須比目前時間晚不到 20 小時。 |
fieldMask |
(選用步驟) 僅限輸入。不可變動。如果 field_mask 為空，且沒有 如果 field_mask 為空，且 如果 field_mask 不是空白，則 |
聯集欄位 config。產生權杖的方法專屬設定。config 只能是下列其中一項： |
|
bidiGenerateContentSetup |
(選用步驟) 僅限輸入。不可變動。 |
uses |
(選用步驟) 僅限輸入。不可變動。權杖可使用的次數。如果這個值為零，系統就不會套用任何限制。繼續使用 Live API 工作階段不計入用量。如未指定，預設值為 1。 |
進一步瞭解常見類型
如要進一步瞭解常用的 API 資源類型 Blob、Content、FunctionCall、FunctionResponse、GenerationConfig、GroundingMetadata、ModalityTokenCount 和 Tool，請參閱「生成內容」。