API Live

La API Live permite interacciones bidireccionales de voz y vídeo con Gemini con baja latencia. Usa la API Live para ofrecer a los usuarios finales conversaciones de voz naturales y similares a las humanas, incluida la posibilidad de interrumpir las respuestas del modelo con comandos de voz.

En este documento se explican los conceptos básicos para usar la API Live, incluidas sus funciones, ejemplos para empezar y ejemplos de código de casos prácticos básicos. Si quieres saber cómo iniciar una conversación interactiva con la API Live, consulta el artículo Conversaciones interactivas con la API Live. Si quieres saber qué herramientas puede usar la API Live, consulta Herramientas integradas.

Modelos admitidos

La API Live se puede usar tanto en el SDK de IA generativa de Google como en Vertex AI Studio. Algunas funciones (como la entrada y la salida de texto) solo están disponibles con el SDK de IA generativa.

Puedes usar la API Live con los siguientes modelos:

Versión del modelo Nivel de disponibilidad
gemini-live-2.5-flash GA privada*
gemini-live-2.5-flash-preview-native-audio Vista previa pública

* Ponte en contacto con el representante del equipo de tu cuenta de Google para solicitar acceso.

Para obtener más información, incluidas las especificaciones técnicas y las limitaciones, consulta la guía de referencia de la API Live.

Ejemplos de activadores

Puedes empezar a usar la API Live con uno de los siguientes tutoriales de cuaderno, aplicaciones de demostración o guías.

Tutoriales de Notebook

Descarga estos tutoriales de cuadernos de GitHub o ábrelos en el entorno que prefieras.

Usar WebSockets con la API Live

Streaming de audio y vídeo

Aplicaciones y guías de demostración

Funciones de la API Live

Gemini 2.5 Flash con Live API también incluye audio nativo como oferta de versión preliminar pública. La función de audio nativo incluye lo siguiente:

  • Diálogo afectivo: la API Live entiende el tono de voz del usuario y responde en consecuencia. Las mismas palabras dichas de diferentes maneras pueden dar lugar a conversaciones muy distintas y más matizadas.
  • Audio proactivo y reconocimiento del contexto: Live API ignora de forma inteligente las conversaciones del entorno y otros audios irrelevantes, y sabe cuándo escuchar y cuándo permanecer en silencio.

Para obtener más información sobre el audio nativo, consulta Herramientas integradas.

Formatos de audio admitidos

La API Live admite los siguientes formatos de audio:

  • Audio de entrada: audio PCM sin procesar de 16 bits a 16 kHz, little-endian
  • Audio de salida: audio PCM sin procesar de 16 bits a 24 kHz, little-endian

Obtener respuestas de texto a partir de la entrada de audio

Puedes enviar audio y recibir respuestas de texto convirtiendo el audio a un formato PCM de 16 bits, 16 kHz y mono. En el siguiente ejemplo se lee un archivo WAV y se envía con el formato correcto:

Python

# Test file: https://storage.googleapis.com/generativeai-downloads/data/16000.wav
# Install helpers for converting files: pip install librosa soundfile

import asyncio
import io
from pathlib import Path
from google import genai
from google.genai import types
import soundfile as sf
import librosa

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
model = "gemini-live-2.5-flash"
config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:

        buffer = io.BytesIO()
        y, sr = librosa.load("sample.wav", sr=16000)
        sf.write(buffer, y, sr, format="RAW", subtype="PCM_16")
        buffer.seek(0)
        audio_bytes = buffer.read()

        # If already in correct format, you can use this:
        # audio_bytes = Path("sample.pcm").read_bytes()

        await session.send_realtime_input(
            audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
        )

        async for response in session.receive():
            if response.text is not None:
                print(response.text)

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

Obtener respuestas de voz a partir de texto

Usa este ejemplo para enviar texto y recibir respuestas de voz sintetizada:

Python

import asyncio
import numpy as np
from IPython.display import Audio, Markdown, display
from google import genai
from google.genai.types import (
  Content,
  LiveConnectConfig,
  HttpOptions,
  Modality,
  Part,
  SpeechConfig,
  VoiceConfig,
  PrebuiltVoiceConfig,
)

client = genai.Client(
  vertexai=True,
  project=GOOGLE_CLOUD_PROJECT,
  location=GOOGLE_CLOUD_LOCATION,
)

voice_name = "Aoede"

config = LiveConnectConfig(
  response_modalities=["AUDIO"],
  speech_config=SpeechConfig(
      voice_config=VoiceConfig(
          prebuilt_voice_config=PrebuiltVoiceConfig(
              voice_name=voice_name,
          )
      ),
  ),
)

async with client.aio.live.connect(
  model="gemini-live-2.5-flash",
  config=config,
) as session:
  text_input = "Hello? Gemini are you there?"
  display(Markdown(f"**Input:** {text_input}"))

  await session.send_client_content(
      turns=Content(role="user", parts=[Part(text=text_input)]))

  audio_data = []
  async for message in session.receive():
      if (
          message.server_content.model_turn
          and message.server_content.model_turn.parts
      ):
          for part in message.server_content.model_turn.parts:
              if part.inline_data:
                  audio_data.append(
                      np.frombuffer(part.inline_data.data, dtype=np.int16)
                  )

  if audio_data:
      display(Audio(np.concatenate(audio_data), rate=24000, autoplay=True))

Para ver más ejemplos de envío de texto, consulta nuestra guía de introducción.

Transcribir audio

La API Live puede transcribir el audio de entrada y de salida. Usa el siguiente ejemplo para habilitar la transcripción:

Python

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

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
model = "gemini-live-2.5-flash"

config = {
    "response_modalities": ["AUDIO"],
    "input_audio_transcription": {},
    "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.input_transcription:
                print("Input transcript:", response.server_content.input_transcription.text)
            if response.server_content.output_transcription:
                print("Output transcript:", response.server_content.output_transcription.text)

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

WebSockets

# Set model generation_config
CONFIG = {
    'response_modalities': ['AUDIO'],
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {bearer_token[0]}",
}

# Connect to the server
async with connect(SERVICE_URL, additional_headers=headers) as ws:
    # Setup the session
    await ws.send(
        json.dumps(
            {
                "setup": {
                    "model": "gemini-2.0-flash-live-preview-04-09",
                    "generation_config": CONFIG,
                    'input_audio_transcription': {},
                    'output_audio_transcription': {}
                }
            }
        )
    )

    # Receive setup response
    raw_response = await ws.recv(decode=False)
    setup_response = json.loads(raw_response.decode("ascii"))

    # Send text message
    text_input = "Hello? Gemini are you there?"
    display(Markdown(f"**Input:** {text_input}"))

    msg = {
        "client_content": {
            "turns": [{"role": "user", "parts": [{"text": text_input}]}],
            "turn_complete": True,
        }
    }

    await ws.send(json.dumps(msg))

    responses = []
    input_transcriptions = []
    output_transcriptions = []

    # Receive chucks of server response
    async for raw_response in ws:
        response = json.loads(raw_response.decode())
        server_content = response.pop("serverContent", None)
        if server_content is None:
            break

        if (input_transcription := server_content.get("inputTranscription")) is not None:
            if (text := input_transcription.get("text")) is not None:
                input_transcriptions.append(text)
        if (output_transcription := server_content.get("outputTranscription")) is not None:
            if (text := output_transcription.get("text")) is not None:
                output_transcriptions.append(text)

        model_turn = server_content.pop("modelTurn", None)
        if model_turn is not None:
            parts = model_turn.pop("parts", None)
            if parts is not None:
                for part in parts:
                    pcm_data = base64.b64decode(part["inlineData"]["data"])
                    responses.append(np.frombuffer(pcm_data, dtype=np.int16))

        # End of turn
        turn_complete = server_content.pop("turnComplete", None)
        if turn_complete:
            break

    if input_transcriptions:
        display(Markdown(f"**Input transcription >** {''.join(input_transcriptions)}"))

    if responses:
        # Play the returned audio message
        display(Audio(np.concatenate(responses), rate=24000, autoplay=True))

    if output_transcriptions:
        display(Markdown(f"**Output transcription >** {''.join(output_transcriptions)}"))

Más información

Para obtener más información sobre cómo usar la API Live, consulta los siguientes artículos: