Guía para desarrolladores de Gemini 3.8 Live

Gemini 3.8 Live es un modelo conversacional en tiempo real diseñado para interacciones bidireccionales de voz y video de baja latencia, y para la síntesis de avatares en vivo presenciales. Diseñado para flujos de trabajo conversacionales continuos, 3.8 Live proporciona diálogo basado en emociones detectadas habilitado de forma predeterminada, filtrado de audio proactivo, herramientas de bloqueo de cancelación automática y cambio dinámico de varios idiomas.

En este documento, se incluyen los siguientes temas:

• Cómo se adapta 3.8 Live a la familia de modelos de Gemini
• Funciones clave de 3.8 Live
• Integración con el SDK de IA generativa de Google
• Reglas y convenciones de API requeridas
• Migración desde modelos anteriores de la API de Gemini Live

Rol en la familia de Gemini

3.8 Live está diseñado para interacciones de transmisión en tiempo real. Funciona en WebSockets bidireccionales, procesa voz, feeds de cámaras en vivo y transmisiones de pantalla con una latencia inferior a un segundo, mientras genera audio de 24 kHz y avatares de video de 24 FPS sincronizados.

Especificaciones y comparaciones de modelos

En la siguiente tabla, se comparan las especificaciones entre 3.8 Live y los modelos anteriores de la API de Gemini Live:

Cuándo usar Gemini 3.8 Live

Usa 3.8 Live en las siguientes situaciones:

• Necesitas baja latencia conversacional, turnos naturales y recuperación rápida cuando el usuario interrumpe (interrupción).
• Tu app llama a herramientas externas y necesita una ejecución sin bloqueo para que la salida de audio continúe mientras los sistemas de backend procesan las solicitudes.
• Quieres renderizar avatares digitales que hablan con animación facial sincronizada y lip-sync a 24 FPS sin canalizaciones de renderización externas.
• Tus usuarios conversan en varios idiomas, lo que requiere la detección de idiomas en medio de la transmisión y el cambio entre los idiomas admitidos.
• Necesitas un sesgo de vocabulario específico del dominio para la terminología técnica, los SKU o los nombres de marca.

Para obtener especificaciones completas y límites de cuota, consulta la página del modelo 3.8 Live.

Funciones clave de Gemini 3.8 Live

3.8 Live presenta las siguientes funciones:

• Síntesis de video de avatares en vivo de 24 FPS: 3.8 Live genera transmisiones de video MP4 sincronizadas de 24 FPS (response_modalities=["VIDEO"]) directamente desde el resultado del modelo. Las expresiones faciales y los movimientos de los labios generados se alinean con el discurso sintetizado en tiempo real.

  Puedes usar avatares de stock precompilados o proporcionar imágenes de referencia personalizadas para crear conserjes digitales, agentes del servicio de atención al cliente, tutores virtuales o personajes interactivos. Para obtener detalles de configuración, consulta Cómo configurar avatares en vivo.

• Diálogo basado en emociones detectadas y audio proactivo habilitados de forma predeterminada:

  • Diálogo basado en emociones detectadas: Habilitado de forma predeterminada en 3.8 Live. El modelo procesa la prosodia acústica, las señales vocales, las pausas y la inflexión del discurso en la entrada de audio del usuario para ajustar el tono vocal y el ritmo conversacional.
  • Audio proactivo: Habilitado de forma predeterminada en 3.8 Live. El modelo filtra el ruido ambiental y el discurso de fondo, y genera respuestas de audio solo cuando el usuario se dirige a él.

• Llamada a función de bloqueo asíncrona y de cancelación automática: 3.8 Live proporciona comportamientos de llamada a herramientas diseñados para el discurso en tiempo real:

  • Ejecución asíncrona sin bloqueo: Cuando el modelo genera una llamada a herramienta, la sesión de audio permanece activa para que el agente pueda transmitir confirmaciones conversacionales ("Permítame mostrar los detalles de su cuenta...") y controlar la entrada de seguimiento mientras la app cliente llama a las APIs de backend.
  • Llamadas de bloqueo de cancelación automática (behavior="BLOCKING"): Cuando una declaración de función establece behavior="BLOCKING", la generación se detiene hasta que llega la respuesta de la herramienta. Si llega una nueva entrada del usuario mientras se ejecuta la llamada de bloqueo, el servidor de la API de Gemini Live cancela la llamada pendiente.
  • Manejo de interrupciones cortés: En los modelos anteriores, devolver una respuesta de herramienta con scheduling="INTERRUPT" mientras el usuario hablaba superponía el audio del usuario. En 3.8 Live, el servidor disminuye la programación a WHEN_IDLE cuando el discurso del usuario está activo y reproduce la respuesta después de que el usuario termina de hablar.

• Cambio dinámico de varios idiomas y vocabulario personalizado:

  • Compatibilidad con varios idiomas: Detecta y cambia entre los idiomas admitidos en medio de la sesión sin reiniciar ni volver a configurar la conexión.
  • Sesgo de vocabulario personalizado: Acepta palabras clave específicas del dominio, nombres propios, términos médicos y códigos de productos en AudioTranscriptionConfig (a través de input_audio_transcription) con custom_vocabulary para mejorar la precisión de la transcripción.

• Anclaje visual multimodal con media_resolution control: Acepta transmisiones de video en tiempo real (fotogramas JPEG de 1 FPS, resolución recomendada 768x768) y te permite configurar media_resolution (MEDIA_RESOLUTION_LOW, MEDIA_RESOLUTION_MEDIUM, MEDIA_RESOLUTION_HIGH) para equilibrar el uso de tokens por fotograma y el detalle visual.

Guía de inicio rápido

Antes de comenzar, autentícate Cloud de Confiance by S3NS con las credenciales predeterminadas de la aplicación (ADC).

En el siguiente muestra de código, reemplaza PROJECT_ID con el ID de tu Cloud de Confiance proyecto.

Instala el SDK

Instala o actualiza el SDK de IA generativa de Google y las dependencias de audio:

pip install --upgrade google-genai websockets numpy

Inicia una sesión bidireccional con llamadas a herramientas asíncronas

En el siguiente ejemplo, se establece una sesión en tiempo real con gemini-3.8-live, se configura el sesgo de vocabulario personalizado y se ejecutan llamadas a función asíncronas sin bloqueo:

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

PROJECT_ID = "PROJECT_ID"
LOCATION = "us-central1"
MODEL_ID = "gemini-3.8-live"

# Initialize the Gen AI client for enterprise.
client = genai.Client(enterprise=True, project=PROJECT_ID, location=LOCATION)

# Define a tool for asynchronous execution.
order_lookup_tool = types.FunctionDeclaration(
    name="lookup_order_status",
    description="Fetches real-time shipping status for a customer order ID.",
    parameters=types.Schema(
        type="OBJECT",
        properties={
            "order_id": types.Schema(
                type="STRING",
                description="The order ID, for example, ORD-8472",
            ),
        },
        required=["order_id"],
    ),
)

# Configure the live connection.
config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    system_instruction=types.Content(
        parts=[
            types.Part.from_text(
                text=(
                    "You are an enterprise concierge. When you call a tool, "
                    "briefly acknowledge the request and tell the user what you're doing. "
                    "If a tool returns no results, inform the user before trying again. "
                    "Never issue more than two consecutive tool calls without speaking."
                )
            )
        ]
    ),
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Aoede")
        ),
    ),
    input_audio_transcription=types.AudioTranscriptionConfig(
        custom_vocabulary=["ORD-8472", "Gemini Live", "Express Shipping"]
    ),
    output_audio_transcription=types.AudioTranscriptionConfig(),
    tools=[types.Tool(function_declarations=[order_lookup_tool])],
)

async def handle_tool_call(session, function_call):
    """Executes backend calls asynchronously without blocking incoming audio."""
    order_id = function_call.args.get("order_id", "")
    await asyncio.sleep(2.0)  # Simulate backend API latency.

    if not order_id.startswith("ORD-"):
        result = {
            "status": "invalid_argument",
            "retryable": False,
            "message": f"Order ID '{order_id}' is invalid. Ask the user to verify.",
        }
    else:
        result = {
            "status": "ok",
            "retryable": False,
            "order_id": order_id,
            "shipping_status": "Out for delivery by 4:00 PM",
        }

    # Send tool response matching the call ID.
    await session.send_tool_response(
        function_responses=[
            types.FunctionResponse(
                id=function_call.id,
                name=function_call.name,
                response=result,
            )
        ]
    )

async def main():
    async with client.aio.live.connect(model=MODEL_ID, config=config) as session:
        print(f"Connected to {MODEL_ID}")

        # Send initial text or stream 16 kHz PCM audio chunks.
        await session.send_realtime_input(
            text="Hi! Can you check the status of order ORD-8472?"
        )

        async for message in session.receive():
            # Handle asynchronous tool calls.
            if message.tool_call:
                for call in message.tool_call.function_calls:
                    asyncio.create_task(handle_tool_call(session, call))

            # Process audio output chunks and transcriptions.
            if message.server_content:
                if (
                    message.server_content.output_transcription
                    and message.server_content.output_transcription.text
                ):
                    print(
                        f"Agent: {message.server_content.output_transcription.text}",
                        end="",
                        flush=True,
                    )

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

Reglas y convenciones de API requeridas

Cuando compiles con 3.8 Live, sigue estas convenciones de API:

• Respuestas informativas de la función: No devuelvas un diccionario vacío ({}) ni None desde un controlador de herramientas. Cuando una herramienta devuelve un error o una carga útil vacía, 3.8 Live puede generar llamadas a función repetidas con argumentos modificados, a menos que la respuesta incluya campos de estado. Devuelve campos estructurados en cada respuesta de la herramienta:
  • status: Una cadena de estado legible por máquina, como "ok", "no_results", o "invalid_argument".
  • retryable: Se establece en false cuando repetir la llamada devuelve el mismo resultado.
  • message o guidance: Texto que especifica el estado que se informará al usuario.
• Límites de reintento de herramientas a nivel de instrucción: Incluye un límite de reintento en tu system_instruction. Por ejemplo: "Si una llamada a herramienta no devuelve resultados, informa al usuario en lugar de buscar repetidamente con variaciones de parámetros. Nunca ejecutes más de dos llamadas a herramientas consecutivas sin hablar con el usuario."
• Coincidencia estricta FunctionResponse:
  • Cada turno de FunctionResponse debe proporcionar el id exacto del FunctionCall anterior.
  • Pasa los objetos de respuesta directamente en FunctionResponse.response.
• Formatos de audio de transmisión:
  • Audio de entrada: PCM mono de 16 kHz, 16 bits, little-endian (audio/pcm;rate=16000), transmitido en fragmentos de 20 ms a 100 ms.
  • Audio de salida: PCM mono de 24 kHz.
• Parámetros heredados quitados: No pases enable_affective_dialog o proactivity en tu configuración; estas funciones están habilitadas de forma predeterminada en 3.8 Live.
• Historial de conversaciones de inicialización: Si inicializas el historial de varios turnos con send_client_content, espera hasta que la app cliente reciba el setup_complete del servidor y configura HistoryConfig(initial_history_in_client_content=True).

Migra a Gemini 3.8 Live

Para obtener más información sobre la migración de gemini-live-2.5-flash-native-audio a gemini-3.8-live, consulta Migra del audio nativo de la API de Gemini 2.5 Flash Live a Gemini 3.8 Live.

Lista de tareas para desarrolladores

Verifica los siguientes elementos antes de implementar tu app:

Recursos adicionales

Para obtener más información, consulta los siguientes recursos:

• Página del modelo Gemini 3.8 Live
• Cómo configurar avatares en vivo
• Prácticas recomendadas con la API de Gemini Live
• Migra del audio nativo de la API de Gemini 2.5 Flash Live a Gemini 3.8 Live
• Instructivo de Python de la API de Gemini Live
• Introducción al cuaderno de avatares en vivo
• Habilidad de servicio de la API de Gemini Live