Entwicklerleitfaden für Gemini 3.8 Live

Gemini 3.8 Live ist ein Konversationsmodell für Echtzeitinteraktionen, das für bidirektionale Sprach- und Videointeraktionen mit niedriger Latenz und für die Live-Avatarsynthese in persönlichen Gesprächen entwickelt wurde. 3.8 Live wurde für kontinuierliche Konversationsabläufe entwickelt und bietet standardmäßig aktivierte Funktionen wie empathischen Dialog, proaktive Audiofilterung, automatische Deaktivierung von Blockierungstools und dynamische mehrsprachige Umschaltung.

In diesem Dokument werden folgende Themen behandelt:

• Wie sich 3.8 Live in die Gemini-Modellfamilie einfügt
• Hauptfunktionen von 3.8 Live
• Integration mit dem 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 wurde für Streaming-Interaktionen in Echtzeit entwickelt. Es funktioniert über bidirektionale WebSockets und verarbeitet Sprache, Live-Kamerafeeds und Bildschirmübertragungen mit einer Latenz von weniger als einer Sekunde. Dabei werden 24-kHz-Audio und synchronisierte 24-fps-Videoavatare generiert.

Modellspezifikationen und Vergleiche

In der folgenden Tabelle werden die Spezifikationen von 3.8 Live mit denen früherer Gemini Live API-Modelle verglichen:

Wann sollte Gemini 3.8 Live verwendet werden?

Verwenden Sie 3.8 Live in den folgenden Szenarien:

• Sie benötigen eine niedrige Konversationslatenz, natürliche Gesprächsabläufe und eine schnelle Wiederherstellung, wenn der Nutzer unterbricht (Barge-in).
• Ihre App ruft externe Tools auf und erfordert eine nicht blockierende Ausführung, damit die Audioausgabe fortgesetzt werden kann, 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. Daher ist eine Spracherkennung und ‑umschaltung zwischen unterstützten Sprachen während des Streams erforderlich.
• Sie benötigen einen domainspezifischen Bias für Fachbegriffe, Artikelnummern oder Markennamen.

Vollständige Spezifikationen und Kontingentlimits finden Sie auf der 3.8 Live Modellseite.

Hauptfunktionen von Gemini 3.8 Live

3.8 Live bietet die folgenden Funktionen:

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

  Sie können vorgefertigte Stock-Avatare verwenden oder benutzerdefinierte Referenzbilder bereitstellen, um digitale Concierges, Kundenservicemitarbeiter, virtuelle Tutoren oder interaktive Charaktere zu erstellen. Details zur Einrichtung finden Sie unter Live Avatare konfigurieren.

• Standardmäßig aktivierter empathischer Dialog und proaktives Audio:

  • Empathischer Dialog: In 3.8 Live standardmäßig aktiviert. Das Modell verarbeitet akustische Prosodie, stimmliche Hinweise, Pausen und Sprachmelodie in der Audioeingabe des Nutzers, um den Stimmton und das Gesprächstempo anzupassen.
  • Proaktives Audio: In 3.8 Live standardmäßig aktiviert. Das Modell filtert Umgebungsgeräusche und Hintergrundgespräche und generiert nur dann Audioantworten, wenn es vom Nutzer angesprochen wird.

• Asynchrone und automatische Deaktivierung von Blockierungstools: 3.8 Live bietet Tool-Aufrufverhalten, das für Echtzeit-Sprache entwickelt wurde:

  • Nicht blockierende asynchrone Ausführung: Wenn das Modell einen Tool Aufruf generiert, bleibt die Audiositzung aktiv, sodass der Agent Konversationsbestätigungen streamen kann ("Ich rufe Ihre Kontodetails auf...") und Folgeeingaben verarbeiten kann, während Ihre Client-App Backend-APIs aufruft.
  • Automatische Deaktivierung von Blockierungstools (behavior="BLOCKING"): Wenn in einer Funktionsdeklaration behavior="BLOCKING" festgelegt ist, wird die Generierung angehalten, bis die Tool-Antwort eintrifft. Wenn während des Blockierungsaufrufs eine neue Nutzereingabe eingeht, bricht der Gemini Live API-Server den ausstehenden Aufruf ab.
  • Umgang mit Unterbrechungen: In früheren Modellen wurde die Audioausgabe des Nutzers überlappt, wenn eine Tool Antwort mit scheduling="INTERRUPT" zurückgegeben wurde, während der Nutzer sprach. In 3.8 Live stuft der Server den Zeitplan auf WHEN_IDLE herab, wenn der Nutzer spricht, und gibt die Antwort aus, nachdem der Nutzer aufgehört hat zu sprechen.

• Dynamische mehrsprachige Umschaltung und benutzerdefiniertes Vokabular:

  • Mehrsprachige Unterstützung: Erkennt und wechselt während der Sitzung zwischen unterstützten Sprachen, ohne die Verbindung neu zu starten oder neu zu konfigurieren.
  • Bias für benutzerdefiniertes Vokabular: 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 Videostreams in Echtzeit (JPEG-Frames mit 1 FPS, empfohlene Auflösung 768x768) und ermöglicht Ihnen, media_resolution (MEDIA_RESOLUTION_LOW, MEDIA_RESOLUTION_MEDIUM, MEDIA_RESOLUTION_HIGH) zu konfigurieren, um die Token-Nutzung pro Frame und die visuellen Details auszubalancieren.

Kurzanleitung

Authentifizieren Sie sich zuerst Cloud de Confiance by S3NS mit den Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC).

Ersetzen Sie im folgenden Codebeispiel PROJECT_ID durch Ihre Cloud de Confiance Projekt-ID.

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 asynchronen Tool-Aufrufen starten

Im folgenden Beispiel wird eine Echtzeitsitzung mit gemini-3.8-live eingerichtet, ein Bias für benutzerdefiniertes Vokabular 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

Halten Sie sich bei der Entwicklung mit 3.8 Live an die folgenden API-Konventionen:

• Informative Funktionsantworten: Geben Sie kein leeres Wörterbuch ({}) oder None von einem Tool-Handler zurück. Wenn ein Tool einen Fehler oder eine leere Nutzlast zurückgibt, kann 3.8 Live wiederholte Funktionsaufrufe mit geänderten Argumenten generieren, es sei denn, die Antwort enthält Statusfelder. Geben Sie in jeder Tool-Antwort strukturierte Felder zurück:
  • status: Ein maschinenlesbarer Statusstring wie "ok", "no_results", oder "invalid_argument".
  • retryable: Auf false setzen, wenn die Wiederholung des Aufrufs dasselbe Ergebnis zurückgibt.
  • message oder guidance: Text, der den Status angibt, der dem Nutzer gemeldet werden soll.
• Limits für Tool-Wiederholungen auf Promptebene: Fügen Sie in Ihre system_instruction ein Limit für Wiederholungen ein. Beispiel: "Wenn ein Tool-Aufruf keine Ergebnisse zurückgibt, informieren Sie den Nutzer, anstatt wiederholt mit Parameteränderungen zu suchen. Führen Sie niemals mehr als zwei aufeinanderfolgende Tool-Aufrufe aus, ohne mit dem Nutzer zu sprechen."
• Strikte FunctionResponse Übereinstimmung:
  • Jede FunctionResponse-Wendung muss die genaue id aus dem vorherigen FunctionCall enthalten.
  • Übergeben Sie Antwortobjekte direkt in FunctionResponse.response.
• Streaming-Audioformate:
  • Audioeingabe: 16 kHz, 16 Bit, Little-Endian, Mono-PCM (audio/pcm;rate=16000), in Blöcken von 20 bis 100 ms gestreamt.
  • Audioausgabe: 24 kHz Mono-PCM.
• Entfernte Legacy-Parameter: Übergeben Sie in Ihrer Konfiguration nicht enable_affective_dialog oder proactivity. Diese Funktionen sind in 3.8 Live standardmäßig aktiviert.
• Konversationsverlauf vorbereiten: Wenn Sie den Verlauf für mehrere Wendungen mit send_client_content vorbereiten, warten Sie, bis die Client-App den setup_complete Server-Frame 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 die folgenden Punkte, bevor Sie Ihre App bereitstellen:

Zusätzliche Ressourcen

Weitere Informationen finden Sie in den folgenden Ressourcen:

• Modellseite zu Gemini 3.8 Live
• Live-Avatare konfigurieren
• Best Practices für die Gemini Live API
• Von Gemini 2.5 Flash Live API Native Audio zu Gemini 3.8 Live migrieren
• Gemini Live API-Python-Tutorial
• Einführung in das Notebook „Live-Avatar“
• Gemini Live API Service Skill