設定即時虛擬化身

本文說明如何在 Gemini Live API 中設定即時虛擬人偶。透過 Live Avatar,您可以生成即時影片,讓會說話的虛擬化身與 gemini-3.8-live 模型合成的語音回覆同步。您可以從各種內建虛擬化身中選擇,並在 Google Cloud 控制台和 Gemini Live API 中,將虛擬化身與支援的預建語音配對。

在 Google Cloud 控制台設定即時虛擬化身

請執行下列步驟:

  1. 在 Google Cloud 控制台中,依序前往「Agent Platform」>「Studio」>「Stream realtime」頁面。

    前往「即時串流」

  2. 按一下 「切換模型」。

  3. 從模型清單中選取 gemini-3.8-live。

  4. 在主面板中選取「即時虛擬化身」。

  5. 從「虛擬化身」清單中選取虛擬化身。

  6. 從「語音」清單中選取語音。

  7. 選用:新增系統指示,引導模型行為和輸出內容。

  8. 選用:啟用影像辨識輸入功能,與 Gemini Live API 分享影片。

  9. 在主面板中,按一下「開始工作階段」。

使用 API 設定即時虛擬化身

請執行下列步驟:

  1. 在 generation_config 中設定 "response_modalities": ["VIDEO"]。

  2. 在 avatar_config 物件中,指定預先建構的虛擬人偶名稱。

  3. 在 speech_config 物件中,指定預先建構的語音。

WebSocket 設定

系統會透過標準 WebSocket 握手建立 WebSocket 連線。端點是區域性的,並使用 OAuth 2.0 不記名權杖進行驗證。驗證權杖通常會傳遞至 WebSocket 標頭,例如 Authorization: Bearer [TOKEN]。

以下是 WebSocket 設定範例:

import asyncio
import json
import websockets

# Replace PROJECT_ID and LOCATION with your Project ID and location.
PROJECT_ID = "PROJECT_ID"
LOCATION = "LOCATION"

# Authentication
token_list = !gcloud auth application-default print-access-token
ACCESS_TOKEN = token_list[0]

# Configuration
MODEL_ID = "gemini-3.8-live"
MODEL = f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}"

config = {
    "response_modalities": ["VIDEO"],
    "speech_config": {
        "voice_config": {
            "prebuilt_voice_config": {
                "voice_name": "Puck",
            }
        }
    },
}

avatar_config = {
    "avatar_name": "Ben",
}

# Construct the WSS URL
HOST = f"{LOCATION}-aiplatform.googleapis.com"
URI = f"wss://{HOST}/ws/google.cloud.aiplatform.v1.LlmBidiService/BidiGenerateContent"

async def main():
    headers = {"Authorization": f"Bearer {ACCESS_TOKEN}"}

    async with websockets.connect(URI, additional_headers=headers) as ws:
        print("Session established.")

        # Send Setup (Handshake)
        await ws.send(json.dumps({
            "setup": {
                "model": MODEL,
                "generation_config": config,
                "avatar_config": avatar_config,
            }
        }))
        # Send and receive audio/video streams...

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

Python SDK 設定

下列範例說明如何使用 Google Gen AI SDK 設定即時虛擬人偶:

from google import genai
from google.genai import types

client = genai.Client()

config = types.LiveConnectConfig(
    response_modalities=["VIDEO"],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(
                voice_name="Puck",
            )
        )
    ),
    avatar_config=types.AvatarConfig(
        avatar_name="Ben",
    ),
    system_instruction=types.Content(
        parts=[types.Part.from_text(text="You are a helpful customer service assistant.")]
    ),
)

async with client.aio.live.connect(model="gemini-3.8-live", config=config) as session:
    # Interact with the live session...
    pass

使用自訂虛擬化身

您不必選擇預先建立的虛擬化身,只要提供臉部參考圖像,Gemini Live API 就會根據該圖像生成虛擬化身影片。自訂虛擬化身是在 avatar_config 的 customized_avatar 欄位中,針對每個工作階段設定。

參考圖像規定

參考圖像必須符合下列規格:

  • 圖片格式:建議使用 PNG。PNG 採用無損壓縮技術,而 Alpha 透明度可避免在淺色和深色模式下,虛擬人像周圍出現可見方塊。
  • 色彩模式:RGB。
  • 圖片大小:直向至少 704 x 1280 像素,橫向至少 1280 x 704 像素。
  • 解析度:720p 以上。
  • 顯示比例:標準為 9:16 (直向) 和 16:9 (橫向)。
  • 檔案大小:小於 5 MB
  • 品質:不得模糊不清或壓縮失真。

為獲得最佳效果,請同時遵循下列構圖規範:

  • 構圖:使用胸部以上鏡頭,讓頭部和肩膀占據畫面 60% 以上。裁剪掉下半身、手臂、手部和任何手持物體,例如麥克風或手機。

  • 背景:使用簡單乾淨的背景,不要有其他人或其他明顯物體。

  • 視角:頭部保持水平,雙眼直視鏡頭。

  • 表情:請保持自然放鬆的表情,不要微笑、瞇眼或露出牙齒。

  • 安全性:請勿使用未成年人、名人或令人反感的圖片。

在 Google Cloud 控制台設定自訂虛擬人偶

請執行下列步驟:

  1. 在 Google Cloud 控制台中,依序前往「Agent Platform」>「Studio」>「Stream realtime」頁面。

    即時串流

  2. 從模型清單中選取 gemini-3.8-live。

  3. 在主面板中,按一下「Live Avatar」(即時虛擬化身)。

  4. 選取「虛擬化身」選項下方的「上傳」,然後上傳虛擬化身圖片。

  5. 按一下「開始工作階段」,然後按一下「開始對話」。

使用 API 設定自訂虛擬化身

在透過 WebSocket 連線傳送的初始 setup 酬載中,設定自訂虛擬人偶:

import base64
import json
import websockets

# Load custom avatar image (PNG format, 704x1280 min)
with open("/path/to/your/sample_avatar.png", "rb") as f:
    avatar_b64 = base64.b64encode(f.read()).decode("utf-8")

GENERATION_CONFIG = {
    "response_modalities": ["VIDEO"],
}

# Setup avatar config with custom face image
AVATAR_CONFIG = {
    "customized_avatar": {
        "image_data": avatar_b64,
        "image_mime_type": "png",
    }
}

# Session setup message
SETUP_MESSAGE = {
    "setup": {
        "model": "gemini-3.8-live",
        "generation_config": GENERATION_CONFIG,
        "avatar_config": AVATAR_CONFIG,
        "system_instruction": {
            "parts": [{"text": "Your system instruction here"}]
        },
        "input_audio_transcription": {},
        "output_audio_transcription": {},
    }
}

上述範例使用下列欄位:

欄位路徑 類型 說明
generation_config.response_modalities list[string] 必須設為 ["VIDEO"],才能啟用虛擬化身影片輸出功能。
avatar_config.customized_avatar.image_data string Base64 編碼的圖片字串。
avatar_config.customized_avatar.image_mime_type string 圖片 MIME 格式 ("png")。

您可以將自訂虛擬化身與預先建構的語音或自訂語音配對。

可用的預建語音

您可以將預先建構的虛擬化身,與 Gemini Live API 中任何預先建構的 HD 語音配對。如要進一步瞭解預建語音,請參閱「預建語音」。

後續步驟