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.

Funciones

La API de Multimodal Live incluye las siguientes funciones clave:

• Multimodalidad: El modelo puede ver, escuchar y hablar.
• Interacción en tiempo real de baja latencia: Proporciona respuestas rápidas.
• Memoria de la sesión: El modelo retiene la memoria de todas las interacciones dentro de una sola sesión y recuerda la información que se escuchó o vio anteriormente.
• Compatibilidad con llamadas a funciones, ejecución de código y Búsqueda como herramienta: Permite la integración con servicios y fuentes de datos externos.
• Detección automática de actividad de voz (VAD): El modelo puede reconocer con precisión cuándo el usuario comienza a hablar y cuándo deja de hacerlo. Esto permite interacciones conversacionales naturales y permite a los usuarios interrumpir el modelo en cualquier momento.

Puedes probar la API de Multimodal Live en Google AI Studio.

Comenzar

La API de Multimodal Live es una API con estado que usa WebSockets.

En esta sección, se muestra un ejemplo de cómo usar la API de Multimodal Live para la generación de texto a texto con Python 3.9 o versiones posteriores.

Instala la biblioteca de la API de Gemini

Para instalar el paquete google-genai, usa el siguiente comando pip:

!pip3 install google-genai

Importa las dependencias

Para importar dependencias, sigue estos pasos:

from google import genai

Cómo enviar y recibir un mensaje de texto

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model_id = "gemini-2.0-flash-exp"
config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model_id, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send(message, end_of_turn=True)

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

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

Guía de integración

En esta sección, se describe cómo funciona la integración con la API de Multimodal Live.

Sesiones

Una sesión representa una sola conexión WebSocket entre el cliente y el servidor de 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 respuestas de audio, texto o llamadas a función del servidor de Gemini

La configuración de la sesión se envía en el primer mensaje después de la conexión. Una configuración de sesión incluye el modelo, los parámetros de generación, las instrucciones del sistema y las herramientas.

Consulta la siguiente configuración de ejemplo:

{​​
  "model": string,
  "generation_config": {​
    "candidate_count": integer,
    "max_output_tokens": integer,
    "temperature": number,
    "top_p": number,
    "top_k": integer,
    "presence_penalty": number,
    "frequency_penalty": number,
    "response_modalities": string,
    "speech_config":object
  },

  "system_instruction": "",
  "tools":[]
}

Para obtener más información, consulta BidiGenerateContentSetup.

Cómo enviar mensajes

Los mensajes son cadenas con formato JSON que se intercambian a través de la conexión WebSocket.

Para enviar un mensaje, el cliente debe enviar un mensaje de cliente compatible en una cadena con formato JSON con una de las conexiones WebSocket abiertas.

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:

ws.addEventListener("message", async (evt) => {
  if (evt.data instanceof Blob) {
    // Process the received data (audio, video, etc.)
  } else {
    // Process JSON response
  }
});

Mensajes del servidor compatibles

Consulta los mensajes del servidor admitidos en la siguiente tabla:

Actualizaciones de contenido incrementales

Usa actualizaciones incrementales para enviar entradas de texto, establecer o restablecer el contexto de la sesión. Para contextos cortos, puedes enviar interacciones paso a paso para representar la secuencia exacta de eventos. Para contextos más largos, se recomienda proporcionar un solo resumen del mensaje para liberar la ventana de contexto para las interacciones de seguimiento.

Consulta el siguiente ejemplo de mensaje de contexto:

{
  "client_content": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turn_complete": true
  }
}

Ten en cuenta que, si bien las partes de contenido pueden ser de un tipo functionResponse, no se debe usar BidiGenerateContentClientContent para proporcionar una respuesta a las llamadas a función que emite el modelo. En su lugar, se debe usar BidiGenerateContentToolResponse. BidiGenerateContentClientContent solo se debe usar para establecer el contexto anterior o proporcionar entradas de texto a la conversación.

Transmisión de audio y video

Llamada a función

Todas las funciones deben declararse al comienzo de la sesión. Para ello, envía definiciones de herramientas como parte del mensaje BidiGenerateContentSetup.

Consulta el instructivo sobre llamadas a funciones para obtener más información.

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.

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

Instrucciones del sistema

Puedes proporcionar instrucciones del sistema para controlar mejor el resultado del modelo y especificar el tono y la opinión de las respuestas de audio.

Las instrucciones del sistema se agregan a la instrucción antes de que comience la interacción y permanecen vigentes durante toda la sesión.

Las instrucciones del sistema solo se pueden establecer al comienzo de una sesión, inmediatamente después de la conexión inicial. Para proporcionar más entradas al modelo durante la sesión, usa actualizaciones de contenido incrementales.

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.

Voces

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

Para especificar una voz, establece voice_name dentro del objeto speech_config, como parte de la configuración de la sesión.

Consulta la siguiente representación JSON de un objeto speech_config:

{
  "voice_config": {
    "prebuilt_voice_config ": {
      "voice_name": <var>VOICE_NAME</var>
    }
  }
}

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 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.

En el caso de las aplicaciones web y para dispositivos móviles, te recomendamos que uses la integración de nuestros socios de Daily.

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 de audio y 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

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.