A Google lançou a 15 de setembro de 2026 o Gemini 3.8 Live, o novo modelo de áudio-para-áudio da família Gemini Live API, prometendo respostas de voz quase instantâneas e chamadas de função assíncronas sem cortar o fluxo da conversa. Para quem já brincou com chatbots de texto, a diferença é enorme: em vez de escrever e esperar por uma resposta, fala-se com o modelo como se fosse uma chamada telefónica, com interrupções, tom natural e latência baixa. Este tutorial mostra, passo a passo, como configurar a Gemini API para criar um assistente de voz funcional do zero, com código real em Python, tratamento de erros e um projeto completo no fim.

Vamos usar o SDK oficial google-genai, ligar por WebSocket ao modelo gemini-3.8-live, capturar áudio do microfone, transmiti-lo em streaming e reproduzir a resposta falada em tempo real. No final, terá uma base de código pronta para expandir com ferramentas externas, deteção de interrupção e proteção por tokens efémeros. Tempo estimado: cerca de 60 minutos, incluindo testes.

Este guia foi pensado para quem já programa em Python mas nunca mexeu numa API de streaming de áudio. Não é preciso experiência prévia com WebSockets nem com processamento de sinal: cada passo explica o porquê antes do como, e o código está comentado em português para facilitar a leitura. Se já usou a Gemini API de texto antes, vai reconhecer o padrão geral, mas vai notar rapidamente que uma conversa por voz introduz problemas novos, como a gestão de buffers de áudio e a interrupção em tempo real, que simplesmente não existem numa API de texto tradicional.

O Que É a Gemini Live API e o Que Muda com o Gemini 3.8 Live

A Gemini Live API é uma API de streaming bidirecional, assente numa ligação WebSocket com estado (stateful), pensada para interações de voz e vídeo em tempo real com os modelos Gemini. Ao contrário da API de texto tradicional, onde se envia um pedido e se espera pela resposta completa, a Live API mantém a ligação aberta e troca pequenos blocos de áudio (ou vídeo) em ambos os sentidos, o que permite conversas naturais, com pausas, interrupções e reações quase imediatas.

O Gemini 3.8 Live, anunciado no blogue oficial da Google, é hoje o modelo recomendado para experiências de agente de voz com baixa latência e diálogo em tempo real sem atrasos de raciocínio, segundo a própria documentação da Google. Existe também uma variante chamada Gemini 3.8 Live Extended Thinking, que continua a raciocinar em segundo plano enquanto já está a responder por voz, útil para pedidos que exigem mais do que uma resposta imediata e direta. Ambos os modelos usam a mesma Live API e o mesmo fluxo de trabalho que vamos construir neste tutorial.

Entre as capacidades confirmadas na documentação oficial estão a chamada de funções assíncrona (o modelo pode acionar uma ferramenta externa sem parar de falar), a interrupção por voz (o utilizador pode cortar a resposta do modelo a meio da frase) e o suporte a 97 línguas, com troca de idioma a meio da conversa em vez de ficar preso à língua definida no início da sessão. A janela de contexto do Gemini 3.8 Live é de 128 mil tokens, suficiente para manter o histórico de uma conversa longa sem perder informação relevante.

Gemini 3.8 Live vs Outros Modelos da Família Live API

ModeloID OficialContextoPreço Áudio EntradaPreço Áudio SaídaDestaque
Gemini 3.8 Livegemini-3.8-live128 mil tokens$0,005/min$0,018/minFunction calling assíncrono, baixa latência
Gemini 3.8 Live Extended ThinkingVia Live API128 mil tokens$0,005/min$0,018/minRaciocínio em segundo plano durante a fala
Gemini 3.5 Live Translate Previewgemini-3.5-live-translate-previewNão divulgadoNão divulgadoNão divulgadoTradução voz-a-voz de baixa latência
Gemini 3.1 Flash LiveDisponível no AI Studio LiveNão divulgadoNão divulgadoNão divulgadoGeração anterior, ainda ativa em produção
Gemini 2.5 Flash Live PreviewReferenciado em tabelas de capacidadesNão divulgadoNão divulgadoNão divulgadoModelo Live de gerações anteriores

Note que a Google não publicou todos os preços e limites para os modelos Live mais antigos nas fontes consultadas para este artigo, por isso essas células aparecem como “não divulgado” em vez de um valor inventado. Para o Gemini 3.8 Live, que é o modelo central deste tutorial, os números vêm diretamente do anúncio oficial da Google sobre aplicações de voz em tempo real.

Pré-Requisitos: o Que Precisa Antes de Começar

Antes de escrever a primeira linha de código, confirme que tem tudo isto preparado. Saltar esta lista costuma ser a razão número um de sessões de teste que falham logo na ligação.

  • Uma conta Google e acesso ao Google AI Studio para gerar a chave de API
  • Python 3.10 ou superior instalado (o SDK google-genai assume async/await nativo)
  • Node.js 20 ou superior, caso prefira construir o cliente de voz em JavaScript
  • O SDK oficial google-genai (instalado via pip, versão mais recente disponível no PyPI)
  • Uma biblioteca de áudio como sounddevice ou pyaudio, mais numpy, para captar e reproduzir som
  • Um microfone funcional e colunas ou auscultadores (auscultadores evitam eco durante os testes)
  • Ligação à internet estável, já que a Live API depende de uma ligação WebSocket contínua
  • Familiaridade básica com programação assíncrona em Python (async/await)

Se pretende usar a Live API diretamente no browser, vai também precisar de um pequeno servidor backend para gerar tokens efémeros, um ponto que explicamos em detalhe no passo 10. Não é recomendável colocar a chave de API principal diretamente no código do lado do cliente.

Vale ainda confirmar dois pormenores de sistema operativo antes de avançar. No Linux, pode ser necessário instalar o pacote portaudio19-dev através do gestor de pacotes da distribuição para que o sounddevice consiga aceder ao microfone corretamente. No macOS e no Windows, a primeira execução do script vai normalmente pedir permissão explícita de acesso ao microfone: aceite esse pedido antes de testar qualquer um dos exemplos de código que se seguem, caso contrário a captura de áudio falha silenciosamente sem nenhuma mensagem de erro óbvia.

Passo 1: Criar a Chave de API no Google AI Studio

Comece por aceder ao Google AI Studio com a sua conta Google. Na secção de chaves de API, crie uma nova chave associada a um projeto (novo ou existente). Guarde essa chave num local seguro, nunca a inclua diretamente num repositório público nem a publique em código-fonte partilhado. Para este tutorial, vamos guardá-la como variável de ambiente chamada GEMINI_API_KEY.

Depois de criar a chave, confirme no painel do AI Studio que o seu projeto tem acesso à Live API e ao modelo gemini-3.8-live. Nem todas as contas gratuitas têm acesso imediato a modelos de pré-visualização, por isso vale a pena verificar a disponibilidade antes de avançar para o código.

export GEMINI_API_KEY="a_sua_chave_aqui"

Passo 2: Preparar o Ambiente e Instalar o SDK google-genai

Com a chave de API pronta, crie uma pasta para o projeto e um ambiente virtual Python. Isto evita conflitos de versões com outros projetos que já tenha instalados na máquina.

mkdir assistente-voz-gemini
cd assistente-voz-gemini
python3 -m venv venv
source venv/bin/activate
pip install --upgrade google-genai sounddevice numpy websockets

O pacote google-genai é o SDK oficial da Google para a Gemini API e inclui suporte à Live API através de uma interface assíncrona de alto nível, que trata da gestão da ligação WebSocket por nós. As bibliotecas sounddevice e numpy vão servir para captar áudio do microfone e reproduzir a resposta do modelo. Se preferir JavaScript, o equivalente passa por instalar o pacote oficial via npm e usar a Web Audio API do browser para captura e reprodução.

Passo 3: Estabelecer a Primeira Ligação WebSocket à Live API

Chegou o momento de testar a ligação. O SDK google-genai expõe um cliente assíncrono que gere a sessão Live por nós, incluindo o handshake WebSocket e o envio da configuração inicial do modelo.

import asyncio
import os
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
MODEL = "gemini-3.8-live"

async def testar_ligacao():
    config = {"response_modalities": ["AUDIO"]}
    async with client.aio.live.connect(model=MODEL, config=config) as sessao:
        print("Sessão Live estabelecida com sucesso.")
        await sessao.send_client_content(
            turns={"role": "user", "parts": [{"text": "Olá, consegues ouvir-me?"}]},
            turn_complete=True,
        )
        async for resposta in sessao.receive():
            if resposta.text:
                print("Texto recebido:", resposta.text)
            if resposta.data:
                print("Recebidos", len(resposta.data), "bytes de áudio")

asyncio.run(testar_ligacao())

Se tudo correr bem, deve ver a mensagem de sessão estabelecida seguida de blocos de áudio a chegar em poucos segundos. Se a ligação falhar aqui, o problema está quase sempre relacionado com a chave de API ou com o acesso ao modelo, e não com o resto do código que vamos construir a seguir.

Repare que este teste inicial usa send_client_content para enviar texto, não áudio. É uma forma rápida de confirmar que a sessão, a autenticação e o modelo estão todos a funcionar antes de complicar o código com captura de microfone e reprodução de som. Só depois de ver a resposta de texto ou os primeiros bytes de áudio a chegar é que vale a pena avançar para os passos seguintes, que introduzem streaming de áudio real.

Passo 4: Configurar o Modelo e o speechConfig

A configuração da sessão é onde se define como o modelo deve responder: em texto, em áudio, ou em ambos, qual a voz a usar e que instruções de sistema seguir. O parâmetro speechConfig permite escolher entre as vozes disponíveis nos modelos de texto-para-fala da Google, e o modelo pode alternar entre as 97 línguas suportadas sem ficar preso à língua definida no arranque da sessão.

config = {
    "response_modalities": ["AUDIO"],
    "speech_config": {
        "voice_config": {
            "prebuilt_voice_config": {"voice_name": "Aoede"}
        }
    },
    "system_instruction": (
        "Fala sempre em português de Portugal, de forma curta, "
        "clara e simpática, como um assistente pessoal."
    ),
}

Ajuste a instrução de sistema conforme o caso de uso: um assistente de apoio ao cliente precisa de um tom diferente de um tutor de línguas ou de um agente técnico. Como o Gemini 3.8 Live suporta troca de idioma a meio da conversa, pode testar dizer uma frase em inglês a meio de uma conversa em português e verificar como o modelo reage.

Note que a configuração é enviada apenas uma vez, no momento em que a sessão é aberta com client.aio.live.connect. Se precisar de mudar de voz ou de instrução de sistema a meio da conversa, a forma mais simples é fechar a sessão atual e abrir uma nova com a configuração atualizada, reaproveitando o histórico relevante como contexto inicial, tal como vamos explicar no passo 11 sobre gestão de sessões longas.

Passo 5: Capturar Áudio do Microfone em PCM de 16 kHz

A Live API espera áudio de entrada em formato PCM de 16 bits, a 16 kHz, little-endian, segundo a documentação oficial da Gemini API. Enviar áudio noutro formato é uma das causas mais comuns de falhas silenciosas, em que a sessão parece ativa mas o modelo nunca responde. Usamos a biblioteca sounddevice para capturar áudio diretamente do microfone já no formato correto.

import sounddevice as sd
import numpy as np

TAXA_ENTRADA = 16000
TAMANHO_BLOCO = 1024

def capturar_audio(fila_saida):
    def callback(indata, frames, time, status):
        fila_saida.put_nowait(indata.copy().tobytes())

    stream = sd.InputStream(
        samplerate=TAXA_ENTRADA,
        channels=1,
        dtype="int16",
        blocksize=TAMANHO_BLOCO,
        callback=callback,
    )
    return stream

Este trecho cria um stream de entrada que corre em segundo plano e vai colocando blocos de áudio numa fila assíncrona, prontos a serem enviados para a API. Manter os blocos pequenos, entre 20 e 50 milissegundos de áudio, ajuda a reduzir a latência percebida pelo utilizador, já que o modelo começa a processar o som quase assim que ele é captado.

Um detalhe fácil de ignorar: o parâmetro channels=1 força a captura em mono, o que é intencional. A Live API não precisa de áudio estéreo para reconhecer fala, e enviar dois canais em vez de um duplica desnecessariamente a quantidade de dados transmitidos, sem qualquer ganho de qualidade percebida na transcrição ou na resposta do modelo.

Passo 6: Transmitir Áudio em Streaming Para a API

Com o áudio a ser captado em blocos pequenos, o próximo passo é enviá-lo continuamente para a sessão Live, sem esperar por uma frase completa. É esta transmissão contínua que torna a conversa fluida, em vez de um sistema de gravar, enviar e esperar, como em muitos assistentes de voz mais antigos.

import asyncio

async def enviar_audio(sessao, fila_entrada):
    while True:
        bloco = await fila_entrada.get()
        await sessao.send_realtime_input(
            audio={"data": bloco, "mime_type": "audio/pcm;rate=16000"}
        )

Esta função corre indefinidamente enquanto a sessão estiver aberta, retirando blocos de áudio da fila assim que ficam disponíveis. É importante correr esta tarefa em paralelo com a tarefa que recebe as respostas do modelo, usando asyncio.gather ou tarefas separadas, para que o envio e a receção de áudio aconteçam ao mesmo tempo, sem bloquear um o outro.

Se a sua fila de áudio crescer sem parar, é sinal de que o envio está mais lento do que a captura, normalmente porque a ligação à internet não aguenta o débito necessário. Nesse caso, vale a pena descartar blocos antigos da fila em vez de deixá-la crescer indefinidamente, já que enviar áudio muito atrasado só piora a experiência de conversa em vez de a melhorar.

Passo 7: Reproduzir a Resposta em Áudio de 24 kHz

A resposta do modelo chega também em PCM de 16 bits, mas a uma taxa de amostragem diferente da entrada: 24 kHz em vez de 16 kHz. Reproduzir esse áudio à taxa errada é outra causa frequente de voz robotizada, demasiado grave ou demasiado aguda. O código abaixo recebe os blocos de áudio da sessão e envia-os para a saída de som do sistema.

TAXA_SAIDA = 24000

async def reproduzir_resposta(sessao):
    stream_saida = sd.RawOutputStream(
        samplerate=TAXA_SAIDA, channels=1, dtype="int16"
    )
    stream_saida.start()
    async for resposta in sessao.receive():
        if resposta.data is not None:
            stream_saida.write(resposta.data)
        if resposta.text:
            print("[transcrição]", resposta.text)

Ao juntar as três tarefas, captura, envio e reprodução, num único programa com asyncio.gather, já tem um assistente de voz básico a funcionar de ponta a ponta: fala para o microfone e ouve a resposta do Gemini 3.8 Live quase em tempo real.

Antes de avançar, vale confirmar que o volume de saída não está demasiado baixo nem a cortar (clipping). Um sinal comum de configuração errada é ouvir a voz do assistente aos solavancos, com pequenos silêncios entre palavras: isso costuma indicar que o stream de saída está a ficar sem dados no buffer por breves instantes, um problema que resolvemos com mais detalhe na secção de resolução de problemas mais à frente neste artigo.

Passo 8: Ativar Deteção de Interrupção (Barge-In)

Uma conversa real inclui interrupções: o utilizador começa a falar antes de o assistente terminar a frase. A documentação da Vertex AI para a Live API confirma que é possível interromper as respostas do modelo com comandos de voz, ou seja, a interrupção é tratada nativamente pela API assim que deteta nova fala de entrada enquanto ainda está a enviar áudio de saída.

Na prática, isto significa que o seu código cliente deve continuar a enviar áudio do microfone mesmo enquanto reproduz a resposta do modelo, sem pausar a captura à espera de silêncio. Quando o servidor deteta a nova fala, envia um evento a indicar que a resposta anterior foi interrompida, e cabe à aplicação parar imediatamente a reprodução do áudio que ainda estava em buffer, para não sobrepor as duas vozes.

async def reproduzir_com_interrupcao(sessao, stream_saida):
    async for resposta in sessao.receive():
        if getattr(resposta, "interrupted", False):
            stream_saida.abort()  # limpa o buffer de áudio pendente
            continue
        if resposta.data is not None:
            stream_saida.write(resposta.data)

Teste este comportamento falando por cima da resposta do assistente durante os primeiros testes. Se a voz do modelo continuar a sair mesmo depois de começar a falar, o problema está quase sempre em não limpar o buffer de reprodução local a tempo.

Passo 9: Adicionar Function Calling Assíncrono

Uma das novidades do Gemini 3.8 Live, segundo o changelog oficial da Gemini API, é a chamada de funções assíncrona: o modelo pode executar chamadas a ferramentas ou APIs externas em segundo plano, continuando a transmitir áudio de resposta ao utilizador sem parar a conversa à espera do resultado. Isto é diferente do function calling tradicional em modelos de texto, onde normalmente se espera pela resposta da ferramenta antes de continuar.

ferramenta_tempo = {
    "name": "obter_previsao_tempo",
    "description": "Devolve a previsão do tempo para uma cidade",
    "parameters": {
        "type": "object",
        "properties": {
            "cidade": {"type": "string"},
        },
        "required": ["cidade"],
    },
}

config = {
    "response_modalities": ["AUDIO"],
    "tools": [{"function_declarations": [ferramenta_tempo]}],
}

async def tratar_chamadas_funcao(sessao):
    async for resposta in sessao.receive():
        if resposta.tool_call:
            for chamada in resposta.tool_call.function_calls:
                if chamada.name == "obter_previsao_tempo":
                    cidade = chamada.args["cidade"]
                    resultado = {"temperatura": "22°C", "condicao": "sol"}
                    await sessao.send_tool_response(
                        function_responses=[
                            {"id": chamada.id, "name": chamada.name, "response": resultado}
                        ]
                    )

Substitua o resultado fixo por uma chamada real à sua API de meteorologia, base de dados ou serviço interno. O importante é que a resposta da ferramenta é enviada de volta à sessão através de send_tool_response, e o modelo incorpora essa informação na conversa em curso, sem obrigar a reiniciar a sessão de voz.

Vale a pena declarar várias ferramentas diferentes na mesma configuração de sessão (por exemplo, uma para consultar o tempo, outra para consultar uma agenda e outra para pesquisar num catálogo de produtos), já que o modelo escolhe sozinho qual delas faz sentido para cada pedido do utilizador, sem que o programador precise de interpretar manualmente a intenção da frase. Esta é a mesma lógica de function calling já conhecida da Gemini API de texto, apenas adaptada ao contexto de uma conversa falada e contínua.

Passo 10: Proteger o Cliente com Tokens Efémeros

A documentação da Gemini Live API destaca os tokens efémeros como uma funcionalidade central para gerir sessões e proteger o uso do lado do cliente. Em vez de colocar a chave de API principal num browser ou numa app móvel, onde qualquer pessoa a pode inspecionar, um pequeno servidor backend gera um token de curta duração, válido apenas para abrir uma sessão Live, e é esse token que o cliente usa para ligar à API.

# servidor.py – endpoint simples para gerar tokens efémeros
from flask import Flask, jsonify
from google import genai
import os

app = Flask(__name__)
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

@app.route("/token-efemero", methods=["POST"])
def gerar_token():
    token = client.auth_tokens.create(
        config={"uses": 1, "expire_time_seconds": 60}
    )
    return jsonify({"token": token.name})

if __name__ == "__main__":
    app.run(port=5000)

O cliente (browser ou app móvel) faz um pedido a este endpoint antes de abrir a ligação Live, recebe o token e usa-o em vez da chave principal. Como o token expira rapidamente e serve apenas para uma utilização, o risco de exposição é muito menor do que colocar a chave de API diretamente no código do lado do cliente.

Numa aplicação real, este endpoint deve estar protegido pela sua própria camada de autenticação de utilizador, para que só clientes autenticados na sua aplicação consigam pedir um token efémero. Sem essa camada extra, qualquer pessoa que descubra o endereço do endpoint poderia gerar tokens à vontade e consumir minutos de streaming à sua conta, mesmo sem nunca ver a chave de API principal.

Passo 11: Gerir Duração de Sessão e Limite de Contexto

A Live API impõe limites de duração por sessão: sessões apenas com áudio ficam limitadas a 15 minutos, enquanto sessões que combinam áudio e vídeo ficam limitadas a 2 minutos, de acordo com a documentação técnica consultada para este tutorial. Para uma aplicação de produção, isto significa que a sua aplicação precisa de um plano para o que acontece quando esse limite é atingido a meio de uma conversa.

LIMITE_SESSAO_SEGUNDOS = 14 * 60  # margem de segurança antes dos 15 min

async def gerir_sessao_com_renovacao(config):
    while True:
        async with client.aio.live.connect(model=MODEL, config=config) as sessao:
            inicio = asyncio.get_event_loop().time()
            while asyncio.get_event_loop().time() - inicio < LIMITE_SESSAO_SEGUNDOS:
                await asyncio.sleep(1)
            print("A aproximar-se do limite de sessão, a reconectar...")

Uma estratégia prática é avisar o utilizador com alguns segundos de antecedência, algo como "vou só recarregar a ligação, um segundo", e reabrir a sessão de forma transparente, reenviando o histórico relevante da conversa como contexto inicial da nova sessão. A Google documenta atualizações completas do conteúdo da sessão por parte do cliente como funcionalidade suportada, o que ajuda a reconstruir o estado sem perder o fio à conversa.

Passo 12: Testar Latência e Validar a Saída

Com todas as peças montadas, é hora de testar o assistente de ponta a ponta. Corra o script principal, fale uma frase simples como "que horas são em Lisboa" e cronometre o tempo entre o fim da sua frase e o início da resposta em áudio. Um bom resultado para uma configuração local e uma ligação estável fica normalmente abaixo de um segundo.

$ python assistente.py
Sessão Live estabelecida com sucesso.
[utilizador fala] "Olá, consegues ouvir-me?"
[transcrição] Olá! Sim, estou a ouvir-te perfeitamente. Como posso ajudar?
Recebidos 3840 bytes de áudio
Recebidos 3840 bytes de áudio
Latência primeiro byte de áudio: 0.71s

Se a latência estiver muito acima disto, reveja o tamanho dos blocos de áudio enviados, já que blocos grandes atrasam o início do processamento, e confirme que a sua rede não está a introduzir atrasos adicionais, por exemplo através de uma VPN lenta. Depois de validar a latência, teste também os cenários de erro: desligue o Wi-Fi a meio de uma frase e veja se a lógica de reconexão do passo 11 recupera a sessão sem travar a aplicação.

Preços e Limites da Gemini Live API

RecursoValorFonte
Preço áudio de entrada$0,005 por minutoBlog oficial da Google (setembro 2026)
Preço áudio de saída$0,018 por minutoBlog oficial da Google
Duração máxima de sessão (só áudio)15 minutosDocumentação da Live API
Duração máxima de sessão (áudio + vídeo)2 minutosDocumentação da Live API
Janela de contexto (Gemini 3.8 Live)128 mil tokensDocumentação do modelo
Línguas suportadas97 línguasDocumentação da Live API
Formato de áudio de entradaPCM 16 bits, 16 kHzDocumentação da Live API
Formato de áudio de saídaPCM 16 bits, 24 kHzDocumentação da Live API

5 Erros Comuns ao Implementar a Gemini Live API

  • Enviar áudio no formato errado. A Live API espera PCM de 16 bits a 16 kHz na entrada. Enviar MP3, WAV comprimido ou uma taxa de amostragem diferente costuma resultar em silêncio ou respostas sem sentido, sem uma mensagem de erro clara.
  • Ignorar o limite de duração da sessão. Sessões só de áudio cortam-se aos 15 minutos. Sem lógica de reconexão, o utilizador fica a meio de uma frase quando a ligação cai sem aviso.
  • Expor a chave de API no código do cliente. Colocar a chave principal num browser ou numa app móvel é um convite a abuso de faturação. Use sempre tokens efémeros gerados pelo backend, como no passo 10.
  • Não implementar deteção de interrupção. Sem tratar o evento de interrupção, o assistente continua a falar por cima do utilizador, o que torna a experiência frustrante muito depressa.
  • Ignorar falhas de rede no WebSocket. Uma ligação instável vai cair mais cedo ou mais tarde. Sem reconexão automática, a aplicação trava em silêncio em vez de recuperar.
  • Bloquear o fluxo à espera de function calling síncrono. Tratar a chamada de função como bloqueante anula a vantagem do modelo assíncrono do Gemini 3.8 Live, que foi pensado para continuar a falar enquanto espera pelo resultado da ferramenta.
  • Presumir que todas as línguas funcionam sem testar. Com 97 línguas suportadas, vale a pena testar especificamente os idiomas relevantes para os seus utilizadores antes de lançar em produção, sobretudo em trocas de idioma a meio da frase.

Resolução de Problemas: 8 Situações Frequentes

ProblemaCausa provávelSolução
WebSocket fecha com código 1006Rede instável ou token expiradoImplementar reconexão automática com espera crescente entre tentativas
Áudio sai robotizado ou distorcidoTaxa de amostragem errada no envio (diferente de 16 kHz)Reamostrar o áudio para PCM 16 bits a 16 kHz antes de enviar
Latência acima de 1 segundoBlocos de áudio demasiado grandesReduzir os blocos enviados para 20-50 milissegundos de áudio
Function calling nunca disparaFerramenta não declarada corretamente na configuração da sessãoConfirmar a estrutura de tools e function_declarations na config
Sessão cai aos 15 minutos sem avisoLimite de sessão de áudio da Live API atingidoReconectar com margem de segurança antes do limite, como no passo 11
Erro de autenticação 401 ou 403Chave de API inválida ou sem acesso à Live APIGerar nova chave no AI Studio e confirmar o acesso ao modelo Live
Microfone não é captado no browserPermissões de áudio bloqueadas ou página sem HTTPSServir a aplicação via HTTPS e pedir permissão explícita ao utilizador
Reprodução de áudio com cortesBuffer de reprodução a esvaziar mais depressa do que os dados chegamAumentar o tamanho do buffer de saída no cliente de áudio
Idioma não muda a meio da conversaspeechConfig fixado a uma só língua desde o inícioConfirmar que a troca dinâmica de idioma está ativa na instrução de sistema
Custo mensal mais alto que o esperadoSessões abertas sem input a consumir minutos de streamingFechar sessões inativas e monitorizar o consumo no painel de faturação

Dicas Avançadas e Projeto Completo

Para levar este projeto de protótipo local a algo pronto para produção, vale a pena considerar algumas práticas adicionais. Primeiro, evite construir toda a infraestrutura de streaming de áudio do zero: a Google refere parcerias com plataformas como Agora, Fishjam, LiveKit, LangChain, Pipecat, Vercel e Vision Agents, que já resolvem problemas de rede, reconexão e escala para aplicações de voz em produção, integrando-se com a Live API por baixo.

Segundo, separe claramente a lógica do assistente, ou seja o que ele faz, que ferramentas usa e que tom mantém, da camada de transporte de áudio. Isto facilita testes automatizados, já que pode simular o texto de entrada e saída sem depender de um microfone real em cada execução de testes. Terceiro, registe métricas desde o início: latência do primeiro byte de áudio, taxa de interrupções por sessão e minutos consumidos por utilizador ajudam a detetar problemas de custo ou de qualidade antes que se tornem críticos.

Um quarto ponto, muitas vezes esquecido até acontecer: defina um limite máximo de minutos por utilizador e por dia antes de lançar o assistente ao público. Como a faturação é por minuto de áudio de entrada e de saída, uma sessão esquecida aberta durante horas, por exemplo por um separador de browser que ninguém fechou, pode gerar uma fatura desproporcional face ao uso real da aplicação. Um corte automático de segurança, para além do limite natural de 15 minutos por sessão, protege o orçamento sem prejudicar a experiência de quem usa o assistente normalmente.

A estrutura de um projeto completo, juntando tudo o que foi construído neste tutorial, fica assim:

assistente-voz-gemini/
├── venv/
├── servidor.py           # gera tokens efémeros (passo 10)
├── assistente.py         # liga à Live API, captura e reproduz áudio
├── ferramentas.py        # declarações e handlers de function calling
├── config.py             # speechConfig, system_instruction, tools
└── requirements.txt      # google-genai, sounddevice, numpy, flask, websockets

O ficheiro assistente.py junta as funções dos passos 5 a 9 numa única corrida com asyncio.gather, tratando em simultâneo a captura de áudio, o envio em streaming, a receção com deteção de interrupção e as chamadas de função. O código completo dos exemplos oficiais da Google, incluindo variantes em várias linguagens, está disponível no repositório de exemplos da Gemini Live API no GitHub, útil como referência para comparar com a sua implementação.

Perguntas Frequentes

O que é a Gemini Live API e em que difere da Gemini API normal?

A Gemini API tradicional funciona por pedido-resposta: envia um prompt e recebe uma resposta completa. A Gemini Live API mantém uma ligação WebSocket aberta e permite streaming bidirecional de áudio (e vídeo), pensada especificamente para conversas de voz em tempo real, com interrupções e latência baixa.

Preciso de pagar para testar a Gemini Live API?

A utilização do Gemini 3.8 Live é faturada por minuto, a $0,005 por minuto de áudio de entrada e $0,018 por minuto de áudio de saída, segundo o anúncio oficial da Google. Verifique no painel do AI Studio se a sua conta tem algum crédito ou limite gratuito disponível antes de começar a testar de forma intensiva.

Que linguagens de programação são suportadas pelo SDK?

O SDK oficial google-genai é o caminho documentado pela Google para aceder à Live API, com uma interface assíncrona para gerir sessões WebSocket. Este tutorial usa Python, mas os exemplos oficiais no GitHub cobrem também outras linguagens para quem prefira construir o cliente fora do ecossistema Python.

O Gemini 3.8 Live funciona bem em português?

A documentação da Live API indica suporte a 97 línguas, com troca dinâmica de idioma a meio da conversa. O português está entre as línguas suportadas pelos modelos de texto-para-fala da Google usados no speechConfig, como demonstrado no passo 4 deste tutorial.

Qual a diferença entre Gemini 3.8 Live e Gemini 3.8 Live Extended Thinking?

O Gemini 3.8 Live normal foca-se em respostas rápidas e diretas, ideal para diálogo simples. A variante Extended Thinking continua a raciocinar em segundo plano enquanto já está a falar, o que é útil para pedidos mais complexos que exigem alguma análise antes ou durante a resposta.

Posso usar a Live API diretamente no browser sem servidor backend?

Tecnicamente é possível ligar diretamente a partir do browser, mas não é recomendável fazê-lo com a chave de API principal exposta no código do cliente. A prática recomendada, descrita no passo 10, é usar um pequeno servidor backend para gerar tokens efémeros de curta duração, que o browser usa em vez da chave principal.

Quanto tempo pode durar uma sessão de voz?

Sessões só com áudio ficam limitadas a 15 minutos, enquanto sessões que combinam áudio e vídeo ficam limitadas a 2 minutos, de acordo com a documentação técnica da Live API. Para conversas mais longas, é necessário implementar lógica de reconexão, como mostrado no passo 11.

A Live API suporta chamadas a ferramentas externas (function calling)?

Sim. O Gemini 3.8 Live suporta function calling assíncrono, o que significa que pode acionar uma API externa, como uma base de dados ou serviço de meteorologia, sem interromper o fluxo de áudio da conversa, como demonstrado no passo 9 deste tutorial.