本文档介绍了如何在 Gemini Live API 中配置实时头像。借助实时虚拟形象,您可以生成实时视频,其中包含正在说话的虚拟形象,该虚拟形象与 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。在主面板中,点击实时虚拟形象。
在虚拟形象的选项下选择“上传”,然后上传虚拟形象图片。
点击开始会话,然后点击开始对话。
使用 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 中的任何预建高清语音配对。如需详细了解预构建语音,请参阅预构建语音。