Live API 參考資料

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

如要進一步瞭解 Live API，請參閱 Live API。

功能

Live API 提供下列主要功能：

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

Live API 是用於伺服器對伺服器的通訊。

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

支援的模型

開始使用

如要試用 Live API，請前往 Vertex AI Studio，然後點選「Start Session」。

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,
    LiveConnectConfig,
    HttpOptions,
    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 (字串)：參數的資料類型，例如字串、整數、布林值。
    • description (字串)：清楚說明參數的用途和預期格式。

  • required (陣列)：字串陣列，列出函式運作時必須使用的參數名稱。

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

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

用戶端應回覆 BidiGenerateContentToolResponse。

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

音訊格式

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

系統指示

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

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

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

中斷

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

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

語音

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

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

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

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

限制

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

用戶端驗證

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

工作階段持續時間上限

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

語音活動偵測 (VAD)

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

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

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

其他限制

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

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

符記數

不支援符記數量。

頻率限制

適用下列頻率限制：

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

訊息和事件

後續步驟

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