Multimodal Live API

Multimodal Live API 可讓您透過 Gemini 進行低延遲的雙向語音和視訊互動。使用多模態即時 API，您可以為使用者提供自然流暢的語音對話體驗，並讓使用者能夠透過語音指令中斷模型的回應。這個模型可以處理文字、音訊和影片輸入內容，並提供文字和音訊輸出內容。

功能

Multimodal Live API 提供下列主要功能：

• 多模態：模型可看、聽和說。
• 低延遲即時互動：提供快速回應。
• 工作階段記憶體：模型會保留單一工作階段內所有互動的記憶體，喚回先前聽到或看到的資訊。
• 支援函式呼叫、程式碼執行和搜尋做為工具：可與外部服務和資料來源整合。
• 自動語音活動偵測 (VAD)：模型可準確辨識使用者何時開始和停止說話。這可讓使用者以自然的對話方式互動，並隨時中斷模型。

您可以在 Google AI Studio 中試用 Multimodal Live API。

開始使用

Multimodal Live API 是使用 WebSockets 的具狀態 API。

本節將舉例說明如何使用 Python 3.9 以上版本的 Multimodal Live API 進行文字轉文字產生作業。

安裝 Gemini API 程式庫

如要安裝 google-genai 套件，請使用下列 pip 指令：

!pip3 install google-genai

匯入依附元件

如何匯入依附元件：

from google import genai

收發簡訊

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model_id = "gemini-2.0-flash-exp"
config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model_id, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send(message, end_of_turn=True)

            async for response in session.receive():
                if response.text is None:
                    continue
                print(response.text, end="")

if __name__ == "__main__":
    asyncio.run(main())

整合指南

本節說明如何整合 Multimodal Live API。

工作階段

工作階段代表用戶端與 Gemini 伺服器之間的單一 WebSocket 連線。

用戶端啟動新連線後，工作階段可與伺服器交換訊息，以便執行下列操作：

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

連線後，系統會在第一則訊息中傳送工作階段設定。工作階段設定包含模型、產生參數、系統指示和工具。

請參考以下設定範例：

{​​
  "model": string,
  "generation_config": {​
    "candidate_count": integer,
    "max_output_tokens": integer,
    "temperature": number,
    "top_p": number,
    "top_k": integer,
    "presence_penalty": number,
    "frequency_penalty": number,
    "response_modalities": string,
    "speech_config":object
  },

  "system_instruction": "",
  "tools":[]
}

詳情請參閱 BidiGenerateContentSetup。

傳送訊息

訊息是透過 WebSocket 連線交換的 JSON 格式字串。

如要傳送訊息，用戶端必須透過已開啟的 WebSocket 連線，以 JSON 格式字串傳送支援的用戶端訊息。

支援的用戶端訊息

請參閱下表中支援的用戶端訊息：

接收訊息

如要接收 Gemini 的訊息，請接聽 WebSocket 的「message」事件，然後根據支援的伺服器訊息定義剖析結果。

請參閱以下資訊：

ws.addEventListener("message", async (evt) => {
  if (evt.data instanceof Blob) {
    // Process the received data (audio, video, etc.)
  } else {
    // Process JSON response
  }
});

支援的伺服器訊息

請參閱下表中支援的伺服器訊息：

分批更新內容

使用增量更新功能傳送文字輸入內容、建立或還原工作階段內容。如果是短時間的內容，您可以傳送逐向互動，以代表確切的事件順序。對於較長的脈絡，建議提供單一訊息摘要，以便釋出脈絡視窗，供後續互動使用。

請參閱以下內容訊息範例：

{
  "client_content": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turn_complete": true
  }
}

請注意，雖然內容部分可以是 functionResponse 類型，但 BidiGenerateContentClientContent 不應用於對模型發出的函式呼叫提供回應。請改用 BidiGenerateContentToolResponse。BidiGenerateContentClientContent 應僅用於建立先前的內容脈絡，或提供對話的文字輸入內容。

串流音訊和影片

函式呼叫

您必須在工作階段開始時宣告所有函式，方法是將工具定義傳送至 BidiGenerateContentSetup 訊息。

請參閱函式呼叫教學課程，進一步瞭解函式呼叫。

模型可從單一提示產生多個函式呼叫，以及連結輸出的必要程式碼。這個程式碼會在沙箱環境中執行，產生後續 BidiGenerateContentToolCall 訊息。執行作業會暫停，直到每個函式呼叫的結果可用為止，藉此確保依序處理。

用戶端應回覆 BidiGenerateContentToolResponse。

音訊輸入和輸出會對模型使用函式呼叫的功能造成負面影響。

音訊格式

Multimodal Live API 支援下列音訊格式：

• 輸入音訊格式：原始 16 位元 PCM 音訊，位元深度為 16 位元，取樣率為 16 kHz 小端序
• 輸出音訊格式：24 kHz 小端序的原始 16 位元 PCM 音訊

系統指示

您可以提供系統指令，進一步控制模型的輸出內容，並指定音訊回應的語氣和情緒。

系統指令會在互動開始前加入提示，並在整個工作階段持續生效。

系統指示只能在工作階段開始時設定，也就是在初始連線後立即設定。如要在工作階段期間為模型提供更多輸入內容，請使用增量內容更新功能。

干擾

使用者隨時可以中斷模型的輸出內容。當語音活動偵測 (VAD) 偵測到中斷情形時，系統會取消並捨棄目前的產生作業。工作階段記錄中只會保留已傳送至用戶端的資訊。接著，伺服器會傳送 BidiGenerateContentServerContent 訊息，回報中斷情形。

此外，Gemini 伺服器會捨棄任何待處理的函式呼叫，並傳送含有取消呼叫 ID 的 BidiGenerateContentServerContent 訊息。

語音

Multimodal Live API 支援以下語音：Aode、Charon、Fenrir、Kore 和 Puck。

如要指定語音，請在 工作階段設定中，在 speech_config 物件中設定 voice_name。

請參閱以下 speech_config 物件的 JSON 表示法：

{
  "voice_config": {
    "prebuilt_voice_config ": {
      "voice_name": <var>VOICE_NAME</var>
    }
  }
}

限制

規劃專案時，請考量 Multimodal Live API 和 Gemini 2.0 的下列限制。

用戶端驗證

Multimodal Live API 只提供伺服器對伺服器驗證，不建議直接用於用戶端。用戶端輸入內容應透過中介應用程式伺服器轉送，以便透過 Multimodal Live API 進行安全驗證。

如果是網頁和行動應用程式，建議您使用Daily合作夥伴提供的整合服務。

對話記錄

雖然模型會追蹤工作階段中的互動，但不會儲存對話記錄。工作階段結束時，系統會清除對應的上下文。

為了還原先前的會話，或為模型提供使用者互動的歷史背景資訊，應用程式應保留自己的對話記錄，並使用 BidiGenerateContentClientContent 訊息，在新的會話開始時傳送這項資訊。

工作階段持續時間上限

音訊工作階段持續時間上限為 15 分鐘，音訊和視訊則為 2 分鐘。如果工作階段時間長度超過限制，連線就會終止。

模型也受限於內容大小。與視訊和音訊串流一併傳送大量內容，可能會導致工作階段提早終止。

語音活動偵測 (VAD)

模型會自動對連續音訊輸入串流執行語音活動偵測 (VAD)。VAD 一律會啟用，且其參數無法設定。

符記數

不支援符記數量。

頻率限制

適用下列頻率限制：

• 每個 API 金鑰 3 個並行工作階段
• 每分鐘 400 萬個符記

訊息和事件

進一步瞭解常見類型

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