Guia para desenvolvedores do Gemini 3.8 Live

O Gemini 3.8 Live é um modelo conversacional em tempo real criado para interações de voz e vídeo bidirecionais de baixa latência e síntese de avatar ao vivo presencial. Projetado para fluxos de trabalho de conversa contínua, o 3.8 Live oferece diálogo afetivo ativado por padrão, filtragem de áudio proativa, ferramentas de bloqueio de cancelamento automático e alternância dinâmica de vários idiomas.

Neste documento, discutimos os seguintes tópicos:

• Como o 3.8 Live se encaixa na família de modelos do Gemini.
• Principais recursos do 3.8 Live.
• Integração com o SDK de IA Generativa do Google.
• Regras e convenções de API necessárias.
• Migração de modelos anteriores da API Gemini Live.

Função na família Gemini

O 3.8 Live foi projetado para interações de streaming em tempo real. Ele opera em WebSockets bidirecionais, processando fala, feeds de câmera ao vivo e transmissões de tela com latência abaixo do segundo, enquanto gera áudio de 24 kHz e avatares de vídeo sincronizados de 24 QPS.

Especificações e comparações de modelos

A tabela a seguir compara as especificações entre o 3.8 Live e modelos anteriores da API Gemini Live:

Quando usar o Gemini 3.8 Live

Use o 3.8 Live nos seguintes cenários:

• Você precisa de baixa latência conversacional, alternância natural e recuperação rápida quando o usuário interrompe (interrupção).
• O app chama ferramentas externas e precisa de execução não bloqueadora para que a saída de áudio continue enquanto os sistemas de back-end processam solicitações.
• Você quer renderizar avatares digitais falantes com animação facial sincronizada e dublagem a 24 QPS sem pipelines de renderização externos.
• Os usuários conversam em vários idiomas, exigindo detecção e alternância de idiomas no meio da transmissão entre idiomas com suporte.
• Você precisa de uma tendência de vocabulário específica do domínio para terminologia técnica, SKUs ou nomes de marcas.

Para conferir as especificações completas e os limites de cota, consulte a página do modelo 3.8 Live.

Principais recursos do Gemini 3.8 Live

O 3.8 Live apresenta os seguintes recursos:

• Síntese de vídeo de avatar em tempo real de 24 QPS: o 3.8 Live gera streams de vídeo MP4 sincronizados de 24 QPS (response_modalities=["VIDEO"]) diretamente da saída do modelo. As expressões faciais e os movimentos labiais gerados se alinham à fala sintetizada em tempo real.

  É possível usar avatares de estoque pré-criados ou fornecer imagens de referência personalizadas para criar recepcionistas digitais, representantes de atendimento ao cliente, tutores virtuais ou personagens interativos. Para detalhes da configuração, consulte Configurar avatares ao vivo.

• Diálogo afetivo e áudio proativo ativados por padrão:

  • Diálogo afetivo: ativado por padrão no 3.8 Live. O modelo processa prosódia acústica, pistas vocais, pausas e inflexão de fala na entrada de áudio do usuário para ajustar o tom vocal e o ritmo conversacional.
  • Áudio proativo: ativado por padrão no 3.8 Live. O modelo filtra o ruído ambiente e a fala de fundo, gerando respostas de áudio apenas quando o usuário se dirige a ele.

• Chamada de função de bloqueio assíncrona e de cancelamento automático: o 3.8 Live oferece comportamentos de chamada de função projetados para fala em tempo real:

  • Execução assíncrona não bloqueadora: quando o modelo gera uma chamada de função, a sessão de áudio permanece ativa para que o agente possa transmitir confirmações conversacionais ("Deixe-me mostrar os detalhes da sua conta...") e processar a entrada de acompanhamento enquanto o app cliente chama APIs de back-end.
  • Chamadas de bloqueio de cancelamento automático (behavior="BLOCKING"): quando uma declaração de função define behavior="BLOCKING", a geração é pausada até que a resposta da ferramenta chegue. Se uma nova entrada do usuário chegar enquanto a chamada de bloqueio estiver em execução, o servidor da API Gemini Live vai cancelar a chamada pendente.
  • Tratamento de interrupção educada: em modelos anteriores, retornar uma resposta de ferramenta com scheduling="INTERRUPT" enquanto o usuário falava sobrepunha o áudio do usuário. No 3.8 Live, o servidor rebaixa a programação para WHEN_IDLE quando a fala do usuário está ativa e reproduz a resposta depois que o usuário termina de falar.

• Alternância dinâmica de vários idiomas e vocabulário personalizado:

  • Suporte multilíngue: detecta e alterna entre idiomas com suporte no meio da sessão sem reiniciar ou reconfigurar a conexão.
  • Tendência de vocabulário personalizado: aceita palavras-chave específicas do domínio, substantivos próprios, termos médicos e códigos de produtos em AudioTranscriptionConfig (por input_audio_transcription) usando custom_vocabulary para melhorar a precisão da transcrição.

• Aterramento visual multimodal com controle de media_resolution: aceita streams de vídeo em tempo real (frames JPEG de 1 QPS, resolução recomendada 768x768) e permite configurar media_resolution (MEDIA_RESOLUTION_LOW, MEDIA_RESOLUTION_MEDIUM, MEDIA_RESOLUTION_HIGH) para equilibrar o uso de tokens por frame e detalhes visuais.

Guia de início rápido

Antes de começar, autentique-se Cloud de Confiance by S3NS usando o Application Default Credentials (ADC).

No exemplo de código a seguir, substitua PROJECT_ID por seu Cloud de Confiance ID do projeto.

Instalar o SDK

Instale ou atualize o SDK da IA generativa do Google e as dependências de áudio:

pip install --upgrade google-genai websockets numpy

Iniciar uma sessão bidirecional com chamada de função assíncrona

O exemplo a seguir estabelece uma sessão em tempo real com gemini-3.8-live, configura a tendência de vocabulário personalizado e executa chamadas de função assíncronas não bloqueadoras:

import asyncio
from google import genai
from google.genai import types

PROJECT_ID = "PROJECT_ID"
LOCATION = "us-central1"
MODEL_ID = "gemini-3.8-live"

# Initialize the Gen AI client for enterprise.
client = genai.Client(enterprise=True, project=PROJECT_ID, location=LOCATION)

# Define a tool for asynchronous execution.
order_lookup_tool = types.FunctionDeclaration(
    name="lookup_order_status",
    description="Fetches real-time shipping status for a customer order ID.",
    parameters=types.Schema(
        type="OBJECT",
        properties={
            "order_id": types.Schema(
                type="STRING",
                description="The order ID, for example, ORD-8472",
            ),
        },
        required=["order_id"],
    ),
)

# Configure the live connection.
config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    system_instruction=types.Content(
        parts=[
            types.Part.from_text(
                text=(
                    "You are an enterprise concierge. When you call a tool, "
                    "briefly acknowledge the request and tell the user what you're doing. "
                    "If a tool returns no results, inform the user before trying again. "
                    "Never issue more than two consecutive tool calls without speaking."
                )
            )
        ]
    ),
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Aoede")
        ),
    ),
    input_audio_transcription=types.AudioTranscriptionConfig(
        custom_vocabulary=["ORD-8472", "Gemini Live", "Express Shipping"]
    ),
    output_audio_transcription=types.AudioTranscriptionConfig(),
    tools=[types.Tool(function_declarations=[order_lookup_tool])],
)

async def handle_tool_call(session, function_call):
    """Executes backend calls asynchronously without blocking incoming audio."""
    order_id = function_call.args.get("order_id", "")
    await asyncio.sleep(2.0)  # Simulate backend API latency.

    if not order_id.startswith("ORD-"):
        result = {
            "status": "invalid_argument",
            "retryable": False,
            "message": f"Order ID '{order_id}' is invalid. Ask the user to verify.",
        }
    else:
        result = {
            "status": "ok",
            "retryable": False,
            "order_id": order_id,
            "shipping_status": "Out for delivery by 4:00 PM",
        }

    # Send tool response matching the call ID.
    await session.send_tool_response(
        function_responses=[
            types.FunctionResponse(
                id=function_call.id,
                name=function_call.name,
                response=result,
            )
        ]
    )

async def main():
    async with client.aio.live.connect(model=MODEL_ID, config=config) as session:
        print(f"Connected to {MODEL_ID}")

        # Send initial text or stream 16 kHz PCM audio chunks.
        await session.send_realtime_input(
            text="Hi! Can you check the status of order ORD-8472?"
        )

        async for message in session.receive():
            # Handle asynchronous tool calls.
            if message.tool_call:
                for call in message.tool_call.function_calls:
                    asyncio.create_task(handle_tool_call(session, call))

            # Process audio output chunks and transcriptions.
            if message.server_content:
                if (
                    message.server_content.output_transcription
                    and message.server_content.output_transcription.text
                ):
                    print(
                        f"Agent: {message.server_content.output_transcription.text}",
                        end="",
                        flush=True,
                    )

if __name__ == "__main__":
    asyncio.run(main())

Regras e convenções de API necessárias

Ao criar com o 3.8 Live, siga estas convenções de API:

• Respostas de função informativas: não retorne um dicionário vazio ({}) ou None de um gerenciador de ferramentas. Quando uma ferramenta retorna um erro ou um payload vazio, o 3.8 Live pode gerar chamadas de função repetidas com argumentos modificados, a menos que a resposta inclua campos de status. Retorne campos estruturados em todas as respostas de ferramentas:
  • status: uma string de status legível por máquina, como "ok", "no_results" ou "invalid_argument".
  • retryable: definido como false quando a repetição da chamada retorna o mesmo resultado.
  • message ou guidance: texto que especifica o status a ser informado ao usuário.
• Limites de repetição de ferramentas no nível do comando: inclua um limite de repetição na system_instruction. Por exemplo: "Se uma chamada de função não retornar resultados, informe o usuário em vez de pesquisar repetidamente com variações de parâmetros. Nunca execute mais de duas chamadas de função consecutivas sem falar com o usuário."
• Correspondência estrita FunctionResponse:
  • Cada turno de FunctionResponse precisa fornecer o id exato do FunctionCall anterior.
  • Transmita objetos de resposta diretamente em FunctionResponse.response.
• Formatos de áudio de streaming:
  • Áudio de entrada: PCM mono de 16 kHz, 16 bits, little-endian (audio/pcm;rate=16000), transmitido em partes de 20 ms a 100 ms.
  • Áudio de saída: PCM mono de 24 kHz.
• Parâmetros legados removidos: não transmita enable_affective_dialog ou proactivity na configuração. Esses recursos são ativados por padrão no 3.8 Live.
• Histórico de conversas de seeding: se você fizer o seeding do histórico de várias conversas usando send_client_content, aguarde até que o app cliente receba o setup_complete frame do servidor e configure HistoryConfig(initial_history_in_client_content=True).

Migrar para o Gemini 3.8 Live

Para mais informações sobre como migrar de gemini-live-2.5-flash-native-audio para gemini-3.8-live, consulte Migrar do áudio nativo da API Gemini 2.5 Flash Live para o Gemini 3.8 Live.

Lista de verificação do desenvolvedor

Verifique os seguintes itens antes de implantar o app:

Outros recursos

Para saber mais, acesse os recursos a seguir:

• Página do modelo Gemini 3.8 Live
• Configurar avatares em tempo real
• Práticas recomendadas com a API Gemini Live
• Migrar do áudio nativo da API Gemini 2.5 Flash Live para o Gemini 3.8 Live
• Tutorial da API Gemini Live em Python
• Introdução ao notebook de avatar em tempo real
• Habilidade de serviço da API Gemini Live