Configura avatares en vivo

En este documento, se describe cómo configurar avatares en vivo en la API de Gemini Live. Los avatares en vivo te permiten generar videos en tiempo real de un avatar que habla y que se sincroniza con las respuestas de voz sintetizada del modelo gemini-3.8-live. Puedes elegir entre una variedad de avatares integrados y combinarlos con voces prediseñadas compatibles en la consola de Google Cloud y la API de Gemini Live.

Configura avatares en vivo en Google Cloud console

Haz lo siguiente:

  1. En la consola de Google Cloud , ve a la página Agent Platform > Studio > Stream en tiempo real.

    Ir a Stream realtime

  2. Haz clic en Cambiar modelo.

  3. En la lista de modelos, selecciona gemini-3.8-live.

  4. En el panel principal, selecciona Live Avatar.

  5. En la lista Avatar, selecciona uno.

  6. En la lista Voz, selecciona una voz.

  7. Opcional: Agrega instrucciones del sistema para guiar el comportamiento y el resultado.

  8. Opcional: Habilita la entrada de cámara para compartir videos con la API de Gemini Live.

  9. En el panel principal, haz clic en Iniciar sesión.

Configura avatares en vivo con la API

Haz lo siguiente:

  1. En generation_config, establece "response_modalities": ["VIDEO"].

  2. En el objeto avatar_config, especifica el nombre del avatar prediseñado.

  3. En el objeto speech_config, especifica la voz prediseñada.

Configuración de WebSocket

Las conexiones WebSocket se establecen con un protocolo de enlace de WebSocket estándar. El extremo es regional y usa tokens de portador de OAuth 2.0 para la autenticación. Por lo general, el token de autenticación se pasa en los encabezados de WebSocket, como Authorization: Bearer [TOKEN].

A continuación, se muestra una configuración de WebSocket de muestra:

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())

Configuración del SDK de Python

En el siguiente ejemplo, se muestra cómo configurar avatares en vivo con el SDK de IA generativa de Google:

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

Cómo usar un avatar personalizado

En lugar de elegir un avatar prediseñado, puedes proporcionar una imagen de referencia de un rostro, y la API de Gemini Live generará el video del avatar a partir de ese parecido. Los avatares personalizados se configuran por sesión en el campo customized_avatar de avatar_config.

Requisitos de las imágenes de referencia

La imagen de referencia debe cumplir con las siguientes especificaciones:

  • Formato de imagen: Se recomienda PNG. El formato PNG usa compresión sin pérdida, y la transparencia alfa evita que se vea un cuadro alrededor del avatar en los modos claro y oscuro.
  • Modo de color: RGB.
  • Tamaño de la imagen: 704 × 1,280 píxeles como mínimo (vertical) y 1,280 × 704 píxeles como mínimo (horizontal)
  • Resolución: 720p o superior
  • Relación de aspecto: La relación de aspecto estándar es 9:16 (vertical) y 16:9 (horizontal).
  • Tamaño de archivo: Inferior a 5 MB
  • Calidad: Sin desenfoque ni artefactos de compresión

Para obtener los mejores resultados, sigue también estos lineamientos de composición:

  • Encuadre: Usa un primer plano de busto, en el que la cabeza y los hombros ocupen más del 60% del encuadre. Recorta la parte inferior del cuerpo, los brazos, las manos y cualquier objeto que se sostenga, como micrófonos o teléfonos.

  • Fondo: Usa un fondo sencillo y ordenado, sin otras personas ni objetos distintivos.

  • Perspectiva: Mira directamente a la cámara, con la cabeza nivelada y los ojos mirando a la lente.

  • Expresión: Mantén una expresión neutra y en reposo, sin sonreír, entrecerrar los ojos ni mostrar los dientes.

  • Seguridad: No uses imágenes de menores, celebridades ni contenido ofensivo.

Configura un avatar personalizado en la consola de Google Cloud

Haz lo siguiente:

  1. En la consola de Google Cloud , ve a la página Agent Platform > Studio > Stream en tiempo real.

    Transmite en tiempo real

  2. En la lista de modelos, selecciona gemini-3.8-live.

  3. En el panel principal, haz clic en Avatar en vivo.

  4. Selecciona Subir en las opciones del avatar y sube una imagen de avatar.

  5. Haz clic en Iniciar sesión y, luego, en Iniciar conversación.

Configura un avatar personalizado con la API

Configura el avatar personalizado en la carga útil setup inicial que envías a través de la conexión de 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": {},
    }
}

En el ejemplo anterior, se usan los siguientes campos:

Ruta del campo Tipo Descripción
generation_config.response_modalities list[string] Debe establecerse en ["VIDEO"] para habilitar la salida de video del avatar.
avatar_config.customized_avatar.image_data string Es la cadena de imagen codificada en Base64.
avatar_config.customized_avatar.image_mime_type string Formato MIME de la imagen ("png").

Puedes vincular un avatar personalizado con una voz prediseñada o con una voz personalizada.

Voces prediseñadas disponibles

Puedes combinar avatares prediseñados con cualquiera de las voces en HD prediseñadas en la API de Gemini Live. Para obtener más información sobre las voces prediseñadas, consulta Voces prediseñadas.

¿Qué sigue?