Iniciar y gestionar sesiones en directo

La API Gemini Live permite interacciones de voz y texto con baja latencia procesando flujos continuos de audio o texto llamados sesiones para ofrecer respuestas habladas inmediatas y similares a las de los humanos. El desarrollador controla la gestión del ciclo de vida de la sesión, desde el handshake inicial hasta la finalización correcta.

En esta página se explica cómo iniciar una sesión de conversación con modelos de Gemini mediante la API Gemini Live. Puedes iniciar una sesión con Vertex AI Studio, el SDK de IA generativa o WebSockets.

En esta página también se explica cómo hacer lo siguiente:

• Prolongar una sesión más allá del límite de tiempo predeterminado
• Reanudar una sesión anterior
• Actualizar las instrucciones del sistema durante una sesión
• Configurar la ventana de contexto de una sesión
• Habilitar la transcripción de una sesión

Tiempo de vida de la sesión

Sin compresión, las sesiones de solo audio están limitadas a 15 minutos y las sesiones de audio y vídeo, a 2 minutos. Si superas estos límites, la sesión finalizará, pero puedes usar la compresión de la ventana de contexto para ampliar las sesiones durante un tiempo ilimitado.

La duración de una conexión está limitada a unos 10 minutos. Cuando se cierra la conexión, también se cierra la sesión. En este caso, puede configurar una sola sesión para que permanezca activa en varias conexiones mediante la reanudación de la sesión. También recibirás un GoAway mensaje antes de que finalice la conexión, lo que te permitirá tomar más medidas.

Número máximo de sesiones simultáneas

Puedes tener hasta 1000 sesiones simultáneas por proyecto en un plan de pago por uso (PayGo). Este límite no se aplica a los clientes que usan Provisioned Throughput.

Iniciar una sesión

En las siguientes pestañas se muestra cómo iniciar una sesión de conversación en directo con Vertex AI Studio, el SDK de IA generativa o WebSockets:

Consola

1. Abre Vertex AI Studio > Stream realtime (Vertex AI Studio > Transmitir en tiempo real).
2. Haz clic en Iniciar sesión para iniciar la conversación.

Para finalizar la sesión, haz clic en Detener sesión.

Python

Antes de empezar, debes autenticarte en Vertex AI mediante una clave de API o las credenciales predeterminadas de la aplicación (ADC):

gcloud auth application-default login
      

Para obtener más información sobre cómo configurar la autenticación, consulta nuestra guía de inicio 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

Cuando se usan WebSockets, la conexión se establece con un handshake de WebSocket estándar. El endpoint es regional y usa tokens de portador de OAuth 2.0 para la autenticación. En este caso, el token de autenticación se suele enviar en los encabezados de 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())
      

Nota: Aunque algunos parámetros, como las instrucciones del sistema, se pueden ajustar durante la sesión, el modelo y otros parámetros suelen ser inmutables una vez que se procesa el mensaje de configuración.

Prolongar una sesión

Nota: La extensión de sesión solo está disponible cuando se usa el SDK de IA generativa, no Vertex AI Studio.

La duración máxima predeterminada de una sesión de conversación es de 10 minutos. Se envía una goAway notificación (BidiGenerateContentServerMessage.goAway) al cliente 60 segundos antes de que finalice la sesión.

Para prolongar una sesión más allá del límite de conexión de 10 minutos, debes volver a conectarte mediante la reanudación de la sesión. Cuando recibas una notificación goAway o cuando se termine la conexión por otros motivos, podrás iniciar una nueva conexión con un identificador de sesión obtenido durante la sesión. De esta forma, se reanudará tu sesión con el contexto intacto en la nueva conexión. No hay límite en el número de veces que puedes hacerlo. Para ver un ejemplo de cómo reanudar una sesión, consulta Reanudar una sesión anterior.

En el siguiente ejemplo se muestra cómo detectar la finalización inminente de una sesión escuchando una notificación goAway:

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)
      

Reanudar una sesión anterior

Importante: Si necesitas asegurarte de que no se conserven datos en tu aplicación, no habilites la reanudación de la sesión.

La API Gemini Live admite la reanudación de sesiones para evitar que el usuario pierda el contexto de la conversación durante una breve desconexión (por ejemplo, al cambiar de Wi-Fi a 5G). Puedes reanudar una sesión anterior en un plazo de 24 horas. La reanudación de la sesión se consigue almacenando datos en caché, como texto, vídeo, peticiones de audio y salidas del modelo. La privacidad a nivel de proyecto se aplica a estos datos almacenados en caché.

De forma predeterminada, la reanudación de la sesión está inhabilitada. Para habilitar la reanudación de sesiones, define el campo sessionResumption del mensaje BidiGenerateContentSetup. Si está habilitado, el servidor envía periódicamente SessionResumptionUpdate mensajes que contienen un session_id y un token de reanudación. Si el WebSocket se desconecta, el cliente puede volver a conectarse e incluir estas credenciales en el nuevo mensaje de configuración. A continuación, el servidor restaura el contexto anterior, lo que permite que la conversación continúe sin problemas.

El periodo de reanudación es finito (normalmente, unos 10 minutos). Si el cliente no vuelve a conectarse en ese plazo, el estado de la sesión se descarta para liberar recursos del servidor.

En el siguiente ejemplo se conecta al servicio, obtiene un controlador de reanudación de sesión, simula una desconexión y, a continuación, se vuelve a conectar mediante el controlador para reanudar la sesión:

Python

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

# 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 resumable_session_example():
    """Demonstrates session resumption by connecting, disconnecting, and reconnecting."""
    session_handle = None

    print("Starting a new session...")
    try:
        async with client.aio.live.connect(
            model=MODEL,
            config=types.LiveConnectConfig(
                response_modalities=["audio"],
                session_resumption_config=types.SessionResumptionConfig(handle=None),
            ),
        ) as session:
            await session.send_content(
                content=types.Content(role="user", parts=[types.Part(text="Hello!")])
            )
            async for message in session.receive():
                if message.session_resumption_update:
                    update = message.session_resumption_update
                    if update.resumable and update.new_handle:
                        session_handle = update.new_handle
                        print(f"Received session handle: {session_handle}")
                        # For demonstration, we break to simulate a disconnect
                        # after receiving a handle.
                        break
                if message.server_content and message.server_content.turn_complete:
                    break
    except websockets.exceptions.WebSocketException as e:
        print(f"Initial connection failed: {e}")
        return

    if not session_handle:
        print("Did not receive a session handle. Cannot demonstrate resumption.")
        return

    print(f"\nSimulating disconnect and reconnecting with handle {session_handle}...")

    try:
        async with client.aio.live.connect(
            model=MODEL,
            config=types.LiveConnectConfig(
                response_modalities=["audio"],
                session_resumption_config=types.SessionResumptionConfig(handle=session_handle),
            ),
        ) as session:
            print("Successfully resumed session.")
            await session.send_content(
                content=types.Content(role="user", parts=[types.Part(text="I am back!")])
            )
            async for message in session.receive():
                if message.session_resumption_update:
                    update = message.session_resumption_update
                    if update.resumable and update.new_handle:
                        session_handle = update.new_handle
                        print(f"Received updated session handle: {session_handle}")
                if message.server_content:
                    print(f"Received server content: {message.server_content}")
                    if message.server_content.turn_complete:
                        break
            print("Resumed session finished.")
    except websockets.exceptions.WebSocketException as e:
        print(f"Failed to resume session: {e}")

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

Habilitar la reanudación de sesiones sin interrupciones con el modo Transparencia

Si habilitas la reanudación de la sesión, también puedes habilitar el modo transparente para que el proceso de reanudación sea más fluido para el usuario. Cuando el modo transparente está habilitado, se devuelve explícitamente el índice del mensaje del cliente que corresponde a la instantánea de contexto. Esto ayuda a identificar qué mensaje del cliente debes volver a enviar cuando reanudes la sesión desde el identificador de reanudación.

Para habilitar el modo Ambiente, sigue estos pasos:

Python

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

Actualizar las instrucciones del sistema durante una sesión

La API Gemini Live te permite actualizar las instrucciones del sistema durante una sesión activa. Úsala para adaptar las respuestas del modelo, como cambiar el idioma o modificar el tono.

Para actualizar las instrucciones del sistema durante la sesión, puedes enviar contenido de texto con el rol system. La instrucción del sistema actualizada seguirá en vigor durante el resto de la sesión.

Python

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

Configurar la ventana de contexto de la sesión

La ventana de contexto de la API Gemini Live se usa para almacenar datos transmitidos en tiempo real (25 tokens por segundo [TPS] en el caso del audio y 258 TPS en el del vídeo) y otro contenido, incluidas las entradas de texto y las salidas del modelo. Una sesión tiene un límite de ventana de contexto de:

• 128.000 tokens para modelos de audio nativos
• 32.000 tokens para otros modelos de la API Live

En las sesiones de larga duración, a medida que avanza la conversación, se acumula el historial de tokens de audio y texto. Si este historial supera el límite del modelo, es posible que el modelo tenga alucinaciones, se ralentice o que la sesión se cierre de forma forzosa. Para habilitar sesiones más largas, puedes habilitar la compresión de la ventana de contexto configurando el campo contextWindowCompression como parte de la configuración de la sesión.

La compresión de la ventana de contexto usa una ventana deslizante del lado del servidor para truncar las conversaciones más antiguas cuando está habilitada. Cuando los tokens acumulados superan una longitud máxima definida (establecida mediante el control deslizante Tamaño máximo del contenido en Vertex AI Studio o trigger_tokens en la API), el servidor recorta automáticamente las conversaciones más antiguas o las resume para mantener el contexto dentro del límite. En ContextWindowCompressionConfig, puede configurar un mecanismo de ventana deslizante y el número de tokens definidos en el parámetro target_tokens que activa la compresión.

De esta forma, la duración de las sesiones puede ser infinita desde el punto de vista del usuario, ya que la "memoria" se gestiona constantemente. Sin compresión, las sesiones solo de audio pueden limitarse a unos 15 minutos antes de alcanzar los límites estrictos.

Las longitudes mínimas y máximas de la longitud del contexto y del tamaño de destino son las siguientes:

Ajuste (marca de API)	Valor mínimo	Valor máximo
Longitud máxima del contexto (trigger_tokens)	5000	128.000
Tamaño del contexto objetivo (target_tokens)	0	128.000

Para definir la ventana de contexto, sigue estos pasos:

Consola

1. Abre Vertex AI Studio > Stream realtime (Vertex AI Studio > Transmitir en tiempo real).
2. Haz clic para abrir el menú Avanzado.
3. En la sección Contexto de la sesión, use el control deslizante Tamaño máximo del contexto para definir un valor entre 5000 y 128.000.
4. (Opcional) En la misma sección, use el control deslizante Tamaño del contexto objetivo para definir el tamaño objetivo en un valor entre 0 y 128.000.

Python

Define los campos context_window_compression.trigger_tokens y context_window_compression.sliding_window.target_tokens en el mensaje de configuración:

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

Habilitar la transcripción de audio de la sesión

Puedes habilitar las transcripciones del audio de entrada y de salida.

Para recibir transcripciones, debes actualizar la configuración de la sesión. Debe añadir los objetos input_audio_transcription y output_audio_transcription, y asegurarse de que text se incluye en response_modalities.

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

Procesar la respuesta

En el siguiente código de ejemplo se muestra cómo conectarse mediante la sesión configurada y extraer las partes de texto (transcripciones) junto con los datos de audio.

# 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.")

Siguientes pasos

• Enviar flujos de audio y vídeo
• Prácticas recomendadas para usar la API Gemini Live
• Diseñar peticiones multimodales
• Introducción a las llamadas de función