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 訊息中的其他欄位。(JSON 中不會表示 messageType 聯集，因此欄位會顯示在訊息頂層)。
訊息和活動
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」。 如果模型假設為即時播放，則生成完成和回合完成之間會出現延遲，這是因為模型會等待播放完成。 |
turnComplete |
僅供輸出。如為 true，表示模型已完成輪流對話。系統只會在收到其他用戶端訊息時開始生成。請注意，啟用播放狀態回報功能後，只有在播放狀態顯示播放完畢時，系統才會發出這項事件。系統會忽略同一代裝置的後續播放狀態。 |
interrupted |
僅供輸出。如果為 true，表示用戶端訊息已中斷目前模型生成作業。如果用戶端正在即時播放內容，這就是停止並清空目前播放佇列的好時機。 |
groundingMetadata |
僅供輸出。生成內容的基礎中繼資料。 |
inputTranscription |
僅供輸出。輸入音訊轉錄稿。轉錄稿會與其他伺服器訊息分開傳送，且無法保證順序。 |
interimInputTranscription |
僅供輸出。低延遲轉錄功能會在使用者說話時更新內容，這個欄位會經常更新。 |
outputTranscription |
僅供輸出。輸出音訊轉錄稿。這些轉錄稿是伺服器生成輸出內容的一部分。系統會在 |
urlContextMetadata |
|
waitingForInput |
僅供輸出。如果為 true，表示模型正在等待使用者提供更多輸入內容，因此不會生成內容，例如預期使用者會繼續對話。 |
speechState |
僅供輸出。已淘汰：請改用 VoiceActivity。 指出 |
interactionStatus |
僅供輸出。即時工作階段的目前活動狀態。一律與 |
modelTurn |
僅供輸出。模型在與使用者進行目前對話時生成的內容。 |
BidiGenerateContentServerMessage
BidiGenerateContent 呼叫的回應訊息。
| 欄位 | |
|---|---|
usageMetadata |
僅供輸出。有關回覆的使用情況中繼資料。 |
聯集欄位 messageType。訊息類型。messageType 只能是下列其中一項： |
|
setupComplete |
僅供輸出。設定完成後，系統會傳送這則訊息，回應用戶端的 |
serverContent |
僅供輸出。模型根據用戶端訊息生成的內容。 |
toolCall |
僅供輸出。要求用戶端執行 |
toolCallCancellation |
僅供輸出。通知用戶端應取消先前發出的 |
goAway |
僅供輸出。伺服器即將中斷連線的通知。 |
sessionResumptionUpdate |
僅供輸出。更新工作階段續傳狀態。 |
BidiGenerateContentSetup
要在第一個 (也是唯一一個) BidiGenerateContentClientMessage 中傳送的訊息。包含在串流 RPC 期間套用的設定。
用戶端應等待 BidiGenerateContentSetupComplete 訊息，再傳送任何其他訊息。
| 欄位 | |
|---|---|
model |
必填。模型的資源名稱。這是模型使用的 ID。 格式： |
generationConfig |
(選用步驟) 生成設定。 系統不支援下列欄位：
|
systemInstruction |
(選用步驟) 使用者為模型提供系統指令。 注意：各部分只能使用文字，且各部分的內容會分別顯示在不同段落。 |
tools[] |
(選用步驟)
|
realtimeInputConfig |
(選用步驟) 設定即時輸入的處理方式。 |
sessionResumption |
(選用步驟) 設定工作階段續傳機制。 如果包含這項資訊，伺服器就會傳送 |
contextWindowCompression |
(選用步驟) 設定內容視窗壓縮機制。 如果包含這項設定，伺服器會在脈絡超過設定長度時，自動縮減脈絡大小。 |
inputAudioTranscription |
(選用步驟) 如果設定此屬性，系統會啟用語音輸入轉錄功能。如果已設定，轉錄內容會與輸入音訊的語言一致。 |
outputAudioTranscription |
(選用步驟) 如果設定為 true，系統會轉錄模型的音訊輸出內容。如果已設定，轉錄稿會與輸出音訊指定的語言代碼一致。 |
proactivity |
(選用步驟) 設定模型的積極程度。 模型就能主動回應輸入內容，並忽略無關的輸入內容。 |
historyConfig |
(選用步驟) 設定用戶端與伺服器之間的記錄交換。 |
BidiGenerateContentSetupComplete
這個類型沒有任何欄位。
用來回應用戶端的 BidiGenerateContentSetup 訊息。
BidiGenerateContentToolCall
要求用戶端執行 functionCalls，並傳回相符 id 的回應。
| 欄位 | |
|---|---|
functionCalls[] |
僅供輸出。要執行的函式呼叫。 |
BidiGenerateContentToolCallCancellation
通知用戶端先前發出的 ToolCallMessage (具有指定的 id) 不應執行，且應取消。如果這些工具呼叫產生副作用，用戶端可能會嘗試還原工具呼叫。只有在用戶端中斷伺服器回合時，才會出現這則訊息。
| 欄位 | |
|---|---|
ids[] |
僅供輸出。要取消的工具呼叫 ID。 |
BidiGenerateContentToolResponse
用戶端針對伺服器傳送的 ToolCall 產生回應。個別 FunctionResponse 物件會透過 id 欄位與對應的 FunctionCall 物件相符。
請注意，在單元和伺服器串流 GenerateContent API 中，函式呼叫是透過交換 Content 部分進行，而在雙向 GenerateContent API 中，函式呼叫是透過這些專用訊息集進行。
| 欄位 | |
|---|---|
functionResponses[] |
(選用步驟) 函式呼叫的回應。 |
BidiGenerateContentTranscription
音訊 (輸入或輸出) 的轉錄稿。
| 欄位 | |
|---|---|
text |
轉錄稿文字。 |
languageCode |
轉錄稿的 BCP-47 語言代碼。 |
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，伺服器會在傳送 |
ProactivityConfig
主動式功能設定。
| 欄位 | |
|---|---|
proactiveAudio |
(選用步驟) 啟用後，模型可以拒絕回應最後一個提示。舉例來說，這可讓模型忽略語音內容以外的語音，或在使用者尚未提出要求時保持靜音。 |
RealtimeInputConfig
設定 BidiGenerateContent 中的即時輸入行為。
| 欄位 | |
|---|---|
automaticActivityDetection |
(選用步驟) 如果未設定，系統預設會啟用自動活動偵測功能。如果停用自動語音偵測功能，用戶端必須傳送活動信號。 |
activityHandling |
(選用步驟) 定義活動的影響。 |
turnCoverage |
(選用步驟) 定義使用者回合中包含的輸入內容。 |
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[] |
僅供輸出。處理工具使用要求輸入內容的模態清單。 |
暫時性驗證權杖
呼叫 AuthTokenService.CreateToken 即可取得暫時性驗證權杖，然後透過 GenerativeService.BidiGenerateContentConstrained 使用權杖，方法是將權杖傳遞至 access_token 查詢參數，或傳遞至 HTTP Authorization 標頭，並加上「Token」前置字串。
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，請參閱「生成內容」。