配置实时虚拟形象

本文档介绍了如何在 Gemini Live API 中配置实时头像。借助实时虚拟形象,您可以生成实时视频,其中包含正在说话的虚拟形象,该虚拟形象与 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. 在主面板中,点击实时虚拟形象。

  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 中的任何预建高清语音配对。如需详细了解预构建语音,请参阅预构建语音。

后续步骤