API de Multimodal Live

Experimental

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Para probar un instructivo que te permita usar tu voz y cámara para hablar con Gemini a través de la API de Multimodal Live, consulta el instructivo de websocket-demo-app.

La API de Multimodal Live habilita interacciones bidireccionales de baja latencia que usan entradas de texto, audio y video, con salida de audio y texto. Esto facilita conversaciones de voz naturales y similares a las humanas con la capacidad de interrumpir el modelo en cualquier momento. La capacidad de comprensión de videos del modelo extiende las modalidades de comunicación, lo que te permite compartir entradas de la cámara o presentaciones en pantalla y hacer preguntas sobre ellas.

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: El modelo puede proporcionar respuestas rápidas.
• Memoria de 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: Puedes integrar el modelo con servicios y fuentes de datos externos.

La API de Multimodal Live está diseñada para la comunicación de servidor a servidor.

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

Comenzar

Para probar la API de Multimodal Live, ve a Vertex AI Studio y haz clic en Probar Multimodal Live.

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.

SDK de Gen AI para Python

Obtén información para instalar o actualizar el SDK de Google Gen AI para Python.
Para obtener más información, consulta la documentación de referencia de la API del SDK de Gen AI para Python o el repositorio de GitHub de python-genai.
Establece variables de entorno para usar el SDK de IA generativa con Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import LiveConnectConfig, HttpOptions, Modality

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
model_id = "gemini-2.0-flash-exp"

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

    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?

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

• Envía texto, audio o video al servidor de Gemini.
• Recibir solicitudes de llamadas de audio, texto o 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,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object
  },

  "systemInstruction": string,
  "tools": [object]
}

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

Envía mensajes

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

Para enviar un mensaje, 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:

Mensaje	Descripción
BidiGenerateContentSetup	Configuración de la sesión que se enviará en el primer mensaje
BidiGenerateContentClientContent	Actualización incremental del contenido de la conversación actual que se entrega desde el cliente
BidiGenerateContentRealtimeInput	Entrada de audio o video en tiempo real
BidiGenerateContentToolResponse	Respuesta a un ToolCallMessage recibido del servidor

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
  }
});

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:

Mensaje	Descripción
BidiGenerateContentSetupComplete	Un mensaje BidiGenerateContentSetup del cliente que se envía cuando se completa la configuración
BidiGenerateContentServerContent	Contenido que genera el modelo en respuesta a un mensaje del cliente
BidiGenerateContentToolCall	Solicita al cliente que ejecute las llamadas a función y que devuelva las respuestas con los IDs coincidentes.
BidiGenerateContentToolCallCancellation	Se envía cuando se cancela una llamada a función debido a que el usuario interrumpe el resultado del modelo.

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

{
  "clientContent": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": 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

Para ver un ejemplo de cómo usar la API de Multimodal Live en un formato de audio y video de transmisión continua, ejecuta el notebook de Jupyter “Comienza a usar la API de Multimodal Live” en uno de los siguientes entornos:

Abrir en Colab |Abrir en Colab Enterprise |Abrir en notebooks administrados por el usuario de Vertex AI Workbench |Ver en GitHub

Ejecución de código

Para ver un ejemplo de ejecución de código, ejecuta el notebook de Jupyter “Introducción a la generación y ejecución de código de Python con Gemini 2.0” en uno de los siguientes entornos:

Abrir en Colab |Abrir en Colab Enterprise |Abrir en notebooks administrados por el usuario de Vertex AI Workbench |Ver en GitHub

Si deseas obtener más información sobre la ejecución de código, consulta Ejecución de código.

Llamada a función

Para ver un ejemplo de llamada a función, ejecuta el notebook de Jupyter “Introducción a las llamadas a función con la API de Gemini” en uno de los siguientes entornos:

Abrir en Colab |Abrir en Colab Enterprise |Abrir en notebooks administrados por el usuario de Vertex AI Workbench |Ver en GitHub

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

Para definir funciones, usa JSON, específicamente con un subconjunto seleccionado del formato de esquema de OpenAPI. Una sola declaración de función puede incluir los siguientes parámetros:

• name (cadena): Es el identificador único de la función dentro de la llamada a la API.

• description (cadena): Una explicación completa del propósito y las capacidades de la función.

• parameters (objeto): Define los datos de entrada que requiere la función.

  • type (cadena): Especifica el tipo de datos general, como objeto.

  • properties (objeto): Muestra una lista de parámetros individuales, cada uno con lo siguiente:

    • type (cadena): Es el tipo de datos del parámetro, como cadena, número entero o booleano.
    • description (cadena): Una explicación clara del propósito del parámetro y el formato esperado.

  • required (array): Es un array de cadenas que enumera los nombres de los parámetros que son obligatorios para que funcione la función.

Para ver ejemplos de código de una declaración de función con comandos curl, consulta Introducción a las llamadas a funciones con la API de Gemini. Para ver ejemplos de cómo crear declaraciones de funciones con los SDKs de la API de Gemini, consulta el instructivo sobre llamadas a funciones.

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.

Para obtener más información, consulta Introducción a las llamadas a funciones.

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:

• Puck
• Caronte
• Kore
• Fenrir
• Aoede

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

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

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "VOICE_NAME"
    }
  }
}

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.

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.

Limitaciones adicionales

No se admite la configuración de extremos manuales.

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

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

BidiGenerateContentClientContent

Actualización incremental de la conversación actual que se entrega desde el cliente. Todo el contenido aquí se agrega sin condiciones al historial de conversaciones y se usa como parte de la instrucción para que el modelo genere contenido.

Un mensaje aquí interrumpirá cualquier generación de modelos actual.

Campos
turns[]	Content Opcional. Es el contenido que se adjunta a la conversación actual con el modelo. Para consultas de un solo turno, esta es una instancia única. Para las consultas de varios turnos, este es un campo repetido que contiene el historial de conversaciones y la solicitud más reciente.
turn_complete	bool Opcional. Si es verdadero, indica que la generación de contenido del servidor debe comenzar con la instrucción acumulada actualmente. De lo contrario, el servidor esperará mensajes adicionales antes de iniciar la generación.

BidiGenerateContentRealtimeInput

Entrada del usuario que se envía en tiempo real.

Esto es diferente de ClientContentUpdate en algunos aspectos:

• Se pueden enviar de forma continua sin interrupciones a la generación de modelos.
• Si es necesario combinar datos intercalados entre ClientContentUpdate y RealtimeUpdate, el servidor intenta realizar optimizaciones para obtener la mejor respuesta, pero no hay garantías.
• El final de la toma de turno no se especifica de forma explícita, sino que se deriva de la actividad del usuario (por ejemplo, el final de la voz).
• Incluso antes de que finalice el turno, los datos se procesan de forma incremental para optimizar un inicio rápido de la respuesta del modelo.
• Siempre se supone que es la entrada del usuario (no se puede usar para propagar el historial de conversaciones).

Campos
media_chunks[]	Blob Opcional. Datos de bytes intercalados para la entrada de contenido multimedia.

BidiGenerateContentServerContent

Actualización incremental del servidor que genera el modelo en respuesta a los mensajes del cliente.

El contenido se genera lo más rápido posible, no en tiempo real. Los clientes pueden optar por almacenar en búfer y reproducir contenido en tiempo real.

Campos
turn_complete	bool Solo salida. Si es verdadero, indica que el modelo terminó de generarse. La generación solo comenzará en respuesta a mensajes adicionales del cliente. Se puede configurar junto con content, lo que indica que content es el último en el giro.
interrupted	bool Solo salida. Si es verdadero, indica que un mensaje del cliente interrumpió la generación de modelos actual. Si el cliente reproduce el contenido en tiempo real, es un buen indicador para detener y vaciar la cola actual. Si el cliente reproduce el contenido en tiempo real, es una buena señal para detener y vaciar la cola de reproducción actual.
grounding_metadata	GroundingMetadata Solo salida. Los metadatos especifican las fuentes que se usan para fundamentar el contenido generado.
model_turn	Content Solo salida. Es el contenido que el modelo generó como parte de la conversación actual con el usuario.

BidiGenerateContentSetup

Es el mensaje que se enviará en el primer y único mensaje del cliente. Contiene la configuración que se aplicará durante la sesión de transmisión.

Los clientes deben esperar un mensaje BidiGenerateContentSetupComplete antes de enviar cualquier mensaje adicional.

Campos
model	string Obligatorio. Es el nombre completamente calificado del modelo del publicador o del extremo del modelo ajustado que se usará. Formato del modelo de publicador: projects/{project}/locations/{location}/publishers/\*/models/\*
generation_config	GenerationConfig Opcional. Configuración de generación No se admiten los siguientes campos: responseLogprobs responseMimeType logprobs responseSchema stopSequence routingConfig audioTimestamp
system_instruction	Content Opcional. Las instrucciones del sistema que proporcionó el usuario para el modelo. Nota: Solo se debe usar texto en las partes. El contenido de cada parte debe encontrarse en un párrafo separado.
tools[]	Tool Opcional. Es una lista de Tools que el modelo puede usar para generar la siguiente respuesta. Un Tool es un fragmento de código que permite que el sistema interactúe con sistemas externos para realizar una acción, o un conjunto de acciones, fuera del conocimiento y del alcance del modelo.

BidiGenerateContentSetupComplete

Este tipo no tiene campos.

Se envía en respuesta a un mensaje BidiGenerateContentSetup del cliente.

BidiGenerateContentToolCall

Solicita al cliente que ejecute el functionCalls y que devuelva las respuestas con los id coincidentes.

Campos
function_calls[]	FunctionCall Solo salida. La llamada a función que se ejecutará.

BidiGenerateContentToolCallCancellation

Notificación para el cliente de que un ToolCallMessage emitido anteriormente con los id especificados no se debería haber ejecutado y se debe cancelar. Si hubo efectos secundarios en esas llamadas a la herramienta, los clientes pueden intentar deshacerlas. Este mensaje solo ocurre en los casos en que los clientes interrumpen los turnos del servidor.

Campos
ids[]	string Solo salida. Los IDs de las llamadas a la herramienta que se cancelarán.

BidiGenerateContentToolResponse

Respuesta generada por el cliente a un ToolCall recibido del servidor. Los objetos FunctionResponse individuales se corresponden con los objetos FunctionCall respectivos mediante el campo id.

Ten en cuenta que, en las APIs de GenerateContent uniaria y de transmisión del servidor, las llamadas a función se realizan intercambiando las partes Content, mientras que, en las APIs de GenerateContent de transmisión bidireccional, las llamadas a función se realizan a través de este conjunto dedicado de mensajes.

Campos
function_responses[]	FunctionResponse Opcional. La respuesta a las llamadas a la función.

¿Qué sigue?

• Obtén más información sobre las llamadas a funciones.
• Consulta la referencia de llamadas a funciones para ver ejemplos.