Gemini 2.5 Pro 預先發布版現已可供正式使用！瞭解詳情

本頁面由 Cloud Translation API 翻譯而成。

Live API - WebSockets API reference

Live API 是使用 WebSockets 的具狀態 API。本節將進一步說明 WebSockets API。

工作階段

WebSocket 連線會在用戶端和 Gemini 伺服器之間建立工作階段。用戶端啟動新連線後，工作階段可以與伺服器交換訊息，以便執行下列操作：

將文字、音訊或影片傳送至 Gemini 伺服器。
接收 Gemini 伺服器傳送的音訊、文字或函式呼叫要求。

WebSocket 連線

如要啟動工作階段，請連線至這個 WebSocket 端點：

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent

工作階段設定

連線後的初始訊息會設定工作階段設定，包括模型、產生參數、系統指示和工具。

您可以在工作階段中變更模型以外的設定參數。

請參閱以下設定範例。請注意，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
  },
  "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 訊息中恰好一個其他欄位。(messageType 聯集並未以 JSON 表示，因此欄位會顯示在訊息的頂層)。

訊息和事件

ActivityEnd

這個類型沒有任何欄位。

標示使用者活動結束。

ActivityHandling

處理使用者活動的不同方式。

列舉
`ACTIVITY_HANDLING_UNSPECIFIED`	如果未指定，則預設行為為 `START_OF_ACTIVITY_INTERRUPTS`。
`START_OF_ACTIVITY_INTERRUPTS`	如果為 true，活動開始會中斷模型的回應 (也稱為「插入」)。模型的目前回應會在中斷時中止。此為預設行為。
`NO_INTERRUPTION`	模型的回應不會中斷。

ActivityStart

這個類型沒有任何欄位。

標示使用者活動的開始時間。

AudioTranscriptionConfig

這個類型沒有任何欄位。

音訊轉錄設定。

AutomaticActivityDetection

設定自動偵測活動功能。

欄位
`disabled`	`bool` 選用設定。啟用此設定 (預設) 後，系統會將偵測到的語音和文字輸入內容視為活動。如果停用，用戶端就必須傳送活動信號。
`startOfSpeechSensitivity`	`StartSensitivity` 選用設定。決定系統偵測語音的可能性。
`prefixPaddingMs`	`int32` 選用設定。系統偵測到語音後，需要等待多久才能提交語音開始時間。這個值越低，語音開始偵測的靈敏度就越高，可辨識的語音越短。不過，這也會增加偽陽性的機率。
`endOfSpeechSensitivity`	`EndSensitivity` 選用設定。判斷系統偵測到語音結束的可能性。
`silenceDurationMs`	`int32` 選用設定。系統偵測到非語音 (例如靜音) 的必要時間長度，之後系統才會提交語音結束信號。這個值越大，系統就越能延長不中斷使用者活動的語音間隔，但這會增加模型的延遲時間。

BidiGenerateContentClientContent

從用戶端傳送的目前對話內容增量更新。此處的所有內容都會無條件附加至對話記錄，並用於提示模型產生內容。

這裡的訊息會中斷任何目前的模型產生作業。

欄位

欄位
`turns[]`	`Content` 選用設定。附加至與模型目前對話的內容。對於單次查詢，這會是單一例項。對於多輪查詢，這是重複欄位，其中包含對話記錄和最新要求。
`turnComplete`	`bool` 選用設定。如果為 true，表示伺服器內容產生作業應從目前累積的提示開始。否則，伺服器會等待其他訊息，然後才開始產生。

turns[]

Content

選用設定。附加至與模型目前對話的內容。

對於單次查詢，這會是單一例項。對於多輪查詢，這是重複欄位，其中包含對話記錄和最新要求。

turnComplete

bool

選用設定。如果為 true，表示伺服器內容產生作業應從目前累積的提示開始。否則，伺服器會等待其他訊息，然後才開始產生。

BidiGenerateContentRealtimeInput

即時傳送的使用者輸入內容。

系統會將不同型態 (音訊、影片和文字) 處理為並行串流。我們無法保證這些串流的順序。

與 BidiGenerateContentClientContent 相比，這個選項具有以下幾個差異：

可持續傳送，不會中斷模型產生作業。
如果需要在 BidiGenerateContentClientContent 和 BidiGenerateContentRealtimeInput 之間交錯混合資料，伺服器會嘗試最佳化，以便提供最佳回應，但無法保證一定能成功。
不需明確指定輪到誰說話，而是根據使用者活動 (例如說話結束) 來判斷。
即使在回合結束前，系統也會逐漸處理資料，以便快速開始處理模型的回覆。

欄位
`mediaChunks[]`	`Blob` 選用設定。媒體輸入內容的內嵌位元組資料。系統不支援多個 `mediaChunks`，除了第一個 `mediaChunks` 外，其他都會遭到忽略。已淘汰：請改用 `audio`、`video` 或 `text`。
`audio`	`Blob` 選用設定。這些資料會形成即時音訊輸入串流。
`video`	`Blob` 選用設定。這些資料會形成即時影片輸入串流。
`activityStart`	`ActivityStart` 選用設定。標示使用者活動的開始時間。只有在自動 (即伺服器端) 活動偵測功能停用時，才能傳送這項資料。
`activityEnd`	`ActivityEnd` 選用設定。標示使用者活動結束。只有在自動 (即伺服器端) 活動偵測功能停用時，才能傳送這項資料。
`audioStreamEnd`	`bool` 選用設定。表示音訊串流已結束，例如麥克風已關閉。只有在啟用自動活動偵測功能 (預設值) 時，才應傳送這項事件。用戶端可以傳送語音訊息，重新開啟串流。
`text`	`string` 選用設定。這些資料會形成即時文字輸入串流。

BidiGenerateContentServerContent

模型為了回應用戶端訊息而產生的伺服器增量更新。

系統會盡快產生內容，但不會即時產生。用戶端可以選擇緩衝並即時播放。

欄位
`generationComplete`	`bool` 僅供輸出。如果為 true，表示模型已完成產生。當模型在產生期間遭到中斷時，中斷回合中不會顯示「generation_complete」訊息，而是會經過「interrupted > turn_complete」。當模型假設即時播放時，在 generation_complete 和 turn_complete 之間會出現延遲，這是因為模型必須等待播放作業完成。
`turnComplete`	`bool` 僅供輸出。如果為 true，表示模型已完成其回合。系統只會在回應其他用戶端訊息時開始產生內容。
`interrupted`	`bool` 僅供輸出。如果為 true，表示用戶端訊息已中斷目前的模型產生作業。如果用戶端正在即時播放內容，這就是停止並清空目前播放佇列的最佳訊號。
`groundingMetadata`	`GroundingMetadata` 僅供輸出。為產生的內容建立基礎中繼資料。
`outputTranscription`	`BidiGenerateContentTranscription` 僅供輸出。輸出音訊轉錄內容。轉錄內容會獨立於其他伺服器訊息傳送，且無法保證順序，尤其是 `serverContent` 和這個 `outputTranscription` 之間。
`modelTurn`	`Content` 僅供輸出。模型在與使用者進行目前對話時產生的內容。

BidiGenerateContentServerMessage

BidiGenerateContent 呼叫的回應訊息。

欄位
`usageMetadata`	`UsageMetadata` 僅供輸出。回應的使用中繼資料。
聯集欄位 `messageType`。訊息類型。`messageType` 只能是下列其中一項：
`setupComplete`	`BidiGenerateContentSetupComplete` 僅供輸出。在設定完成後，回覆用戶端傳送的 `BidiGenerateContentSetup` 訊息時傳送。
`serverContent`	`BidiGenerateContentServerContent` 僅供輸出。模型回覆用戶端訊息時產生的內容。
`toolCall`	`BidiGenerateContentToolCall` 僅供輸出。要求用戶端執行 `functionCalls`，並傳回與相符 `id` 的回應。
`toolCallCancellation`	`BidiGenerateContentToolCallCancellation` 僅供輸出。通知用戶端，先前以指定 `id` 發出的 `ToolCallMessage` 應取消。
`goAway`	`GoAway` 僅供輸出。通知伺服器即將中斷連線。
`sessionResumptionUpdate`	`SessionResumptionUpdate` 僅供輸出。更新工作階段恢復狀態。

BidiGenerateContentSetup

要在第一個 (且僅在第一個) BidiGenerateContentClientMessage 中傳送的訊息。包含在串流 RPC 期間套用的設定。

用戶端應等待 BidiGenerateContentSetupComplete 訊息，再傳送其他訊息。

欄位
`model`	`string` 必要欄位。模型的資源名稱。這個值會做為模型的 ID 使用。格式：`models/{model}`
`generationConfig`	`GenerationConfig` 選用設定。產生設定。系統不支援下列欄位： `responseLogprobs` `responseMimeType` `logprobs` `responseSchema` `stopSequence` `routingConfig` `audioTimestamp`
`systemInstruction`	`Content` 選用設定。使用者為模型提供系統指示。注意：部分內容只能使用文字，且每個部分的內容都會放在個別段落中。
`tools[]`	`Tool` 選用設定。模型可能用來產生下一個回應的 `Tools` 清單。 `Tool` 是一段程式碼，可讓系統與外部系統互動，執行模型知識和範圍以外的動作或一組動作。
`realtimeInputConfig`	`RealtimeInputConfig` 選用設定。設定即時輸入內容的處理方式。
`sessionResumption`	`SessionResumptionConfig` 選用設定。設定工作階段恢復機制。如果包含此參數，伺服器就會傳送 `SessionResumptionUpdate` 訊息。
`contextWindowCompression`	`ContextWindowCompressionConfig` 選用設定。設定內容視窗壓縮機制。如果包含，當脈絡超過設定長度時，伺服器會自動縮減脈絡大小。
`outputAudioTranscription`	`AudioTranscriptionConfig` 選用設定。如果設為 true，系統就會啟用模型的音訊輸出轉錄功能。轉錄內容會與輸出音訊的語言代碼相符 (如果已設定的話)。

BidiGenerateContentSetupComplete

這個類型沒有任何欄位。

回覆用戶端傳送的 BidiGenerateContentSetup 訊息。

BidiGenerateContentToolCall

要求用戶端執行 functionCalls，並傳回與相符 id 的回應。

欄位

欄位
`functionCalls[]`	`FunctionCall` 僅供輸出。要執行的函式呼叫。

functionCalls[]

FunctionCall

僅供輸出。要執行的函式呼叫。

BidiGenerateContentToolCallCancellation

通知用戶端，先前發出的 ToolCallMessage 含有指定的 id，因此不應執行，應予以取消。如果這些工具呼叫有副作用，用戶端可能會嘗試撤銷工具呼叫。只有在用戶端中斷伺服器轉換時，才會顯示這則訊息。

欄位

欄位
`ids[]`	`string` 僅供輸出。要取消的工具呼叫 ID。

ids[]

string

僅供輸出。要取消的工具呼叫 ID。

BidiGenerateContentToolResponse

用戶端針對從伺服器收到的 ToolCall 產生回應。個別 FunctionResponse 物件會透過 id 欄位與相應的 FunctionCall 物件配對。

請注意，在單向和伺服器串流 GenerateContent API 中，函式呼叫會透過交換 Content 部分，而在雙向 GenerateContent API 中，函式呼叫會透過這些專用訊息組進行。

欄位

欄位
`functionResponses[]`	`FunctionResponse` 選用設定。函式呼叫的回應。

functionResponses[]

FunctionResponse

選用設定。函式呼叫的回應。

BidiGenerateContentTranscription

音訊轉錄 (輸入或輸出)。

欄位

欄位
`text`	`string` 轉錄稿文字。

text

string

轉錄稿文字。

ContextWindowCompressionConfig

啟用脈絡窗口壓縮功能，這是一種管理模型脈絡窗口的機制，可確保脈絡窗口不超過指定長度。

欄位

欄位
聯集欄位 `compressionMechanism`。使用的背景視窗壓縮機制。`compressionMechanism` 只能是下列其中一項：
`slidingWindow`	`SlidingWindow` 滑動式視窗機制。
`triggerTokens`	`int64` 觸發內容回溯期壓縮功能所需的符記數量 (在執行回合之前)。這可用於平衡品質與延遲時間，因為較短的脈絡視窗可能會導致模型回應速度加快。不過，任何壓縮作業都會導致暫時性延遲增加，因此不應頻繁觸發。如未設定，預設值為模型的上下文視窗限制的 80%。這樣可將 20% 的記憶體留給下一個使用者要求/模型回應。

聯集欄位 compressionMechanism。使用的背景視窗壓縮機制。compressionMechanism 只能是下列其中一項：

slidingWindow

SlidingWindow

滑動式視窗機制。

triggerTokens

int64

觸發內容回溯期壓縮功能所需的符記數量 (在執行回合之前)。

這可用於平衡品質與延遲時間，因為較短的脈絡視窗可能會導致模型回應速度加快。不過，任何壓縮作業都會導致暫時性延遲增加，因此不應頻繁觸發。

如未設定，預設值為模型的上下文視窗限制的 80%。這樣可將 20% 的記憶體留給下一個使用者要求/模型回應。

EndSensitivity

決定如何偵測語音結束。

列舉
`END_SENSITIVITY_UNSPECIFIED`	預設值為 END_SENSITIVITY_HIGH。
`END_SENSITIVITY_HIGH`	自動偵測功能會更頻繁地結束語音內容。
`END_SENSITIVITY_LOW`	自動偵測功能會較少結束語音內容。

GoAway

通知伺服器即將中斷連線。

欄位

欄位
`timeLeft`	`Duration` 連線會以 ABORTED 的狀態終止前，剩餘的時間。這項時間長度絕不會低於模型專屬的最小值，後者會與模型的速率限制一併指定。

timeLeft

Duration

連線會以 ABORTED 的狀態終止前，剩餘的時間。

這項時間長度絕不會低於模型專屬的最小值，後者會與模型的速率限制一併指定。

RealtimeInputConfig

在 BidiGenerateContent 中設定即時輸入行為。

欄位

欄位
`automaticActivityDetection`	`AutomaticActivityDetection` 選用設定。如未設定，系統會預設啟用自動活動偵測功能。如果停用自動語音偵測功能，用戶端就必須傳送活動信號。
`activityHandling`	`ActivityHandling` 選用設定。定義活動的效果。
`turnCoverage`	`TurnCoverage` 選用設定。定義使用者回合中包含哪些輸入內容。

automaticActivityDetection

AutomaticActivityDetection

選用設定。如未設定，系統會預設啟用自動活動偵測功能。如果停用自動語音偵測功能，用戶端就必須傳送活動信號。

activityHandling

ActivityHandling

選用設定。定義活動的效果。

turnCoverage

TurnCoverage

選用設定。定義使用者回合中包含哪些輸入內容。

SessionResumptionConfig

工作階段恢復設定。

這則訊息會以 BidiGenerateContentSetup.sessionResumption 的形式納入工作階段設定。如果已設定，伺服器會傳送 SessionResumptionUpdate 訊息。

欄位

欄位
`handle`	`string` 前一個工作階段的句柄。如果不存在，則會建立新工作階段。工作階段句柄來自先前連線中的 `SessionResumptionUpdate.token` 值。

handle

string

前一個工作階段的句柄。如果不存在，則會建立新工作階段。

工作階段句柄來自先前連線中的 SessionResumptionUpdate.token 值。

SessionResumptionUpdate

更新工作階段恢復狀態。

只有在設定 BidiGenerateContentSetup.sessionResumption 時才會傳送。

欄位

欄位
`newHandle`	`string` 代表可繼續執行的狀態的新句柄。如果 `resumable`=false，則為空值。
`resumable`	`bool` 如果目前的工作階段可在此時恢復，則為 True。在某些工作階段中，無法繼續執行。例如模型執行函式呼叫或產生函式時。在這種狀態下，使用先前的會話方塊繼續工作階段，會導致部分資料遺失。在這些情況下，`newHandle` 會是空白，`resumable` 會為 false。

newHandle

string

代表可繼續執行的狀態的新句柄。如果 resumable=false，則為空值。

resumable

bool

如果目前的工作階段可在此時恢復，則為 True。

在某些工作階段中，無法繼續執行。例如模型執行函式呼叫或產生函式時。在這種狀態下，使用先前的會話方塊繼續工作階段，會導致部分資料遺失。在這些情況下，newHandle 會是空白，resumable 會為 false。

SlidingWindow

SlidingWindow 方法會捨棄結構定義視窗開頭的內容。產生的結果一律會從 USER 角色輪到時開始。系統指示和任何 BidiGenerateContentSetup.prefixTurns 一律會保留在結果開頭。

欄位

欄位
`targetTokens`	`int64` 要保留的符記目標數量。預設值為 trigger_tokens/2。捨棄部分內容區塊會導致暫時性延遲增加，因此應調整這個值，避免頻繁執行壓縮作業。

targetTokens

int64

要保留的符記目標數量。預設值為 trigger_tokens/2。

捨棄部分內容區塊會導致暫時性延遲增加，因此應調整這個值，避免頻繁執行壓縮作業。

StartSensitivity

決定如何偵測語音開始。

列舉
`START_SENSITIVITY_UNSPECIFIED`	預設值為 START_SENSITIVITY_HIGH。
`START_SENSITIVITY_HIGH`	自動偵測功能會更頻繁地偵測語音開始時間。
`START_SENSITIVITY_LOW`	自動偵測功能會減少偵測語音開始的次數。

TurnCoverage

關於使用者回合中納入哪些輸入內容的選項。

列舉
`TURN_COVERAGE_UNSPECIFIED`	如果未指定，則預設行為為 `TURN_INCLUDES_ONLY_ACTIVITY`。
`TURN_INCLUDES_ONLY_ACTIVITY`	使用者回合只包含上一個回合以來的活動，不包含閒置狀態 (例如音訊串流中的靜默)。此為預設行為。
`TURN_INCLUDES_ALL_INPUT`	使用者回合包含上次回合後的所有即時輸入內容，包括閒置狀態 (例如音訊串流中的靜音)。

UsageMetadata

回應的使用中繼資料。

欄位
`promptTokenCount`	`int32` 僅供輸出。提示中的符記數量。設定 `cachedContent` 時，這仍是有效提示的總大小，也就是包含快取內容中的符記數量。
`cachedContentTokenCount`	`int32` 提示快取內容中的符記數量
`responseTokenCount`	`int32` 僅供輸出。所有產生的回覆候選項中，符號的總數。
`toolUsePromptTokenCount`	`int32` 僅供輸出。工具使用提示中出現的符記數量。
`thoughtsTokenCount`	`int32` 僅供輸出。思考模型的想法符記數。
`totalTokenCount`	`int32` 僅供輸出。產生要求 (提示 + 候選回覆) 的權杖總數。
`promptTokensDetails[]`	`ModalityTokenCount` 僅供輸出。在要求輸入內容中處理的模式清單。
`cacheTokensDetails[]`	`ModalityTokenCount` 僅供輸出。要求輸入內容中快取內容的模式清單。
`responseTokensDetails[]`	`ModalityTokenCount` 僅供輸出。在回應中傳回的模式清單。
`toolUsePromptTokensDetails[]`	`ModalityTokenCount` 僅供輸出。系統為工具使用要求輸入內容處理的模式清單。

進一步瞭解常見類型

如要進一步瞭解常用的 API 資源類型 Blob、Content、FunctionCall、FunctionResponse、GenerationConfig、GroundingMetadata、ModalityTokenCount 和 Tool，請參閱「產生內容」。