Multimodal Live API

La API de Multimodal Live habilita interacciones de voz y video bidireccionales de baja latencia con Gemini. Con la API de Multimodal 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 Multimodal Live en Google AI Studio.

Usa la API de Multimodal Live

En esta sección, se describe cómo usar la API de Multimodal 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 a continuación.

Cómo enviar y recibir mensajes de texto

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-exp"

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(input=message, end_of_turn=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", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-exp"

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(input=message, end_of_turn=True)

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

            # Comment this out 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 Multimodal 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:

from google.genai import types

turns = [
    types.Content(parts=[types.Part(text="What is the capital of France?")], role="user"),
    types.Content(parts=[types.Part(text="Paris")], role="model")
]
await session.send(input=types.LiveClientContent(turns=turns))

turns = [types.Content(parts=[types.Part(text="What is the capital of Germany?")], role="user")]
await session.send(input=types.LiveClientContent(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 Multimodal Live admite las siguientes voces: Aoede, Charon, Fenrir, Kore y Puck.

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"
    }
  }
}

Usa llamadas a función

Puedes definir herramientas con la API de Multimodal 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(input="Turn the lights down to a romantic level", end_of_turn=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 de forma negativa 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 not None:
        # The generation was interrupted

Limitaciones

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

Autenticación de clientes

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

Historial de conversaciones

Si bien el modelo realiza un seguimiento de las interacciones durante la sesión, el historial de conversaciones no se almacena. Cuando finaliza una sesión, se borra el contexto correspondiente.

Para restablecer una sesión anterior o proporcionarle al modelo el contexto histórico de las interacciones del usuario, la aplicación debe mantener su propio registro de conversación y usar un mensaje BidiGenerateContentClientContent para enviar esta información al comienzo de una sesión nueva.

Duración máxima de la sesión

La duración de la sesión se limita a 15 minutos para el audio o a 2 minutos para el audio y el video. Cuando la duración de la sesión supera el límite, se finaliza la conexión.

El modelo también se limita por el tamaño del contexto. Enviar grandes fragmentos de contenido junto con las transmisiones de audio y video puede provocar que la sesión finalice antes.

Detección de actividad de voz (VAD)

El modelo realiza automáticamente la detección de actividad de voz (VAD) en una transmisión de entrada de audio continua. El VAD siempre está habilitado y sus parámetros no se pueden configurar.

Recuento de tokens

No se admite el recuento de tokens.

Límites de frecuencia

Se aplican los siguientes límites de frecuencia:

• 3 sesiones simultáneas por clave de API
• 4 millones de tokens por minuto

Referencia de la API de WebSockets

La API de Multimodal Live es una API con estado que usa WebSockets. En esta sección, encontrarás detalles adicionales sobre la API de WebSockets.

Sesiones

Una conexión WebSocket establece una sesión entre el cliente y el servidor Gemini. Después de que un cliente inicia una conexión nueva, la sesión puede intercambiar mensajes con el servidor para realizar las siguientes acciones:

• Enviar texto, audio o video al servidor de Gemini
• Recibir solicitudes de llamadas de audio, texto o función del servidor de Gemini

El mensaje inicial después de la conexión establece la configuración de la sesión, que incluye el modelo, los parámetros de generación, las instrucciones del sistema y las herramientas.

Consulta la siguiente configuración de ejemplo. Ten en cuenta que la mayúscula o minúscula de los nombres en los SDKs puede variar. Puedes buscar las opciones de configuración del SDK de Python aquí.

{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object
  },
  "systemInstruction": string,
  "tools": [object]
}

Cómo enviar mensajes

Para intercambiar mensajes a través de la conexión WebSocket, el cliente debe enviar un objeto JSON a través de una conexión WebSocket abierta. El objeto JSON debe tener exactamente uno de los campos del siguiente conjunto de objetos:

{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

Mensajes de cliente compatibles

Consulta los mensajes de cliente admitidos en la siguiente tabla:

Recibir mensajes

Para recibir mensajes de Gemini, escucha el evento "message" de WebSocket y, luego, analiza el resultado según la definición de los mensajes del servidor compatibles.

Consulta lo siguiente:

async with client.aio.live.connect(model='...', config=config) as session:
    await session.send(input='Hello world!', end_of_turn=True)
    async for message in session.receive():
        print(message)

Los mensajes del servidor tendrán exactamente uno de los campos del siguiente conjunto de objetos:

{
  "setupComplete": BidiGenerateContentSetupComplete,
  "serverContent": BidiGenerateContentServerContent,
  "toolCall": BidiGenerateContentToolCall,
  "toolCallCancellation": BidiGenerateContentToolCallCancellation
}

Mensajes del servidor compatibles

Consulta los mensajes del servidor admitidos en la siguiente tabla:

Mensajes y eventos

Más información sobre los tipos comunes

Para obtener más información sobre los tipos de recursos de API de uso general Blob, Content, FunctionCall, FunctionResponse, GenerationConfig, GroundingMetadata y Tool, consulta Cómo generar contenido.

Integraciones de terceros

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

• A diario
• Livekit