Live API 參考資料

透過 Live API，您可以與 Gemini 展開低延遲的雙向語音/視訊互動。使用 Live API，您可以為使用者提供自然、類似人類語音的對話體驗，並讓使用者透過語音指令中斷模型的回覆。Live API 可處理文字、音訊和影片輸入內容，並提供文字和音訊輸出內容。

如要進一步瞭解 Live API，請參閱這篇文章。

功能

Live API 包含下列主要功能：

• 多模態：模型可以看、聽和說話。
• 低延遲即時互動：模型可快速回應。
• 工作階段記憶：模型會保留單一工作階段中的所有互動記錄，並回想先前聽過或看過的資訊。
• 支援函式呼叫、程式碼執行和 Google 搜尋做為工具： 您可以將模型與外部服務和資料來源整合。

Live API 專為伺服器對伺服器通訊而設計。

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

支援的模型

• Gemini 2.5 Flash with Live API native audio (預先發布版)
• Gemini 2.0 Flash with Live API (預先發布版)
• Gemini 2.5 Flash

開始使用

如要試用 Live API，請前往 Vertex AI Studio，然後點選「開始工作階段」。

Live API 是使用 WebSockets 的有狀態 API。

本節提供範例，說明如何使用 Live API 產生文字，並使用 Python 3.9 以上版本。

pip install --upgrade google-genai

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import (Content, HttpOptions, LiveConnectConfig,
                                Modality, Part)

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
model_id = "gemini-2.0-flash-live-preview-04-09"

async with client.aio.live.connect(
    model=model_id,
    config=LiveConnectConfig(response_modalities=[Modality.TEXT]),
) as session:
    text_input = "Hello? Gemini, are you there?"
    print("> ", text_input, "\n")
    await session.send_client_content(
        turns=Content(role="user", parts=[Part(text=text_input)])
    )

    response = []

    async for message in session.receive():
        if message.text:
            response.append(message.text)

    print("".join(response))
# Example output:
# >  Hello? Gemini, are you there?
# Yes, I'm here. What would you like to talk about?

整合指南

本節說明如何整合 Live API。

工作階段

WebSocket 連線會在用戶端和 Gemini 伺服器之間建立工作階段。

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

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

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

請參閱下列設定範例：

{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object
  },

  "systemInstruction": string,
  "tools": [object]
}

詳情請參閱 BidiGenerateContentSetup。

傳送訊息

訊息是透過 WebSocket 連線交換的 JSON 格式物件。

如要傳送訊息，用戶端必須透過開啟的 WebSocket 連線傳送 JSON 物件。JSON 物件必須只包含一個下列物件集中的欄位：

{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

支援的用戶端訊息

下表列出支援的用戶端訊息：

接收郵件

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

請參閱以下資訊：

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

伺服器訊息會只包含下列物件集中的一個欄位：

{
  "setupComplete": BidiGenerateContentSetupComplete,
  "serverContent": BidiGenerateContentServerContent,
  "toolCall": BidiGenerateContentToolCall,
  "toolCallCancellation": BidiGenerateContentToolCallCancellation
  "usageMetadata": UsageMetadata
  "goAway": GoAway
  "sessionResumptionUpdate": SessionResumptionUpdate
  "inputTranscription": BidiGenerateContentTranscription
  "outputTranscription": BidiGenerateContentTranscription
}

支援的伺服器訊息

下表列出支援的伺服器訊息：

分批更新內容

使用增量更新傳送文字輸入內容、建立工作階段情境資訊，或還原工作階段情境資訊。如為簡短情境，您可以傳送逐輪互動，代表確切的事件順序。如果脈絡較長，建議提供單一訊息摘要，以釋放脈絡窗口，供後續互動使用。

請參閱以下範例情境訊息：

{
  "clientContent": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

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

串流音訊和影片

程式碼執行

如要進一步瞭解程式碼執行作業，請參閱「程式碼執行」。

函式呼叫

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

您可以使用 JSON 定義函式，具體來說，就是使用OpenAPI 結構定義格式的選取子集。單一函式宣告可包含下列參數：

• name (字串)：API 呼叫中函式的專屬 ID。

• description (字串)：詳細說明函式的用途和功能。

• 參數 (物件)：定義函式所需的輸入資料。

  • type (字串)：指定整體資料類型，例如物件。

  • properties (物件)：列出個別參數，每個參數都包含：

    • type (字串)：參數的資料類型，例如字串、整數、布林值。
    • 說明 (字串)：清楚說明參數的用途和預期格式。

  • 必要 (陣列)：字串陣列，列出函式運作時必須提供的參數名稱。

如需使用 curl 指令宣告函式的程式碼範例，請參閱「使用 Gemini API 呼叫函式」。如需如何使用 Gemini API SDK 建立函式宣告的範例，請參閱函式呼叫教學課程。

模型可以根據單一提示產生多個函式呼叫，以及串連輸出內容所需的程式碼。這段程式碼會在沙箱環境中執行，產生後續的 BidiGenerateContentToolCall 訊息。執行作業會暫停，直到每個函式呼叫的結果都可用為止，確保處理作業依序進行。

用戶端應回覆 BidiGenerateContentToolResponse。

詳情請參閱「函式呼叫簡介」。

音訊格式

請參閱支援的音訊格式清單。

系統指示

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

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

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

中斷

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

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

語音

如要指定語音，請在 speechConfig 物件中設定 voiceName，做為工作階段設定的一部分。

請參閱下列 speechConfig 物件的 JSON 表示法：

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "VOICE_NAME"
    }
  }
}

如要查看支援的語音清單，請參閱「變更語音和語言設定」。

限制

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

用戶端驗證

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

工作階段時間上限

對話工作階段的預設時間上限為 10 分鐘。詳情請參閱「工作階段長度」。

語音活動偵測 (VAD)

根據預設，模型會對連續音訊輸入串流自動執行語音活動偵測 (VAD)。VAD 可透過設定訊息的RealtimeInputConfig.AutomaticActivityDetection欄位進行設定。

如果音訊串流暫停超過一秒 (例如使用者關閉麥克風時)，系統會傳送 AudioStreamEnd 事件，清除所有快取音訊。用戶端隨時可以繼續傳送音訊資料。

或者，您也可以在設定訊息中將 RealtimeInputConfig.AutomaticActivityDetection.disabled 設為 true，關閉自動 VAD。在此設定中，用戶端負責偵測使用者語音，並在適當時間傳送 ActivityStart 和 ActivityEnd 訊息。這個設定未傳送 AudioStreamEnd。而是以 ActivityEnd 訊息標示串流中斷。

其他限制

系統不支援手動設定端點。

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

權杖數量

不支援權杖計數。

頻率限制

適用下列頻率限制：

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

訊息和活動

後續步驟

• 進一步瞭解函式呼叫。
• 如需範例，請參閱函式呼叫參考資料。