ライブアバターを構成する

このドキュメントでは、Gemini Live API でライブ アバターを構成する方法について説明します。ライブ アバターを使用すると、gemini-3.8-live モデルからの合成音声応答と同期した、話すアバターのリアルタイム動画を生成できます。さまざまな組み込みアバターから選択し、 Cloud de Confiance コンソールと Gemini Live API の両方でサポートされている事前構築済みの音声と組み合わせることができます。

Cloud de Confiance コンソールでライブアバターを構成する

手順は次のとおりです。

  1. Cloud de Confiance コンソールで、[Agent Platform> Studio> Stream realtime] ページに移動します。

    [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 ベアラー トークンを使用します。通常、認証トークンは Authorization: Bearer [TOKEN] などの WebSocket ヘッダーで渡されます。

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 はロスレス圧縮を使用し、アルファ透明度により、ライトモードとダークモードでアバターの周囲に表示されるボックスを防ぎます。
  • カラーモード: RGB。
  • 画像サイズ: 縦向きの場合は 704 x 1,280 ピクセル以上、横向きの場合は 1,280 x 704 ピクセル以上。
  • 解像度: 720p 以上。
  • アスペクト比: 9:16(縦向き)と 16:9(横向き)が標準です。
  • ファイルサイズ: 5 MB 未満
  • 品質: ぼやけや圧縮アーティファクトがない。

最適な結果を得るには、次の構図のガイドラインも参考にしてください。

  • フレーミング: 頭と肩がフレームの 60% 以上を占めるバストショットを使用します。下半身、腕、手、マイクやスマートフォンなどの持ち物を切り取ります。

  • 背景: 他の人物や目立つ物体が写り込まない、シンプルな背景を使用します。

  • 視点: 頭を水平に保ち、レンズをまっすぐ見ながら、カメラを正面から見ます。

  • 表情: 笑顔、しかめっ面、歯が見えるような表情は避け、自然な表情を保ってください。

  • 安全性: 未成年者、著名人、不適切なコンテンツの画像は使用しないでください。

Cloud de Confiance コンソールでカスタム アバターを構成する

手順は次のとおりです。

  1. Cloud de Confiance コンソールで、[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 のプリビルド アバターは、プリビルド HD 音声と組み合わせることができます。事前構築済みの音声の詳細については、事前構築済みの音声をご覧ください。

次のステップ