Configurer des avatars en direct

Ce document explique comment configurer des avatars en direct dans l'API Gemini Live. Les avatars en direct vous permettent de générer des vidéos en temps réel d'un avatar parlant, synchronisées 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 Cloud de Confiance et l'API Gemini Live.

Configurer des avatars en direct dans la console Cloud de Confiance

Procédez comme suit :

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

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

2. Cliquez sur  mic 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 en direct.

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 le résultat.

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 en direct à 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 en direct à 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. L'API Gemini Live génère alors la vidéo de l'avatar à partir de cette image. 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 de l'image : PNG recommandé. Le format PNG utilise une compression sans perte, et la transparence alpha empêche l'apparition d'un encadré visible autour de l'avatar en mode clair et sombre.
• Mode couleur : RVB.
• Taille d'image : 704 x 1 280 pixels minimum (portrait), 1 280 x 704 pixels minimum (paysage).
• Résolution : au moins 720p.
• Format : le format standard est 9:16 (portrait) et 16:9 (paysage).
• Taille du fichier : inférieure à 5 Mo
• Qualité : pas de flou ni d'artefacts de compression.

Pour obtenir les meilleurs résultats, suivez également ces consignes de composition :

• Cadrage : utilisez un plan rapproché (tête et épaules) qui occupe plus de 60% du cadre. Recadrez l'image pour supprimer le bas du corps, les bras, les mains et les objets tenus, comme les micros ou les téléphones.

• Arrière-plan : utilisez un arrière-plan simple et épuré, sans autre personne ni objet distinct.

• Perspective : regardez directement l'appareil photo, avec la tête droite et les yeux tournés vers l'objectif.

• Expression : gardez une expression neutre et au repos, sans sourire, sans plisser les yeux ni montrer les dents.

• Sécurité : n'utilisez pas d'images de mineurs, de célébrités ni de contenu offensant.

Configurer un avatar personnalisé dans la console Cloud de Confiance

Procédez comme suit :

1. Dans la console Cloud de Confiance , accédez à la page Agent Platform> Studio> Flux 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 en direct.

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 :

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 à l'une des voix HD prédéfinies de l'API Gemini Live. Pour en savoir plus sur les voix prédéfinies, consultez Voix prédéfinies.

Étapes suivantes

• Configurer la langue et la voix
• Démarrer et gérer des sessions en direct
• Envoyer des flux audio et vidéo
• Bonnes pratiques avec l'API Live