Configurer des avatars en direct

Ce document explique comment configurer des avatars live dans l'API Gemini Live. Les avatars live vous permettent de générer une vidéo en temps réel d'un avatar parlant, synchronisée avec les réponses vocales synthétisées du modèle gemini-3.8-live. Vous pouvez choisir parmi une variété d'avatars intégrés et les associer à des voix prédéfinies compatibles dans la console Google Cloud et l'API Gemini Live.

Configurer des avatars live dans la console Google Cloud

Procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Agent Platform > Studio > Diffuser en temps réel.

    Accéder à la page "Diffuser en temps réel"

  2. Cliquez sur Changer de modèle.

  3. Dans la liste des modèles, sélectionnez gemini-3.8-live.

  4. Dans le panneau principal, sélectionnez Avatar live.

  5. Dans la liste Avatar, sélectionnez un avatar.

  6. Dans la liste Voix, sélectionnez une voix.

  7. Facultatif : ajoutez des instructions système pour guider le comportement et la sortie.

  8. Facultatif : Activez l'entrée de la caméra pour partager des vidéos avec l'API Gemini Live.

  9. Dans le panneau principal, cliquez sur Démarrer la session.

Configurer des avatars live à l'aide de l'API

Procédez comme suit :

  1. Dans generation_config, définissez "response_modalities": ["VIDEO"].

  2. Dans l'objet avatar_config, spécifiez le nom de l'avatar prédéfini.

  3. Dans l'objet speech_config, spécifiez la voix prédéfinie.

Configuration WebSocket

Les connexions WebSocket sont établies avec un handshake WebSocket standard. Le point de terminaison est régional et utilise des jetons de support OAuth 2.0 pour l'authentification. Le jeton d'authentification est généralement transmis dans les en-têtes WebSocket, tels que Authorization: Bearer [TOKEN].

Voici un exemple de configuration 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())

Configuration du SDK Python

L'exemple suivant montre comment configurer des avatars live à l'aide du SDK Google Gen AI :

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

Utiliser un avatar personnalisé

Au lieu de choisir un avatar prédéfini, vous pouvez fournir une image de référence d'un visage, et l'API Gemini Live génère la vidéo de l'avatar à partir de cette ressemblance. Les avatars personnalisés sont configurés par session dans le champ customized_avatar de avatar_config.

Exigences concernant les images de référence

L'image de référence doit respecter les spécifications suivantes :

  • Format d'image : PNG recommandé. Le format PNG utilise une compression sans perte, et la transparence alpha empêche l'affichage d'un cadre visible autour de l'avatar en modes clair et sombre.
  • Mode couleur : RVB.
  • Taille de l'image : 704 x 1 280 pixels minimum (portrait), 1 280 x 704 pixels minimum (paysage).
  • Résolution : au moins 720p.
  • Format : 9:16 (portrait) et 16:9 (paysage) sont les formats standards.
  • Taille de fichier : inférieure à 5 Mo
  • Qualité : pas de flou ni d'artefacts de compression.

Pour des résultats optimaux, suivez également ces consignes de composition :

  • Cadrage : utilisez un plan poitrine, où la tête et les épaules occupent plus de 60 % du cadre. Recadrez le bas du corps, les bras, les mains et tout objet tenu, comme un micro ou un téléphone.

  • Arrière-plan : utilisez un arrière-plan simple et épuré, sans autres personnes ni objets distincts.

  • Perspective : placez-vous directement face à l'appareil photo, la tête droite et les yeux fixés sur l'objectif.

  • Expression : gardez une expression neutre et détendue, sans sourire, sans plisser les yeux et sans montrer vos dents.

  • Sécurité : n'utilisez pas d'images de mineurs, de célébrités ou de contenus offensants.

Configurer un avatar personnalisé dans la console Google Cloud

Procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Agent Platform > Studio > Diffuser en temps réel.

    Diffuser en temps réel

  2. Dans la liste des modèles, sélectionnez gemini-3.8-live.

  3. Dans le panneau principal, cliquez sur Avatar live.

  4. Sélectionnez "Importer" sous les options de l'avatar, puis importez une image d'avatar.

  5. Cliquez sur Démarrer la session, puis sur Démarrer la conversation.

Configurer un avatar personnalisé à l'aide de l'API

Configurez l'avatar personnalisé dans la charge utile setup initiale que vous envoyez via la connexion WebSocket :

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": {},
    }
}

L'exemple précédent utilise les champs suivants :

Chemin d'accès du champ Type Description
generation_config.response_modalities list[string] Doit être défini sur ["VIDEO"] pour activer la sortie vidéo de l'avatar.
avatar_config.customized_avatar.image_data string Chaîne d'image encodée en base64.
avatar_config.customized_avatar.image_mime_type string Format MIME de l'image ("png").

Vous pouvez associer un avatar personnalisé à une voix prédéfinie ou à une voix personnalisée.

Voix prédéfinies disponibles

Vous pouvez associer des avatars prédéfinis à n'importe quelle voix HD prédéfinie dans l'API Gemini Live. Pour en savoir plus sur les voix prédéfinies, consultez Voix prédéfinies.

Étapes suivantes