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:
No console do Google Cloud , acesse a página Agent Platform > Studio > Stream realtime.
Clique em Trocar modelo.
Na lista de modelos, selecione
gemini-3.8-live.No painel principal, selecione Avatar em tempo real.
Na lista Avatar, selecione um avatar.
Na lista Voz, selecione uma opção.
Opcional: adicione instruções do sistema para orientar o comportamento e a saída.
Opcional: ative a entrada de câmera para compartilhar vídeos com a API Gemini Live.
No painel principal, clique em Iniciar sessão.
Configurar avatares em tempo real usando a API
Faça o seguinte:
Em
generation_config, defina"response_modalities": ["VIDEO"].No objeto
avatar_config, especifique o nome do avatar predefinido.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:
No console do Google Cloud , acesse a página Agent Platform > Studio > Stream realtime.
Na lista de modelos, selecione
gemini-3.8-live.No painel principal, clique em Avatar em tempo real.
Selecione "Fazer upload" nas opções do avatar e envie uma imagem.
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
- Configurar idioma e voz
- Iniciar e gerenciar sessões ao vivo
- Enviar streams de áudio e vídeo
- Práticas recomendadas com a API Gemini Live