Entwicklerleitfaden für Gemini 3.8 Live

Gemini 3.8 Live ist ein Echtzeit-Konversationsmodell, das für bidirektionale Sprach- und Videointeraktionen mit niedriger Latenz und die Synthese von Live-Avataren für persönliche Gespräche entwickelt wurde. 3.8 Live wurde für kontinuierliche Workflows mit durchgängiger Unterhaltung entwickelt und bietet standardmäßig aktivierte affektive Dialoge, proaktive Audiofilterung, automatisch abbrechende Blockierungstools und dynamischen mehrsprachigen Wechsel.

In diesem Dokument werden folgende Themen behandelt:

  • Wie sich 3.8 Live in die Gemini-Modellfamilie einfügt.
  • Wichtige Funktionen in 3.8 Live.
  • Integration in das Google Gen AI SDK.
  • Erforderliche API-Regeln und -Konventionen.
  • Migration von früheren Gemini Live API-Modellen.

Rolle in der Gemini-Familie

3.8 Live ist für Echtzeit-Streaming-Interaktionen konzipiert. Es funktioniert über bidirektionale WebSockets und verarbeitet Sprache, Live-Kamerafeeds und Bildschirmübertragungen mit einer Latenz von weniger als einer Sekunde, während es 24-kHz-Audio und synchronisierte Video-Avatare mit 24 fps generiert.

Modellspezifikationen und -vergleiche

In der folgenden Tabelle werden die Spezifikationen von 3.8 Live und früheren Gemini Live API-Modellen verglichen:

Attribut Gemini 3.8 Live Gemini 2.5 Flash Live API Native Audio (GA-Baseline)
Modell-ID gemini-3.8-live gemini-live-2.5-flash-native-audio
Startphase General Availability (GA) General Availability (GA)
Eingabemodalitäten Audio (16 kHz PCM), Video (1 fps JPEG), Text Audio (16 kHz PCM), Video (1 fps JPEG), Text
Ausgabemodalitäten Audio (24 kHz PCM), Video (24 fps MP4 Live-Avatar), Text Audio (24 kHz PCM), Text
Live-Avatar-Synthese Synchronisierte Videoausgabe mit 24 fps Nicht unterstützt
Empathischer Dialog Standardmäßig aktiviert Erfordert eine explizite Konfiguration
Proaktive Audioeingabe Standardmäßig aktiviert Erfordert eine explizite Konfiguration
Ausführung von Funktionsaufrufen Asynchron nicht blockierend und automatisch abbrechend blockierend (behavior="BLOCKING") Asynchron und synchron
Unterbrechungen verarbeiten Downgrade für höfliches Unterbrechen (wartet, wenn der Nutzer spricht) Sofortige Unterbrechung (kann die Audioausgabe des Nutzers überlagern)
Sprachunterstützung Dynamischer Wechsel zwischen unterstützten Sprachen während des Streams Unterstützte Sprachen
Domain-Biasing Unterstützt custom_vocabulary in AudioTranscriptionConfig Standard-Baseline-Transkription
Visuelle Token-Steuerung Konfigurierbare media_resolution (LOW, MEDIUM, HIGH) Festes Token-Budget pro Frame

Wann Gemini 3.8 Live verwendet werden sollte

Verwenden Sie 3.8 Live in den folgenden Szenarien:

  • Sie benötigen eine geringe Gesprächslatenz, einen natürlichen Gesprächswechsel und eine schnelle Wiederaufnahme, wenn der Nutzer unterbricht (Barge-In).
  • Ihre Anwendung ruft externe Tools auf und benötigt eine nicht blockierende Ausführung, damit die Audioausgabe fortgesetzt wird, während Backend-Systeme Anfragen verarbeiten.
  • Sie möchten sprechende digitale Avatare mit synchronisierter Gesichtsanimation und Lip Sync mit 24 fps ohne externe Rendering-Pipelines rendern.
  • Ihre Nutzer unterhalten sich in mehreren Sprachen, was eine Spracherkennung während des Gesprächs und einen Wechsel zwischen den unterstützten Sprachen erfordert.
  • Sie benötigen eine fachspezifische Vokabulargewichtung für technische Begriffe, SKUs oder Markennamen.

Die vollständigen Spezifikationen und Kontingentlimits finden Sie auf der Seite zum Modell 3.8 Live.

Wichtige Funktionen in Gemini 3.8 Live

In Version 3.8 Live werden die folgenden Funktionen eingeführt:

  • Live-Avatar-Videosynthese mit 24 fps: 3.8 Live generiert synchronisierte MP4-Videostreams mit 24 fps (response_modalities=["VIDEO"]) direkt aus der Modellausgabe. Die generierten Gesichtsausdrücke und Lippenbewegungen werden in Echtzeit mit der synthetisierten Sprache synchronisiert.

    Sie können vordefinierte Standard-Avatare verwenden oder benutzerdefinierte Referenzbilder bereitstellen, um digitale Concierges, Kundenservice-KI-Agenten, virtuelle Tutoren oder interaktive Charaktere zu erstellen. Weitere Informationen zur Einrichtung finden Sie unter Live-Avatare konfigurieren.

  • Standardmäßig aktivierte Funktionen „Empathischer Dialog“ und „Proaktive Audioeingabe“:

    • Empathischer Dialog: Standardmäßig in 3.8 Live aktiviert. Das Modell verarbeitet akustische Prosodie, stimmliche Hinweise, Pausen und Sprachbeugung in der Audioeingabe des Nutzers, um den Tonfall und das Tempo der Unterhaltung anzupassen.
    • Proaktive Audioeingabe: Standardmäßig in 3.8 Live aktiviert. Das Modell filtert Umgebungsgeräusche und Hintergrundsprache heraus und generiert nur dann Audioantworten, wenn es vom Nutzer angesprochen wird.
  • Asynchrone und automatisch abgebrochene Aufrufe von Blockierfunktionen: 3.8 Live bietet Toolaufruf-Verhaltensweisen, die für Echtzeitsprache entwickelt wurden:

    • Nicht blockierende asynchrone Ausführung: Wenn das Modell einen Toolaufruf generiert, bleibt die Audiositzung aktiv, sodass der Agent Bestätigungen im Gespräch streamen („Ich rufe Ihre Kontodetails auf…“) und Folgeeingaben verarbeiten kann, während Ihre Client-App Backend-APIs aufruft.
    • Blockierende Aufrufe automatisch abbrechen (behavior="BLOCKING"): Wenn in einer Funktionsdeklaration behavior="BLOCKING" festgelegt ist, wird die Generierung pausiert, bis die Toolantwort eintrifft. Wenn während der Ausführung des blockierenden Aufrufs neue Nutzereingaben eingehen, bricht der Gemini Live API-Server den ausstehenden Aufruf ab.
    • Höfliches Unterbrechen: Bei früheren Modellen wurde die Antwort eines Tools mit scheduling="INTERRUPT" zurückgegeben, während der Nutzer sprach, was zu einer Überlagerung der Audioausgabe des Nutzers führte. In 3.8 Live stuft der Server den Zeitplan auf WHEN_IDLE herab, wenn der Nutzer spricht, und spielt die Antwort ab, nachdem der Nutzer aufgehört hat zu sprechen.
  • Dynamischer Wechsel zwischen mehreren Sprachen und benutzerdefiniertes Vokabular:

    • Mehrsprachige Unterstützung: Erkennt unterstützte Sprachen und wechselt während einer Sitzung zwischen ihnen, ohne dass die Verbindung neu gestartet oder konfiguriert werden muss.
    • Benutzerdefinierte Vokabulargewichtung: Akzeptiert domainspezifische Keywords, Eigennamen, medizinische Begriffe und Produktcodes in AudioTranscriptionConfig (über input_audio_transcription) mit custom_vocabulary, um die Transkriptionsgenauigkeit zu verbessern.
  • Multimodale visuelle Verankerung mit media_resolution-Steuerung: Akzeptiert Echtzeit-Videostreams (JPEG-Frames mit 1 FPS, empfohlene Auflösung 768x768) und ermöglicht die Konfiguration von media_resolution (MEDIA_RESOLUTION_LOW, MEDIA_RESOLUTION_MEDIUM, MEDIA_RESOLUTION_HIGH), um die Tokennutzung pro Frame und die visuellen Details auszubalancieren.

Kurzanleitung

Bevor Sie beginnen, authentifizieren Sie sich bei Google Cloud mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC).

Ersetzen Sie im folgenden Codebeispiel PROJECT_ID durch Ihre Projekt-ID von Google Cloud .

SDK installieren

Installieren oder aktualisieren Sie das Google Gen AI SDK und die Audioabhängigkeiten:

pip install --upgrade google-genai websockets numpy

Bidirektionale Sitzung mit asynchronem Toolaufruf starten

Im folgenden Beispiel wird eine Echtzeitsitzung mit gemini-3.8-live eingerichtet, eine vordefinierte Stimme (Aoede) ausgewählt, ein benutzerdefiniertes Vokabular-Biasing konfiguriert und nicht blockierende asynchrone Funktionsaufrufe ausgeführt:

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

Erforderliche API-Regeln und -Konventionen

Beachten Sie beim Entwickeln mit 3.8 Live die folgenden API-Konventionen:

  • Informative Funktionsantworten: Geben Sie von einem Tool-Handler kein leeres Wörterbuch ({}) oder None zurück. Wenn ein Tool einen Fehler oder eine leere Nutzlast zurückgibt, generiert 3.8 Live möglicherweise wiederholte Funktionsaufrufe mit geänderten Argumenten, es sei denn, die Antwort enthält Statusfelder. Geben Sie in jeder Toolantwort strukturierte Felder zurück:
    • status: Ein maschinenlesbarer Statusstring, z. B. "ok", "no_results" oder "invalid_argument".
    • retryable: Setzen Sie diesen Wert auf false, wenn die Wiederholung des Aufrufs dasselbe Ergebnis zurückgibt.
    • message oder guidance: Text, der den Status angibt, der dem Nutzer gemeldet werden soll.
  • Wiederholungslimits für Tools auf Prompt-Ebene: Fügen Sie ein Wiederholungslimit in Ihre system_instruction ein. Beispiel: „Wenn ein Toolaufruf keine Ergebnisse liefert, informiere den Nutzer, anstatt wiederholt mit Parametervariationen zu suchen. Führe nie mehr als zwei aufeinanderfolgende Toolaufrufe aus, ohne mit dem Nutzer zu sprechen.“
  • Strikter FunctionResponse-Abgleich:
    • Bei jeder FunctionResponse-Runde muss die genaue id aus der vorherigen FunctionCall angegeben werden.
    • Antwortobjekte direkt in FunctionResponse.response übergeben.
  • Streaming-Audioformate:
    • Eingabeaudio: 16 kHz, 16 Bit, Little Endian, Mono-PCM (audio/pcm;rate=16000), gestreamt in Blöcken von 20 ms bis 100 ms.
    • Ausgabeaudio: 24 kHz Mono-PCM.
  • Entfernte Legacy-Parameter: Übergeben Sie enable_affective_dialog oder proactivity nicht in Ihrer Konfiguration. Diese Funktionen sind in 3.8 Live standardmäßig aktiviert.
  • Unterhaltungsverlauf einfügen: Wenn Sie einen mehrstufigen Verlauf mit send_client_content einfügen, warten Sie, bis die Client-App den Server-Frame setup_complete empfängt, und konfigurieren Sie HistoryConfig(initial_history_in_client_content=True).

Zu Gemini 3.8 Live migrieren

Weitere Informationen zur Migration von gemini-live-2.5-flash-native-audio zu gemini-3.8-live finden Sie unter Von Gemini 2.5 Flash Live API Native Audio zu Gemini 3.8 Live migrieren.

Checkliste für Entwickler

Prüfen Sie vor der Bereitstellung Ihrer Anwendung Folgendes:

Zusätzliche Ressourcen

Weitere Informationen finden Sie in den folgenden Ressourcen: