本文說明如何在 Gemini Live API 中設定即時虛擬人偶。透過 Live Avatar,您可以生成即時影片,讓會說話的虛擬化身與 gemini-3.8-live 模型合成的語音回覆同步。您可以從各種內建虛擬化身中選擇,並在 Google Cloud 控制台和 Gemini Live API 中,將虛擬化身與支援的預建語音配對。
在 Google Cloud 控制台設定即時虛擬化身
請執行下列步驟:
在 Google Cloud 控制台中,依序前往「Agent Platform」>「Studio」>「Stream realtime」頁面。
按一下 「切換模型」。
從模型清單中選取
gemini-3.8-live。在主面板中選取「即時虛擬化身」。
從「虛擬化身」清單中選取虛擬化身。
從「語音」清單中選取語音。
選用:新增系統指示,引導模型行為和輸出內容。
選用:啟用影像辨識輸入功能,與 Gemini Live API 分享影片。
在主面板中,按一下「開始工作階段」。
使用 API 設定即時虛擬化身
請執行下列步驟:
在
generation_config中設定"response_modalities": ["VIDEO"]。在
avatar_config物件中,指定預先建構的虛擬人偶名稱。在
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 控制台設定自訂虛擬人偶
請執行下列步驟:
在 Google Cloud 控制台中,依序前往「Agent Platform」>「Studio」>「Stream realtime」頁面。
從模型清單中選取
gemini-3.8-live。在主面板中,按一下「Live Avatar」(即時虛擬化身)。
選取「虛擬化身」選項下方的「上傳」,然後上傳虛擬化身圖片。
按一下「開始工作階段」,然後按一下「開始對話」。
使用 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 語音配對。如要進一步瞭解預建語音,請參閱「預建語音」。