API de Gemini Live

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

La API de Gemini 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 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 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.

Modelos compatibles

• Gemini 2.0 Flash

Comenzar

Para probar la API en vivo, ve a Vertex AI Studio y, luego, haz clic en Iniciar sesión.

La API en vivo es una API con estado que usa WebSockets.

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

pip install --upgrade google-genai

# 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 (
    Content,
    LiveConnectConfig,
    HttpOptions,
    Modality,
    Part,
)

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
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?

Guía de integración

En esta sección, se describe cómo funciona la integración con la API de 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:

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

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

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
  "usageMetadata": UsageMetadata
  "goAway": GoAway
  "sessionResumptionUpdate": SessionResumptionUpdate
  "inputTranscription": BidiGenerateContentTranscription
  "outputTranscription": BidiGenerateContentTranscription
}

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

Ejecución de código

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

Llamada a función

Todas las funciones deben declararse al comienzo de la sesión. Para ello, se deben enviar 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): Es 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 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 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 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 Live y Gemini 2.0 cuando planifiques tu proyecto.

Autenticación de clientes

La API en vivo 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.

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)

De forma predeterminada, el modelo realiza automáticamente la detección de actividad de voz (VAD) en una transmisión continua de entrada de audio. 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, cuando el usuario apaga el micrófono), se envía 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 desactivar 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.

Limitaciones adicionales

No se admite la configuración manual de extremos.

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

¿Qué sigue?

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