Iniciar e gerenciar sessões ao vivo

A API Live permite interações de voz e texto com baixa latência ao processar fluxos contínuos de áudio ou texto chamados de sessões para fornecer respostas faladas imediatas e semelhantes às humanas. O gerenciamento do ciclo de vida da sessão, desde o handshake inicial até o encerramento normal, é controlado pelo desenvolvedor.

Nesta página, mostramos como iniciar uma sessão de conversa com modelos do Gemini usando a API Live. É possível iniciar uma sessão usando o Vertex AI Studio, o SDK da IA generativa ou WebSockets.

Esta página também mostra como fazer o seguinte:

  • Estender uma sessão além do limite de tempo padrão
  • Retomar uma sessão anterior
  • Atualizar instruções do sistema durante uma sessão
  • Configurar a janela de contexto de uma sessão
  • Ativar a transcrição de uma sessão

Ciclo de vida da sessão

Sem compressão, as sessões somente de áudio são limitadas a 15 minutos, e as sessões de áudio e vídeo são limitadas a 2 minutos. Se esses limites forem excedidos, a sessão será encerrada, mas você pode usar a compactação da janela de contexto para estender as sessões por um período ilimitado.

A vida útil de uma conexão é limitada a cerca de 10 minutos. Quando a conexão termina, a sessão também é encerrada. Nesse caso, é possível configurar uma única sessão para permanecer ativa em várias conexões usando a retomada de sessão. Você também vai receber uma mensagem GoAway antes do fim da conexão, permitindo que você tome outras medidas.

Máximo de sessões simultâneas

É possível ter até 1.000 sessões simultâneas por projeto em um plano de pagamento por utilização (PayGo). Esse limite não se aplica a clientes que usam taxa de transferência provisionada.

Iniciar uma sessão

As guias a seguir mostram como iniciar uma sessão de conversa em tempo real usando o Vertex AI Studio, o SDK de IA generativa ou WebSockets:

Console

  1. Abra Vertex AI Studio > Transmitir em tempo real.
  2. Clique em Iniciar sessão para começar a conversa.

Para encerrar a sessão, clique em Parar sessão.

Python

Antes de começar, autentique na Vertex AI usando uma chave de API ou credenciais padrão do aplicativo (ADC): 

gcloud auth application-default login

Para mais informações sobre como configurar a autenticação, consulte nosso início rápido. 

import asyncio
from google import genai

# Replace the PROJECT_ID and LOCATION with your Project ID and location. 
client = genai.Client(vertexai=True, project="PROJECT_ID", location="LOCATION")

# Configuration
MODEL = "gemini-live-2.5-flash-preview-native-audio-09-2025"
config = {
   "response_modalities": ["audio"],
}

async def main():
   # Establish WebSocket session
   async with client.aio.live.connect(model=MODEL, config=config) as session:
       print("Session established. Sending audio...")

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

Python

Ao usar WebSockets, a conexão é estabelecida com um handshake padrão do WebSocket. O endpoint é regional e usa tokens de portador do OAuth 2.0 para autenticação. Nesse cenário, o token de autenticação geralmente é transmitido nos cabeçalhos do WebSocket, como Authorization: Bearer [TOKEN]. 

import asyncio
import websockets

# Replace the 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-live-2.5-flash-preview-native-audio-09-2025"
MODEL = f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}"
config = {
   "response_modalities": ["audio"],
}

# 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
           }
       }))
    # Send audio/video ...

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

Ampliar uma sessão

A duração máxima padrão de uma sessão de conversa é de 10 minutos. Uma notificação goAway (BidiGenerateContentServerMessage.goAway) é enviada ao cliente 60 segundos antes do fim da sessão.

É possível aumentar a duração da sessão em incrementos de 10 minutos usando o SDK da IA generativa. Não há limite para o número de vezes que você pode estender uma sessão. Por exemplo, consulte Retomar uma sessão anterior.

Para estender uma sessão:

Python

async for response in session.receive():
    if response.go_away is not None:
        # The connection will soon be terminated
        print(response.go_away.time_left)

Retomar uma sessão anterior

A API Live oferece suporte à retomada de sessão para evitar que o usuário perca o contexto da conversa durante uma breve desconexão (por exemplo, ao mudar do Wi-Fi para o 5G). Você pode retomar uma sessão anterior em até 24 horas. A retomada da sessão é feita armazenando dados em cache, incluindo texto, vídeo, áudio, comandos e saídas do modelo. A privacidade no nível do projeto é aplicada a esses dados armazenados em cache.

Por padrão, a retomada de sessão está desativada. Para ativar a retomada da sessão, defina o campo sessionResumption da mensagem BidiGenerateContentSetup. Se ativado, o servidor envia periodicamente mensagens SessionResumptionUpdate contendo um session_id e um token de retomada. Se o WebSocket for desconectado, o cliente poderá se reconectar e incluir essas credenciais na nova mensagem de configuração. Em seguida, o servidor restaura o contexto anterior, permitindo que a conversa continue sem problemas.

A janela de retomada é finita (geralmente cerca de 10 minutos). Se o cliente não se reconectar dentro desse período, o estado da sessão será descartado para liberar recursos do servidor.

Confira a seguir um exemplo de como ativar a retomada de sessão e recuperar o ID do identificador:

Python

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


# Replace the PROJECT_ID and LOCATION with your Project ID and location. 
client = genai.Client(vertexai=True, project="PROJECT_ID", location="LOCATION")

# Configuration
MODEL = "gemini-live-2.5-flash-preview-native-audio-09-2025"

async def main():
    print(f"Connecting to the service with handle {previous_session_handle}...")
    async with client.aio.live.connect(
        model=MODEL,
        config=types.LiveConnectConfig(
            response_modalities=["audio"],
            session_resumption=types.SessionResumptionConfig(
                # The handle of the session to resume is passed here,
                # or else None to start a new session.
                handle=previous_session_handle
            ),
        ),
    ) as session:
        while True:
            await session.send_client_content(
                turns=types.Content(
                    role="user", parts=[types.Part(text="Hello world!")]
                )
            )
            async for message in session.receive():
                # Periodically, the server will send update messages that may
                # contain a handle for the current state of the session.
                if message.session_resumption_update:
                    update = message.session_resumption_update
                    if update.resumable and update.new_handle:
                        # The handle should be retained and linked to the session.
                        return update.new_handle

                # For the purposes of this example, placeholder input is continually fed
                # to the model. In non-sample code, the model inputs would come from
                # the user.
                if message.server_content and message.server_content.turn_complete:
                    break

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

Ativar a retomada de sessão sem problemas com o modo transparente

Ao ativar a retomada de sessão, você também pode ativar o modo transparente para ajudar a tornar o processo de retomada mais fácil para o usuário. Quando o modo transparente está ativado, o índice da mensagem do cliente que corresponde ao snapshot de contexto é retornado explicitamente. Isso ajuda a identificar qual mensagem do cliente precisa ser enviada novamente quando você retoma a sessão do identificador de retomada.

Para ativar o modo transparente:

Python

config = {
   "response_modalities": ["audio"],
   "session_resumption": {
     "session_resumption_config": {
        "transparent": True,
     }
   }
}

Atualizar instruções do sistema durante uma sessão

Com a API Live, é possível atualizar as instruções do sistema durante uma sessão ativa. Use isso para adaptar as respostas do modelo, como mudar o idioma ou modificar o tom.

Para atualizar as instruções do sistema no meio da sessão, envie conteúdo de texto com a função system. A instrução atualizada vai continuar em vigor durante o restante da sessão.

Python

session.send_client_content(
      turns=types.Content(
          role="system", parts=[types.Part(text="new system instruction")]
      ),
      turn_complete=False
  )

Configurar a janela de contexto da sessão

A janela de contexto da API Live é usada para armazenar dados transmitidos em tempo real (25 tokens por segundo [TPS] para áudio e 258 TPS para vídeo) e outros conteúdos, incluindo entradas de texto e saídas de modelo. Uma sessão tem um limite de janela de contexto de:

  • 128 mil tokens para modelos de áudio nativo
  • 32 mil tokens para outros modelos da API Live

Em sessões longas, conforme a conversa avança, o histórico de tokens de áudio e texto se acumula. Se esse histórico exceder o limite do modelo, ele poderá alucinar, ficar mais lento ou a sessão poderá ser encerrada à força. Para ativar sessões mais longas, habilite a compressão da janela de contexto definindo o campo contextWindowCompression como parte da configuração da sessão.

A compactação da janela de contexto usa uma janela deslizante do lado do servidor para truncar as conversas mais antigas quando ativada. Quando os tokens acumulados excedem um comprimento máximo definido (use o controle deslizante Tamanho máximo do conteúdo no Vertex AI Studio ou trigger_tokens na API), o servidor corta automaticamente as conversas mais antigas ou as resume para manter o contexto dentro do limite. Em ContextWindowCompressionConfig, é possível configurar um mecanismo de janela deslizante e o número de tokens definidos no parâmetro target_tokens que aciona a compactação.

Isso permite durações de sessão teoricamente infinitas do ponto de vista do usuário, já que a "memória" é constantemente gerenciada. Sem compressão, as sessões somente de áudio podem ser limitadas a aproximadamente 15 minutos antes de atingir limites rígidos.

Os comprimentos mínimo e máximo para o comprimento do contexto e o tamanho da meta são:

Configuração (flag da API) Valor mínimo Valor máximo
Tamanho máximo de contexto (trigger_tokens) 5.000 128.000
Tamanho do contexto pretendido (target_tokens) 0 128.000

Para definir a janela de contexto:

Console

  1. Abra Vertex AI Studio > Transmitir em tempo real.
  2. Clique para abrir o menu Avançado.
  3. Na seção Contexto da sessão, use o controle deslizante Tamanho máximo do contexto para definir um valor entre 5.000 e 128.000.
  4. (Opcional) Na mesma seção, use o controle deslizante Tamanho do contexto de destino para definir o tamanho de destino como um valor entre 0 e 128.000.

Python

Defina os campos context_window_compression.trigger_tokens e context_window_compression.sliding_window.target_tokens na mensagem de configuração: 

config = {
   "response_modalities": ["audio"],
   # Configures compression
   "context_window_compression" : {
    "trigger_tokens": 10000,
    "sliding_window": {"target_tokens" : 512}
   }
}

Ativar a transcrição de áudio para a sessão

É possível ativar as transcrições para o áudio de entrada e saída.

Para receber transcrições, atualize a configuração da sessão. É necessário adicionar os objetos input_audio_transcription e output_audio_transcription e garantir que text esteja incluído em response_modalities.

config = {
    "response_modalities": ["audio", "text"],
    "input_audio_transcription": {},
    "output_audio_transcription": {},
}

Processamento da resposta

O exemplo de código a seguir demonstra como se conectar usando a sessão configurada e extrair as partes de texto (transcrições) junto com os dados de áudio.

# Receive Output Loop
async for message in session.receive():
    server_content = message.server_content
    if server_content:
        # Handle Model Turns (Audio + Text)
        model_turn = server_content.model_turn
        if model_turn and model_turn.parts:
            for part in model_turn.parts:
                # Handle Text (Transcriptions)
                if part.text:
                    print(f"Transcription: {part.text}")
                # Handle Audio
                if part.inline_data:
                    audio_data = part.inline_data.data
                    # Process audio bytes...
                    pass

        # Check for turn completion
        if server_content.turn_complete:
            print("Turn complete.")

A seguir