En este documento, se describe cómo configurar avatares en tiempo real en la API de Gemini Live. Los avatares
en tiempo real te permiten generar videos en tiempo real de un avatar que habla sincronizado con
respuestas de voz sintetizadas del modelo gemini-3.8-live.
Puedes elegir entre una variedad de avatares integrados y vincularlos con voces precompiladas compatibles
tanto en la consola de Google Cloud como en la API de Gemini Live.
Configura avatares en tiempo real en la consola de Google Cloud
Haz lo siguiente:
En la consola de Google Cloud , ve a la página Agent Platform > Studio > Transmitir en tiempo real.
Haz clic en Cambiar de modelo.
En la lista de modelos, selecciona
gemini-3.8-live.En el panel principal, selecciona Avatar en tiempo real.
En la lista Avatar, selecciona un avatar.
En la lista Voz, selecciona una voz.
Opcional: Agrega instrucciones del sistema para guiar el comportamiento y el resultado.
Opcional: Habilita la entrada de cámara para compartir videos con la API de Gemini Live.
En el panel principal, haz clic en Iniciar sesión.
Configura avatares en tiempo real con la API
Haz lo siguiente:
En
generation_config, establece"response_modalities": ["VIDEO"].En el objeto
avatar_config, especifica el nombre del avatar prediseñado.En el objeto
speech_config, especifica la voz precompilada.
Configuración de WebSocket
Las conexiones de WebSocket se establecen con un protocolo de enlace de WebSocket estándar. El
extremo es regional y usa tokens del 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 un ejemplo de configuración de 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())
Configuración del SDK de Python
En el siguiente ejemplo, se muestra cómo configurar avatares en tiempo real 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
Usa 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 esa semejanza.
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érdidas, 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), 1,280 × 704 píxeles como mínimo (horizontal).
- Resolución: 720p o superior
- Relación de aspecto: El estándar es 9:16 (vertical) y 16:9 (horizontal).
- Tamaño de archivo: Inferior a 5 MB
- Calidad: No debe haber desenfoque ni artefactos de compresión.
Para obtener los mejores resultados, también sigue estos lineamientos de composición:
Encuadre: Usa un 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 simple y ordenado, sin otras personas ni objetos distintivos.
Perspectiva: Mira directamente a la cámara, con la cabeza nivelada y los ojos mirando hacia la lente.
Expresión: Mantén una expresión neutral y relajada, 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:
En la consola de Google Cloud , ve a la página Agent Platform > Studio > Transmitir en tiempo real.
En la lista de modelos, selecciona
gemini-3.8-live.En el panel principal, haz clic en Avatar en tiempo real.
Selecciona Subir en las opciones de Avatar y sube una imagen de avatar.
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 inicial de setup 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] |
Se debe establecer 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 precompilada o con una voz personalizada.
Voces prediseñadas disponibles
Puedes vincular avatares prediseñados con cualquiera de las 30 voces en HD prediseñadas en la API de Gemini Live. Para obtener más información sobre las voces compatibles, consulta Voces compatibles.
¿Qué sigue?
- Configura el idioma y la voz
- Cómo iniciar y administrar sesiones en vivo
- Envía transmisiones de audio y video
- Prácticas recomendadas con la API de Gemini Live