API en vivo

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

Especificaciones

La API de Live tiene las siguientes especificaciones técnicas:

  • Entradas: Texto, audio y video
  • Salidas: Texto y audio (voz sintetizada)
  • Duración predeterminada de la sesión: 10 minutos
    • La duración de la sesión se puede extender en incrementos de 10 minutos según sea necesario.
  • Ventana de contexto: 32,000 tokens
  • Selección entre 8 voces para las respuestas
  • Compatibilidad con respuestas en 31 idiomas

Usa la API de Live

En las siguientes secciones, se proporcionan ejemplos sobre cómo usar las funciones de la API de Live.

Para obtener más información, consulta la guía de referencia de la API en vivo.

Cómo enviar y recibir mensajes de texto

SDK de IA generativa para Python

    # Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
    # with appropriate values for your project.
    
    from google import genai
    from google.genai.types import (
        Content,
        LiveConnectConfig,
        Modality,
        Part,
    )
    
    client = genai.Client(
        vertexai=True,
        project=GOOGLE_CLOUD_PROJECT,
        location=GOOGLE_CLOUD_LOCATION
    )
    MODEL_ID = "gemini-2.0-flash-live-preview-04-09"
    
    async with client.aio.live.connect(
        model=MODEL_ID,
        config=LiveConnectConfig(response_modalities=[Modality.TEXT]),
    ) as session:
        text_input = "Hello? Gemini, are you there?"
        print("> ", text_input, "\n")
        await session.send_client_content(
            turns=Content(role="user", parts=[Part(text=text_input)])
        )
    
        response = []
    
        async for message in session.receive():
            if message.text:
                response.append(message.text)
    
        print("".join(response))
    # Example output:
    # >  Hello? Gemini, are you there?
    # Yes, I'm here. What would you like to talk about?

Cómo enviar texto y recibir audio

SDK de IA generativa para Python

  import asyncio
  import numpy as np
  from IPython.display import Audio, Markdown, display
  from google import genai
  from google.genai.types import (
      Content,
      LiveConnectConfig,
      HttpOptions,
      Modality,
      Part,
      SpeechConfig,
      VoiceConfig,
      PrebuiltVoiceConfig,
  )

  client = genai.Client(
      vertexai=True,
      project=GOOGLE_CLOUD_PROJECT,
      location=GOOGLE_CLOUD_LOCATION,
  )

  voice_name = "Aoede"  # @param ["Aoede", "Puck", "Charon", "Kore", "Fenrir", "Leda", "Orus", "Zephyr"]

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

  async with client.aio.live.connect(
      model=MODEL_ID,
      config=config,
  ) as session:
      text_input = "Hello? Gemini are you there?"
      display(Markdown(f"**Input:** {text_input}"))

      await session.send_client_content(
          turns=Content(role="user", parts=[Part(text=text_input)]))

      audio_data = []
      async for message in session.receive():
          if (
              message.server_content.model_turn
              and message.server_content.model_turn.parts
          ):
              for part in message.server_content.model_turn.parts:
                  if part.inline_data:
                      audio_data.append(
                          np.frombuffer(part.inline_data.data, dtype=np.int16)
                      )

      if audio_data:
          display(Audio(np.concatenate(audio_data), rate=24000, autoplay=True))

Para ver más ejemplos de cómo enviar mensajes de texto, consulta nuestra guía de introducción.

Cómo enviar audio

Para enviar audio y recibir texto, convértelo a un formato mono PCM de 16 bits y 16 kHz. En este ejemplo, se lee un archivo WAV y se envía en el formato correcto:

SDK de IA generativa para Python

# Test file: https://storage.googleapis.com/generativeai-downloads/data/16000.wav
# Install helpers for converting files: pip install librosa soundfile

import asyncio
import io
from pathlib import Path
from google import genai
from google.genai import types
import soundfile as sf
import librosa

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION
    )
model = "gemini-2.0-flash-live-preview-04-09"
config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:

        buffer = io.BytesIO()
        y, sr = librosa.load("sample.wav", sr=16000)
        sf.write(buffer, y, sr, format="RAW", subtype="PCM_16")
        buffer.seek(0)
        audio_bytes = buffer.read()

        # If already in correct format, you can use this:
        # audio_bytes = Path("sample.pcm").read_bytes()

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

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

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

Formatos de audio compatibles

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 en formato little-endian
  • Formato de audio de salida: Audio PCM sin procesar de 16 bits a 24 kHz en formato little-endian

Transcripción de audio

La API de Live puede transcribir audio de entrada y salida:

SDK de IA generativa para Python

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

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
model = "gemini-2.0-flash-live-preview-04-09"

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

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        message = "Hello? Gemini are you there?"

        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for response in session.receive():
            if response.server_content.model_turn:
                print("Model turn:", response.server_content.model_turn)
            if response.server_content.input_transcription:
                print("Input transcript:", response.server_content.input_transcription.text)
            if response.server_content.output_transcription:
                print("Output transcript:", response.server_content.output_transcription.text)


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

Cómo cambiar la configuración de idioma y voz

La API de Live usa Chirp 3 para admitir respuestas de voz sintetizadas en una variedad de voces y de idiomas en HD. Para obtener una lista completa y demostraciones de cómo suena cada voz, consulta Chirp 3: Voces en HD.

Para configurar la voz y el idioma de la respuesta, haz lo siguiente:

SDK de IA generativa para Python

config = LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=SpeechConfig(
        voice_config=VoiceConfig(
            prebuilt_voice_config=PrebuiltVoiceConfig(
                voice_name=voice_name,
            )
        ),
        language_code="en-US",
    ),
)

Console

  1. Abre Vertex AI Studio > Transmitir en tiempo real.
  2. En el expansor Salidas, selecciona una voz del menú desplegable Voz.
  3. En el mismo expansor, selecciona un idioma en el menú desplegable Idioma.
  4. Haz clic en Iniciar sesión para comenzar la sesión.

Para obtener los mejores resultados cuando le pidas al modelo que responda en un idioma que no sea inglés, incluye lo siguiente como parte de las instrucciones del sistema:

RESPOND IN LANGUAGE. YOU MUST RESPOND UNMISTAKABLY IN LANGUAGE.

Tener una conversación transmitida

Para ver un ejemplo de cómo usar la API de Live en un formato de audio de transmisión continua, ejecuta este ejemplo en una computadora local con acceso a micrófono y bocina (en lugar de usar un notebook de Colab).

SDK de IA generativa para Python

Configura una conversación con la API que te permita enviar instrucciones de texto y recibir respuestas de audio:

"""
# Installation
# on linux
sudo apt-get install portaudio19-dev

# on mac
brew install portaudio

python3 -m venv env
source env/bin/activate
pip install google-genai
"""

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

CHUNK=4200
FORMAT=pyaudio.paInt16
CHANNELS=1
RECORD_SECONDS=5
MODEL = 'gemini-2.0-flash-live-preview-04-09'
INPUT_RATE=16000
OUTPUT_RATE=24000

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
config = {
    "response_modalities": ["AUDIO"],
    "input_audio_transcription": {},  # Configure input transcription
    "output_audio_transcription": {},  # Configure output transcription
}

async def main():
    print(MODEL)
    p = pyaudio.PyAudio()
    async with client.aio.live.connect(model=MODEL, config=config) as session: 
        #exit()
        async def send():
            stream = p.open(
                format=FORMAT, channels=CHANNELS, rate=INPUT_RATE, input=True, frames_per_buffer=CHUNK)
            while True:
                frame = stream.read(CHUNK)
                await session.send(input={"data": frame, "mime_type": "audio/pcm"})
                await asyncio.sleep(10**-12)
        async def receive():
            output_stream = p.open(
                format=FORMAT, channels=CHANNELS, rate=OUTPUT_RATE, output=True, frames_per_buffer=CHUNK)
            async for message in session.receive():
                if message.server_content.input_transcription:
                  print(message.server_content.model_dump(mode="json", exclude_none=True))
                if message.server_content.output_transcription:
                  print(message.server_content.model_dump(mode="json", exclude_none=True))
                if message.server_content.model_turn:
                    for part in message.server_content.model_turn.parts:
                        if part.inline_data.data:
                            audio_data=part.inline_data.data
                            output_stream.write(audio_data)
                            await asyncio.sleep(10**-12)
        send_task = asyncio.create_task(send())
        receive_task = asyncio.create_task(receive())
        await asyncio.gather(send_task, receive_task)

asyncio.run(main())

Console

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

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

Duración de la sesión

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

Cuando usas la API, puedes extender la duración de la sesión en incrementos de 10 minutos. No hay límite para la cantidad de veces que puedes extender una sesión. Para ver un ejemplo de cómo extender la duración de la sesión, consulta Habilita e inhabilita la reanudación de la sesión. Esta función solo está disponible en la API, no en Vertex AI Studio.

Ventana de contexto

La longitud máxima del contexto de una sesión en la API de Live es de 32,768 tokens de forma predeterminada, que se asignan para almacenar datos en tiempo real que se transmiten a una velocidad de 25 tokens por segundo (TPS) para audio y 258 TPS para video, y otro contenido, incluidas entradas basadas en texto, salidas de modelos, etcétera.

Si la ventana de contexto supera la longitud máxima, se truncarán los contextos de los giros más antiguos de la ventana de contexto, de modo que el tamaño general de la ventana de contexto esté por debajo de la limitación.

La longitud de contexto predeterminada de la sesión y la longitud de contexto objetivo después de la truncación se pueden configurar con los campos context_window_compression.trigger_tokens y context_window_compression.sliding_window.target_tokens del mensaje de configuración, respectivamente.

Sesiones simultáneas

De forma predeterminada, puedes tener hasta 10 sesiones simultáneas por proyecto.

Actualiza las instrucciones del sistema durante la sesión

La API de Live te permite actualizar las instrucciones del sistema en medio de una sesión activa. Puedes usar esto para adaptar las respuestas del modelo durante la sesión, por ejemplo, cambiar el idioma en el que responde el modelo a otro idioma o modificar el tono con el que quieres que responda.

Para actualizar esto, puedes enviar contenido de texto con el rol system. La instrucción del sistema actualizada permanecerá vigente durante el resto de la sesión.

SDK de IA generativa para Python

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

Cómo cambiar la configuración de detección de actividad de voz

De forma predeterminada, el modelo realiza automáticamente la detección de actividad de voz (VAD) en una transmisión de entrada de audio continua. La VAD se puede configurar con el campo realtimeInputConfig.automaticActivityDetection del mensaje 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.

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.

Habilita y habilita la reanudación de la sesión

Esta función está inhabilitada de forma predeterminada. El usuario debe habilitarlo cada vez que llama a la API especificando el campo en la solicitud a la API, y se aplica la privacidad a nivel del proyecto para los datos almacenados en caché. Si habilitas la reanudación de la sesión, el usuario puede volver a conectarse a una sesión anterior en un plazo de 24 horas almacenando datos almacenados en caché, incluidos los datos de instrucciones de texto, video y audio, y los resultados del modelo, durante un máximo de 24 horas. Para lograr una retención de datos nula, no habilites esta función.

Para habilitar la función de reanudación de la sesión, configura el campo session_resumption del mensaje LiveConnectConfig. Si está habilitado, el servidor tomará periódicamente una instantánea de los contextos de sesión almacenados en caché actuales y los almacenará en el almacenamiento interno. Cuando se tome una instantánea correctamente, se mostrará un resumption_update con el ID de control que puedes registrar y usar más adelante para reanudar la sesión desde la instantánea.

Este es un ejemplo de cómo habilitar la función de reanudación de la sesión y recopilar la información del ID de control:

SDK de IA generativa para Python

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

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION
)
model = "gemini-2.0-flash-live-preview-04-09"

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

Si deseas lograr una reanudación de sesión sin problemas, puedes habilitar el modo transparente:

SDK de IA generativa para Python

types.LiveConnectConfig(
            response_modalities=["AUDIO"],
            session_resumption=types.SessionResumptionConfig(
                transparent=True,
    ),
)

Después de habilitar el modo transparente, se muestra de forma explícita 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 reanudas la sesión desde el control de reanudación.

Usa llamadas a función

Puedes usar las llamadas a función para crear una descripción de una función y, luego, pasar esa descripción al modelo en una solicitud. La respuesta del modelo incluye el nombre de una función que coincide con la descripción y los argumentos con los que se la llama.

Todas las funciones deben declararse al comienzo de la sesión. Para ello, se deben enviar definiciones de herramientas como parte del mensaje LiveConnectConfig.

SDK de IA generativa para Python

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

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
model = "gemini-2.0-flash-live-preview-04-09"

# Simple function definitions
turn_on_the_lights = {"name": "turn_on_the_lights"}
turn_off_the_lights = {"name": "turn_off_the_lights"}

tools = [{"function_declarations": [turn_on_the_lights, turn_off_the_lights]}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Turn on the lights please"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            elif chunk.tool_call:
                function_responses = []
                for fc in tool_call.function_calls:
                    function_response = types.FunctionResponse(
                        name=fc.name,
                        response={ "result": "ok" } # simple, hard-coded function response
                    )
                    function_responses.append(function_response)

                await session.send_tool_response(function_responses=function_responses)


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

Usa la ejecución de código

Puedes usar la ejecución de código con la API de Live para generar y ejecutar código de Python directamente.

SDK de IA generativa para Python

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


client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
model = "gemini-2.0-flash-live-preview-04-09"

tools = [{'code_execution': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Compute the largest prime palindrome under 100000."
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                      if part.executable_code is not None:
                        print(part.executable_code.code)

                      if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

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

Puedes usar la conexión a tierra con la Búsqueda de Google con la API de Live mediante google_search:

SDK de IA generativa para Python

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

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
model = "gemini-2.0-flash-live-preview-04-09"


tools = [{'google_search': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "When did the last Brazil vs. Argentina soccer match happen?"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

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

                # The model might generate and execute Python code to use Search
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                        if part.executable_code is not None:
                        print(part.executable_code.code)

                        if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

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

Audio nativo

Gemini 2.5 Flash con la API de Live cuenta con funciones de audio nativas. Además de las funciones estándar de la API de Live, el audio nativo incluye lo siguiente:

  • Calidad y adaptabilidad de la voz mejoradas: El audio nativo de la API de Live proporciona interacciones de voz más ricas y naturales con 30 voces en HD en 24 idiomas.
  • Presentamos Audio proactivo: Cuando el Audio proactivo está habilitado, el modelo solo responde cuando es relevante. El modelo genera transcripciones de texto y respuestas de audio de forma proactiva solo para las consultas dirigidas al dispositivo y no responde a las consultas que no están dirigidas al dispositivo.

  • Presentamos el diálogo afectivo: Los modelos que usan audio nativo de la API de Live pueden comprender y responder de forma adecuada a las expresiones emocionales de los usuarios para generar conversaciones más matizadas.

Cómo usar el audio proactivo

Para usar Audio proactivo, configura el campo proactivity en el mensaje de configuración y establece proactive_audio en true:

SDK de IA generativa para Python

config = LiveConnectConfig(
    response_modalities=["AUDIO"],
    proactivity=ProactivityConfig(proactive_audio=True),
)

Usa el diálogo basado en emociones detectadas

Para usar el diálogo afectivo, establece enable_affective_dialog en true en el mensaje de configuración:

SDK de IA generativa para Python

config = LiveConnectConfig(
    response_modalities=["AUDIO"],
    enable_affective_dialog=True,
)

Limitaciones

Consulta la sección de limitaciones de la API de Live de nuestra documentación de referencia para obtener la lista completa de las limitaciones actuales de la API de Live.

La versión preliminar privada de Gemini 2.5 Flash con audio nativo de la API de Live tiene un límite de 3 sesiones simultáneas.

Precios

Consulta nuestra página de precios para obtener más detalles.

Más información

Para obtener más información sobre la API de Live, como la referencia de la API de WebSocket, consulta la documentación de la API de Gemini.