Guía de capacidades de la API en vivo

Esta es una guía completa que abarca las capacidades y configuraciones disponibles con la API de Live. Consulta la página Comienza a usar la API de Live para obtener una descripción general y código de muestra para casos de uso comunes.

Antes de comenzar

  • Familiarízate con los conceptos básicos: Si aún no lo hiciste, primero lee la página Comienza a usar la API de Live . En esta guía, se presentan los principios fundamentales de la API de Live, cómo funciona y los diferentes enfoques de implementación.
  • Prueba la API de Live en AI Studio: Es posible que te resulte útil probar la API de Live en Google AI Studio antes de comenzar a compilar. Para usar la API de Live en Google AI Studio, selecciona Stream.

Comparación de modelos

En la siguiente tabla, se resumen las diferencias clave entre los modelos de Gemini 3.1 Flash Live Preview y Gemini 2.5 Flash Live Preview:

Función Versión preliminar de Gemini 3.1 Flash Live Versión preliminar de Gemini 2.5 Flash Live
Pensamiento Usa thinkingLevel para controlar la profundidad del pensamiento con parámetros de configuración como minimal, low, medium y high. El valor predeterminado es minimal para optimizar la latencia más baja. Consulta Niveles y presupuestos de pensamiento. Usa thinkingBudget para establecer la cantidad de tokens de pensamiento. El pensamiento dinámico está habilitado de forma predeterminada. Establece thinkingBudget en 0 para inhabilitarlo. Consulta Niveles y presupuestos de pensamiento.
Recepción de la respuesta Un solo evento del servidor puede contener varias partes de contenido de forma simultánea (por ejemplo, inlineData y transcripción). Asegúrate de que tu código procese todas las partes de cada evento para no perder contenido. Cada evento del servidor contiene solo una parte del contenido. Las partes se entregan en eventos separados.
Contenido del cliente send_client_content solo se admite para propagar el historial de contexto inicial (requiere configurar initial_history_in_client_content en la configuración de la sesión). Para enviar actualizaciones de texto durante la conversación, usa send_realtime_input en su lugar. send_client_content se admite durante toda la conversación para enviar actualizaciones de contenido incrementales y establecer contexto.
Cobertura de giros La configuración predeterminada es TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO. El turno del modelo incluye la actividad de audio detectada y todos los fotogramas de video. La configuración predeterminada es TURN_INCLUDES_ONLY_ACTIVITY. El turno del modelo solo incluye la actividad detectada.
VAD personalizado (activity_start/activity_end) Compatible. Inhabilita la VAD automática y envía mensajes activityStart y activityEnd de forma manual para controlar los límites de los turnos. Compatible. Inhabilita la VAD automática y envía mensajes activityStart y activityEnd de forma manual para controlar los límites de los turnos.
Configuración automática del VAD Compatible. Configura parámetros como start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms y silence_duration_ms. Compatible. Configura parámetros como start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms y silence_duration_ms.
Llamada a función asíncrona (behavior: NON_BLOCKING) No admitido. La llamada a función solo es secuencial. El modelo no comenzará a responder hasta que envíes la respuesta de la herramienta. Compatible. Establece behavior en NON_BLOCKING en una declaración de función para permitir que el modelo siga interactuando mientras se ejecuta la función. Controla cómo el modelo maneja las respuestas con el parámetro scheduling (INTERRUPT, WHEN_IDLE o SILENT).
Audio proactivo No compatible Compatible. Cuando está habilitado, el modelo puede decidir de forma proactiva no responder si el contenido de entrada no es pertinente. Establece proactive_audio en true en la configuración de proactivity (requiere v1beta).
Diálogo basado en emociones detectadas No compatible Compatible. El modelo adapta el estilo de su respuesta para que coincida con la expresión y el tono de la entrada. Establece enable_affective_dialog en true en la configuración de la sesión (requiere v1beta).

Para migrar de Gemini 2.5 Flash Live a Gemini 3.1 Flash Live, consulta la guía de migración.

Cómo establecer una conexión

En el siguiente ejemplo, se muestra cómo crear una conexión con una clave de API:

Python

import asyncio
from google import genai

client = genai.Client()

model = "gemini-3.1-flash-live-preview"
config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        print("Session started")
        # Send content...

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

JavaScript

import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({});
const model = 'gemini-3.1-flash-live-preview';
const config = { responseModalities: [Modality.AUDIO] };

async function main() {

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        console.debug(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  console.debug("Session started");
  // Send content...

  session.close();
}

main();

Modalidades de interacción

En las siguientes secciones, se proporcionan ejemplos y contexto de respaldo para las diferentes modalidades de entrada y salida disponibles en la API de Live.

Cómo enviar audio

El audio debe enviarse como datos PCM sin procesar (audio PCM sin procesar de 16 bits, 16 kHz, little-endian).

Python

# Assuming 'chunk' is your raw PCM audio bytes
await session.send_realtime_input(
    audio=types.Blob(
        data=chunk,
        mime_type="audio/pcm;rate=16000"
    )
)

JavaScript

// Assuming 'chunk' is a Buffer of raw PCM audio
session.sendRealtimeInput({
  audio: {
    data: chunk.toString('base64'),
    mimeType: 'audio/pcm;rate=16000'
  }
});

Formatos de audio

Los datos de audio en la API de Live siempre son PCM sin procesar, little-endian y de 16 bits. La salida de audio siempre usa una frecuencia de muestreo de 24 kHz. El audio de entrada es de 16 kHz de forma nativa, pero la API de Live volverá a muestrear si es necesario, por lo que se puede enviar cualquier frecuencia de muestreo. Para transmitir la tasa de muestreo del audio de entrada, establece el tipo de MIME de cada Blob que contenga audio en un valor como audio/pcm;rate=16000.

Cómo recibir audio

Las respuestas de audio del modelo se reciben como fragmentos de datos.

Python

async for response in session.receive():
    if response.server_content and response.server_content.model_turn:
        for part in response.server_content.model_turn.parts:
            if part.inline_data:
                audio_data = part.inline_data.data
                # Process or play the audio data

JavaScript

// Inside the onmessage callback
const content = response.serverContent;
if (content?.modelTurn?.parts) {
  for (const part of content.modelTurn.parts) {
    if (part.inlineData) {
      const audioData = part.inlineData.data;
      // Process or play audioData (base64 encoded string)
    }
  }
}

Enviando mensaje de texto

El texto se puede enviar con send_realtime_input (Python) o sendRealtimeInput (JavaScript).

Python

await session.send_realtime_input(text="Hello, how are you?")

JavaScript

session.sendRealtimeInput({
  text: 'Hello, how are you?'
});

Enviando video

Los fotogramas de video se envían como imágenes individuales (p.ej., JPEG o PNG) a una velocidad de fotogramas específica (máximo 1 fotograma por segundo).

Python

# Assuming 'frame' is your JPEG-encoded image bytes
await session.send_realtime_input(
    video=types.Blob(
        data=frame,
        mime_type="image/jpeg"
    )
)

JavaScript

// Assuming 'frame' is a Buffer of JPEG-encoded image data
session.sendRealtimeInput({
  video: {
    data: frame.toString('base64'),
    mimeType: 'image/jpeg'
  }
});

Actualizaciones incrementales de contenido

Usa actualizaciones incrementales para enviar entradas de texto, establecer el contexto de la sesión o restablecerlo. En el caso de contextos breves, puedes enviar interacciones paso a paso para representar la secuencia exacta de eventos:

Python

turns = [
    {"role": "user", "parts": [{"text": "What is the capital of France?"}]},
    {"role": "model", "parts": [{"text": "Paris"}]},
]

await session.send_client_content(turns=turns, turn_complete=False)

turns = [{"role": "user", "parts": [{"text": "What is the capital of Germany?"}]}]

await session.send_client_content(turns=turns, turn_complete=True)

JavaScript

let inputTurns = [
  { "role": "user", "parts": [{ "text": "What is the capital of France?" }] },
  { "role": "model", "parts": [{ "text": "Paris" }] },
]

session.sendClientContent({ turns: inputTurns, turnComplete: false })

inputTurns = [{ "role": "user", "parts": [{ "text": "What is the capital of Germany?" }] }]

session.sendClientContent({ turns: inputTurns, turnComplete: true })

Para contextos más largos, se recomienda proporcionar un solo resumen del mensaje para liberar la ventana de contexto para interacciones posteriores. Consulta Reanudación de sesión para conocer otro método para cargar el contexto de la sesión.

Transcripción de audio

Además de la respuesta del modelo, también puedes recibir transcripciones de la entrada y la salida de audio.

Para habilitar la transcripción del audio de salida del modelo, envía output_audio_transcription en la configuración. El idioma de la transcripción se infiere de la respuesta del modelo.

Python

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

client = genai.Client()
model = "gemini-3.1-flash-live-preview"

config = {
    "response_modalities": ["AUDIO"],
    "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.output_transcription:
                print("Transcript:", response.server_content.output_transcription.text)

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

JavaScript

import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({});
const model = 'gemini-3.1-flash-live-preview';

const config = {
  responseModalities: [Modality.AUDIO],
  outputAudioTranscription: {}
};

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      }
    }
    return turns;
  }

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        responseQueue.push(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  const inputTurns = 'Hello how are you?';
  session.sendClientContent({ turns: inputTurns });

  const turns = await handleTurn();

  for (const turn of turns) {
    if (turn.serverContent && turn.serverContent.outputTranscription) {
      console.debug('Received output transcription: %s\n', turn.serverContent.outputTranscription.text);
    }
  }

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

main();

Para habilitar la transcripción de la entrada de audio del modelo, envía input_audio_transcription en la configuración.

Python

import asyncio
from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client()
model = "gemini-3.1-flash-live-preview"

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

async def main():
    async with client