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

工作階段設定

建立 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
  },
  "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

這個類型沒有任何欄位。

音訊轉錄設定。

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`，除了第一個以外，其他都會遭到忽略。已淘汰：請改用 `audio`、`video` 或 `text`。
`audio`	`Blob` 選用。這些會形成即時音訊輸入串流。
`video`	`Blob` 選用。這些內容會構成即時影片輸入串流。
`activityStart`	`ActivityStart` 選用。標記使用者活動的開始時間。只有在停用自動 (即伺服器端) 活動偵測功能時，系統才會傳送這項資料。
`activityEnd`	`ActivityEnd` 選用。標記使用者活動的結束時間。只有在停用自動 (即伺服器端) 活動偵測功能時，系統才會傳送這項資料。
`audioStreamEnd`	`bool` 選用。表示音訊串流已結束，例如麥克風已關閉。只有在啟用自動活動偵測功能 (預設為啟用) 時，才應傳送這項資料。用戶端可以傳送語音訊息來重新開啟串流。
`text`	`string` 選用。這些內容會構成即時文字輸入串流。

BidiGenerateContentServerContent

模型根據用戶端訊息產生的伺服器增量更新。

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

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

BidiGenerateContentServerMessage

BidiGenerateContent 呼叫的回應訊息。

欄位
`usageMetadata`	`UsageMetadata` 僅供輸出。回應的使用情況中繼資料。
聯集欄位 `messageType`。訊息類型。`messageType` 只能是下列其中一項：
`setupComplete`	`BidiGenerateContentSetupComplete` 僅供輸出。設定完成後，系統會傳送這則訊息，回應用戶端的 `BidiGenerateContentSetup` 訊息。
`serverContent`	`BidiGenerateContentServerContent` 僅供輸出。模型根據客戶訊息生成的內容。
`toolCall`	`BidiGenerateContentToolCall` 僅供輸出。要求用戶端執行 `functionCalls`，並傳回相符 `id` 的回應。
`toolCallCancellation`	`BidiGenerateContentToolCallCancellation` 僅供輸出。通知用戶端先前發出的 `ToolCallMessage` 應取消，並指定 `id`。
`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` 選用。設定內容視窗壓縮機制。如果包含這項設定，伺服器會在脈絡超過設定長度時，自動縮減脈絡大小。
`inputAudioTranscription`	`AudioTranscriptionConfig` 選用。如果設定此屬性，系統會啟用語音輸入轉錄功能。如果已設定，轉錄內容會與輸入音訊的語言一致。
`outputAudioTranscription`	`AudioTranscriptionConfig` 選用。如果設定，系統會轉錄模型的音訊輸出內容。如果已設定，轉錄稿會與輸出音訊指定的語言代碼一致。
`proactivity`	`ProactivityConfig` 選用。設定模型的積極程度。這樣一來，模型就能主動回應輸入內容，並忽略無關的輸入內容。

BidiGenerateContentSetupComplete

這個類型沒有任何欄位。

用來回應用戶端的 BidiGenerateContentSetup 訊息。

BidiGenerateContentToolCall

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

欄位

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

functionCalls[]

FunctionCall

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

BidiGenerateContentToolCallCancellation

通知用戶端先前發出的 ToolCallMessage (具有指定的 id) 不應執行，且應取消。如果這些工具呼叫產生副作用，用戶端可能會嘗試還原工具呼叫。只有在用戶端中斷伺服器回合時，才會出現這則訊息。

欄位

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

ids[]

string

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

BidiGenerateContentToolResponse

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

請注意，在 unary 和 server-streaming GenerateContent API 中，函式呼叫是透過交換 Content 部分進行，而在 bidi 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) 前的剩餘時間。

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

ProactivityConfig

主動式功能設定。

欄位

欄位
`proactiveAudio`	`bool` 選用。啟用後，模型可以拒絕回應最後一個提示。舉例來說，這可讓模型忽略語音內容，或在使用者尚未提出要求時保持靜默。

proactiveAudio

bool

選用。啟用後，模型可以拒絕回應最後一個提示。舉例來說，這可讓模型忽略語音內容，或在使用者尚未提出要求時保持靜默。

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`	使用者回合包含自上一個回合以來的所有即時輸入內容，包括閒置狀態 (例如音訊串流中的無聲狀態)。

UrlContextMetadata

與網址內容擷取工具相關的中繼資料。

欄位

urlMetadata[]

UrlMetadata

網址環境清單。

UsageMetadata

回應的使用情況中繼資料。

欄位
`promptTokenCount`	`int32` 僅供輸出。提示中的權杖數量。設定 `cachedContent` 時，這仍是有效提示的總大小，也就是說，這包括快取內容中的權杖數量。
`cachedContentTokenCount`	`int32` 提示快取部分 (快取內容) 中的權杖數量
`responseTokenCount`	`int32` 僅供輸出。所有生成的候選回覆的詞元總數。
`toolUsePromptTokenCount`	`int32` 僅供輸出。工具使用提示中的權杖數量。
`thoughtsTokenCount`	`int32` 僅供輸出。思考型模型思考時使用的詞元數量。
`totalTokenCount`	`int32` 僅供輸出。生成要求 (提示 + 回覆候選項目) 的權杖總數。
`promptTokensDetails[]`	`ModalityTokenCount` 僅供輸出。要求輸入內容中處理的模態清單。
`cacheTokensDetails[]`	`ModalityTokenCount` 僅供輸出。要求輸入中快取內容的模態清單。
`responseTokensDetails[]`	`ModalityTokenCount` 僅供輸出。回應中傳回的模態清單。
`toolUsePromptTokensDetails[]`	`ModalityTokenCount` 僅供輸出。處理工具使用要求輸入內容的模態清單。

暫時性驗證權杖

您可以呼叫 AuthTokenService.CreateToken 取得臨時驗證權杖，然後搭配 GenerativeService.BidiGenerateContentConstrained 使用，方法是將權杖傳遞至 access_token 查詢參數，或傳遞至 HTTP Authorization 標頭，並加上「Token」前置字串。

CreateAuthTokenRequest

建立臨時驗證權杖。

欄位

欄位
`authToken`	`AuthToken` 必填。要建立的權杖。

authToken

AuthToken

必填。要建立的權杖。

AuthToken

要求建立臨時驗證權杖。

欄位
`name`	`string` 僅供輸出。ID。權杖本身。
`expireTime`	`Timestamp` 選用。僅供輸入。不可變更。這個選用時間過後，如果使用產生的符記，系統就會拒絕 BidiGenerateContent 工作階段中的訊息。(Gemini 可能會在時間到期後預先關閉工作階段)。如未設定，預設值為 30 分鐘。設定的值必須在 20 小時內。
`newSessionExpireTime`	`Timestamp` 選用。僅供輸入。不可變更。使用這項要求產生的權杖建立新的 Live API 工作階段時，系統會拒絕要求，這個時間就是權杖的到期時間。如未設定，未來預設值為 60 秒。設定的值必須在 20 小時內。
`fieldMask`	`FieldMask` 選用。僅供輸入。不可變更。如果 field_mask 為空，且沒有 `bidiGenerateContentSetup`，則有效 `BidiGenerateContentSetup` 訊息會取自 Live API 連線。如果 field_mask 為空，且存在 `bidiGenerateContentSetup` is，則有效 `BidiGenerateContentSetup` 訊息會完全取自這項要求中的 `bidiGenerateContentSetup`。系統會忽略 Live API 連線的設定訊息。如果 field_mask 不為空白，則 `bidiGenerateContentSetup` 中的對應欄位會覆寫 Live API 連線中設定訊息的欄位。
聯集欄位 `config`。產生權杖的方法專屬設定。`config` 只能是下列其中一項：
`bidiGenerateContentSetup`	`BidiGenerateContentSetup` 選用。僅供輸入。不可變更。`BidiGenerateContent` 專用的設定。
`uses`	`int32` 選用。僅供輸入。不可變更。代幣可使用的次數。如果這個值為零，系統就不會套用任何限制。繼續使用 Live API 工作階段不會計入用量。如未指定，則預設值為 1。

常見類型的詳細資訊

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