Live API

La API de Live permite interacciones de voz y video bidireccionales de baja latencia con Gemini. Con la API de Live, puedes proporcionar a los usuarios finales la experiencia de conversaciones de voz naturales y similares a las humanas, y la capacidad de interrumpir las respuestas del modelo con comandos por voz. El modelo puede procesar entradas de texto, audio y video, y puede proporcionar salidas de texto y audio.

Puedes probar la API de Live en Google AI Studio.

Novedades

La API de Live tiene nuevas funciones y capacidades.

Nuevas funciones:

• Dos voces nuevas y 30 idiomas nuevos, con idioma de salida configurable
• Resoluciones de imagen configurables: 66/256 tokens
• Cobertura de giro configurable: Envía todas las entradas todo el tiempo o solo cuando el usuario habla.
• Configura si la entrada debe interrumpir el modelo o no
• Detección de actividad de voz configurable y nuevos eventos de cliente para la señalización de fin de turno
• Recuentos de tokens
• Un evento de cliente para indicar el final de la transmisión
• Transmisión de texto
• Reasumir la sesión configurable, con datos de la sesión almacenados en el servidor durante 24 horas
• Compatibilidad con sesiones más largas con una ventana de contexto deslizante

Eventos de cliente nuevo:

• Fin de la transmisión de audio o cierre del micrófono
• Eventos de inicio y finalización de la actividad para controlar manualmente la transición de giro

Nuevos eventos del servidor:

• Notificación que desaparece que indica que se debe reiniciar una sesión
• Generación completada

Usa la API de Live

En esta sección, se describe cómo usar la API de Live con uno de nuestros SDKs. Para obtener más información sobre la API subyacente de WebSockets, consulta la referencia de la API de WebSockets.

Para usar todas las funciones, asegúrate de instalar la versión más reciente del SDK, p.ej., pip install -U google-genai.

Cómo enviar y recibir mensajes de texto

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send_client_content(
                turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
            )

            async for response in session.receive():
                if response.text is not None:
                    print(response.text, end="")

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

Cómo recibir audio

En el siguiente ejemplo, se muestra cómo recibir datos de audio y escribirlos en un archivo .wav.

import asyncio
import wave
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        wf = wave.open("audio.wav", "wb")
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(24000)

        message = "Hello? Gemini are you there?"
        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for idx,response in async_enumerate(session.receive()):
            if response.data is not None:
                wf.writeframes(response.data)

            # Un-comment this code to print audio data info
            # if response.server_content.model_turn is not None:
            #      print(response.server_content.model_turn.parts[0].inline_data.mime_type)

        wf.close()

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

Formatos de audio

La API de Live admite los siguientes formatos de audio:

• Formato de audio de entrada: Audio PCM sin procesar de 16 bits a 16 kHz de tipo little-endian
• Formato de audio de salida: Audio PCM sin procesar de 16 bits a 24 kHz de tipo little-endian

Cómo transmitir audio y video

Instrucciones del sistema

Las instrucciones del sistema te permiten dirigir el comportamiento de un modelo según tus necesidades y casos de uso específicos. Las instrucciones del sistema se pueden establecer en la configuración de configuración y permanecerán vigentes durante toda la sesión.

from google.genai import types

config = {
    "system_instruction": types.Content(
        parts=[
            types.Part(
                text="You are a helpful assistant and answer in a friendly tone."
            )
        ]
    ),
    "response_modalities": ["TEXT"],
}

Actualizaciones de contenido incrementales

Usa actualizaciones incrementales para enviar entradas de texto, establecer el contexto de la sesión o restablecerlo. Para contextos cortos, puedes enviar interacciones paso a paso para representar la secuencia exacta de eventos:

turns = [
    {"role": "user", "parts": [{"text": "What is the capital of France?"}]},
    {"role": "model", "parts": [{"text": "Paris"}]},
]

await session.send_client_content(turns=turns, turn_complete=False)

turns = [{"role": "user", "parts": [{"text": "What is the capital of Germany?"}]}]

await session.send_client_content(turns=turns, turn_complete=True)

{
  "clientContent": {
    "turns": [
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

Para contextos más largos, se recomienda proporcionar un solo resumen del mensaje para liberar la ventana de contexto para interacciones posteriores.

Cambiar voces

La API de Live admite las siguientes voces: Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus y Zephyr.

Para especificar una voz, establece el nombre de la voz dentro del objeto speechConfig como parte de la configuración de la sesión:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
        )
    )
)

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "Kore"
    }
  }
}

Cambiar idioma

La API de Live admite varios idiomas.

Para cambiar el idioma, establece el código de idioma dentro del objeto speechConfig como parte de la configuración de la sesión:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        language_code="de-DE",
    )
)

Usa llamadas a función

Puedes definir herramientas con la API de Live. Consulta el instructivo sobre llamadas a funciones para obtener más información.

Las herramientas deben definirse como parte de la configuración de la sesión:

config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    tools=[set_light_values]
)

async with client.aio.live.connect(model=model, config=config) as session:
    await session.send_client_content(
        turns={
            "role": "user",
            "parts": [{"text": "Turn the lights down to a romantic level"}],
        },
        turn_complete=True,
    )

    async for response in session.receive():
        print(response.tool_call)

A partir de una sola instrucción, el modelo puede generar varias llamadas a funciones y el código necesario para encadenar sus resultados. Este código se ejecuta en un entorno de zona de pruebas y genera mensajes BidiGenerateContentToolCall posteriores. La ejecución se detiene hasta que los resultados de cada llamada a función están disponibles, lo que garantiza el procesamiento secuencial.

El cliente debe responder con BidiGenerateContentToolResponse.

Las entradas y salidas de audio afectan negativamente la capacidad del modelo para usar llamadas a función.

Controla las interrupciones

Los usuarios pueden interrumpir la salida del modelo en cualquier momento. Cuando la detección de actividad de voz (VAD) detecta una interrupción, se cancela y descarta la generación en curso. Solo la información que ya se envió al cliente se conserva en el historial de la sesión. Luego, el servidor envía un mensaje BidiGenerateContentServerContent para informar la interrupción.

Además, el servidor de Gemini descarta las llamadas a función pendientes y envía un mensaje BidiGenerateContentServerContent con los IDs de las llamadas canceladas.

async for response in session.receive():
    if response.server_content.interrupted is True:
        # The generation was interrupted

Configura la detección de actividad de voz (VAD)

Puedes configurar o inhabilitar la detección de actividad de voz (VAD).

Usa la VAD automática

De forma predeterminada, el modelo realiza automáticamente la VAD en un flujo de entrada de audio continuo. La VAD se puede configurar con el campo realtimeInputConfig.automaticActivityDetection de la configuración de configuración.

Cuando la transmisión de audio se pausa durante más de un segundo (por ejemplo, porque el usuario apagó el micrófono), se debe enviar un evento audioStreamEnd para borrar el audio almacenado en caché. El cliente puede reanudar el envío de datos de audio en cualquier momento.

# example audio file to try:
# URL = "https://storage.googleapis.com/generativeai-downloads/data/hello_are_you_there.pcm"
# !wget -q $URL -O sample.pcm
import asyncio
from pathlib import Path
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        audio_bytes = Path("sample.pcm").read_bytes()

        await session.send_realtime_input(
            audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
        )

        # if stream gets paused, send:
        # await session.send_realtime_input(audio_stream_end=True)

        async for response in session.receive():
            if response.text is not None:
                print(response.text)

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

Con send_realtime_input, la API responderá al audio automáticamente según el VAD. Mientras que send_client_content agrega mensajes al contexto del modelo en orden, send_realtime_input está optimizado para la capacidad de respuesta a expensas del orden determinista.

Inhabilita la VAD automática

Como alternativa, puedes inhabilitar la VAD automática configurando realtimeInputConfig.automaticActivityDetection.disabled como true en el mensaje de configuración. En esta configuración, el cliente es responsable de detectar la voz del usuario y enviar mensajes activityStart y activityEnd en los momentos adecuados. No se envía un audioStreamEnd en esta configuración. En cambio, cualquier interrupción de la transmisión se marca con un mensaje activityEnd.

config = {
    "response_modalities": ["TEXT"],
    "realtime_input_config": {"automatic_activity_detection": {"disabled": True}},
}

async with client.aio.live.connect(model=model, config=config) as session:
    # ...
    await session.send_realtime_input(activity_start=types.ActivityStart)
    await session.send_realtime_input(
        audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
    )
    await session.send_realtime_input(activity_end=types.ActivityEnd)
    # ...

Cómo obtener el recuento de tokens

Puedes encontrar la cantidad total de tokens consumidos en el campo usageMetadata del mensaje del servidor que se muestra.

async for message in session.receive():
    # The server will periodically send messages that include UsageMetadata.
    if message.usage_metadata:
        usage = message.usage_metadata
        print(
            f"Used {usage.total_token_count} tokens in total. Response token breakdown:"
        )
        for detail in usage.response_tokens_details:
            match detail:
                case types.ModalityTokenCount(modality=modality, token_count=count):
                    print(f"{modality}: {count}")

Cómo extender la duración de la sesión

La duración máxima de la sesión se puede extender a ilimitada con dos mecanismos:

• Habilita la compresión de la ventana de contexto
• Configura la reanudación de la sesión

Además, recibirás un mensaje GoAway antes de que finalice la sesión, lo que te permitirá realizar más acciones.

Habilita la compresión de la ventana de contexto

Para habilitar sesiones más largas y evitar la terminación abrupta de la conexión, puedes habilitar la compresión de la ventana de contexto configurando el campo contextWindowCompression como parte de la configuración de la sesión.

En ContextWindowCompressionConfig, puedes configurar un mecanismo de ventana deslizante y la cantidad de tokens que activa la compresión.

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    context_window_compression=(
        # Configures compression with default parameters.
        types.ContextWindowCompressionConfig(
            sliding_window=types.SlidingWindow(),
        )
    ),
)

Cómo configurar la reanudación de la sesión

Para evitar que se cierre la sesión cuando el servidor restablezca periódicamente la conexión de WebSocket, configura el campo sessionResumption en la configuración de configuración.

Si pasas esta configuración, el servidor enviará mensajes SessionResumptionUpdate, que se pueden usar para reanudar la sesión pasando el último token de reanudación como SessionResumptionConfig.handle de la conexión posterior.

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

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

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())

Recibir un mensaje antes de que se desconecte la sesión

El servidor envía un mensaje GoAway que indica que la conexión actual se finalizará pronto. Este mensaje incluye timeLeft, que indica el tiempo restante y te permite realizar más acciones antes de que la conexión se cierre como ABORTED.

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)

Recibir un mensaje cuando se complete la generación

El servidor envía un mensaje generationComplete que indica que el modelo terminó de generar la respuesta.

async for response in session.receive():
    if response.server_content.generation_complete is True:
        # The generation is complete

Cambia la resolución del contenido multimedia

Para especificar la resolución de contenido multimedia de entrada, configura el campo mediaResolution como parte de la configuración de la sesión:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)

Limitaciones

Ten en cuenta las siguientes limitaciones de la API de Live y Gemini 2.0 cuando planifiques tu proyecto.

Modalidades de respuesta

Solo puedes establecer una modalidad de respuesta (TEXT o AUDIO) por sesión en la configuración de la sesión. Si intentas configurar ambos, se mostrará un mensaje de error de configuración. Esto significa que puedes configurar el modelo para que responda con texto o audio, pero no con ambos en la misma sesión.

Autenticación de clientes

La API de Live solo proporciona autenticación de servidor a servidor y no se recomienda para el uso directo de clientes. La entrada del cliente debe enrutarse a través de un servidor de aplicaciones intermedio para una autenticación segura con la API de Live.

Duración de la sesión

Si habilitas la compresión de la sesión, puedes extender su duración hasta un tiempo ilimitado. Sin compresión, las sesiones de solo audio se limitan a 15 minutos, y las sesiones de audio y video se limitan a 2 minutos. Si superas estos límites sin compresión, se finalizará la conexión.

Además, puedes configurar la reanudación de la sesión para permitir que el cliente reanude una sesión que se cerró.

Ventana de contexto

Una sesión tiene un límite de ventana de contexto de 32,000 tokens.

Idiomas admitidos

La API de Live admite los siguientes idiomas:

Integraciones de terceros

Para implementaciones de aplicaciones web y para dispositivos móviles, puedes explorar las siguientes opciones:

• A diario
• Livekit