Configurar avatares em tempo real

Este documento descreve como configurar avatares em tempo real na API Gemini Live. Com os avatares em tempo real, é possível gerar um vídeo em tempo real de um avatar falante sincronizado com respostas de fala sintetizadas do modelo gemini-3.8-live. Escolha entre uma variedade de avatares integrados e combine-os com vozes predefinidas compatíveis no console do Google Cloud e na API Gemini Live.

Configurar avatares em tempo real no console do Google Cloud

Faça o seguinte:

  1. No console do Google Cloud , acesse a página Agent Platform > Studio > Stream realtime.

    Acessar "Transmitir em tempo real"

  2. Clique em Trocar modelo.

  3. Na lista de modelos, selecione gemini-3.8-live.

  4. No painel principal, selecione Avatar em tempo real.

  5. Na lista Avatar, selecione um avatar.

  6. Na lista Voz, selecione uma opção.

  7. Opcional: adicione instruções do sistema para orientar o comportamento e a saída.

  8. Opcional: ative a entrada de câmera para compartilhar vídeos com a API Gemini Live.

  9. No painel principal, clique em Iniciar sessão.

Configurar avatares em tempo real usando a API

Faça o seguinte:

  1. Em generation_config, defina "response_modalities": ["VIDEO"].

  2. No objeto avatar_config, especifique o nome do avatar predefinido.

  3. No objeto speech_config, especifique a voz predefinida.

Configuração do WebSocket

As conexões WebSocket são estabelecidas com um handshake WebSocket padrão. O endpoint é regional e usa tokens do portador do OAuth 2.0 para autenticação. O token de autenticação normalmente é transmitido em cabeçalhos do WebSocket, como Authorization: Bearer [TOKEN].

Veja a seguir um exemplo de configuração do 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())

Configuração do SDK do Python

O exemplo a seguir mostra como configurar avatares em tempo real usando o SDK de IA generativa do 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

Usar um avatar personalizado

Em vez de escolher um avatar predefinido, você pode fornecer uma imagem de referência de um rosto, e a API Gemini Live vai gerar o vídeo do avatar com base nessa semelhança. Os avatares personalizados são configurados por sessão no campo customized_avatar de avatar_config.

Requisitos da imagem de referência

A imagem de referência precisa atender às seguintes especificações:

  • Formato da imagem: PNG recomendado. O PNG usa compactação sem perdas, e a transparência alfa impede que uma caixa visível apareça ao redor do avatar nos modos claro e escuro.
  • Modo de cor: RGB.
  • Tamanho da imagem: mínimo de 704 x 1.280 pixels (retrato) e 1.280 x 704 pixels (paisagem).
  • Resolução: no mínimo 720p.
  • Proporção: 9:16 (retrato) e 16:9 (paisagem) é o padrão.
  • Tamanho do arquivo: menor que 5 MB
  • Qualidade: sem partes desfocadas ou distorções de compactação.

Para melhores resultados, siga também estas diretrizes de composição:

  • Enquadramento: use um plano médio, em que a cabeça e os ombros ocupam mais de 60% do quadro. Corte a parte inferior do corpo, os braços, as mãos e todos os objetos que estiverem sendo segurados, como microfones ou smartphones.

  • Plano de fundo: use um plano de fundo simples e sem outras pessoas ou objetos distintos.

  • Perspectiva: olhe diretamente para a câmera, com a cabeça nivelada e os olhos voltados para a lente.

  • Expressão: mantenha uma expressão neutra e relaxada, sem sorrir, apertar os olhos ou mostrar os dentes.

  • Segurança: não use imagens de menores, celebridades ou conteúdo ofensivo.

Configurar um avatar personalizado no console do Google Cloud

Faça o seguinte:

  1. No console do Google Cloud , acesse a página Agent Platform > Studio > Stream realtime.

    Streaming em tempo real

  2. Na lista de modelos, selecione gemini-3.8-live.

  3. No painel principal, clique em Avatar em tempo real.

  4. Selecione "Fazer upload" nas opções do avatar e envie uma imagem.

  5. Clique em Iniciar sessão e em Iniciar conversa.

Configurar um avatar personalizado usando a API

Configure o avatar personalizado no payload setup inicial que você envia pela conexão 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": {},
    }
}

O exemplo anterior usa os seguintes campos:

Caminho do campo Tipo Descrição
generation_config.response_modalities list[string] Precisa ser definido como ["VIDEO"] para ativar a saída de vídeo do avatar.
avatar_config.customized_avatar.image_data string String de imagem codificada em Base64.
avatar_config.customized_avatar.image_mime_type string Formato MIME da imagem ("png").

É possível combinar um avatar personalizado com uma voz predefinida ou com uma voz personalizada.

Vozes predefinidas disponíveis

Você pode combinar avatares predefinidos com qualquer uma das 30 vozes em alta definição predefinidas na API Gemini Live. Para mais informações sobre as vozes disponíveis, consulte Vozes disponíveis.

A seguir