Live API-Referenz

Dieses Dokument enthält eine Referenz für die Live API und zeigt, wie Sie sie für bidirektionales Streaming mit Gemini verwenden. Es deckt folgende Themenbereiche ab:

• Funktionen:Hier erfahren Sie mehr über die wichtigsten Funktionen der Live API, darunter Multimodalität und Interaktion mit geringer Latenz.
• Erste Schritte:Hier finden Sie ein Kurzanleitungsbeispiel für die Verwendung der API mit der Text-zu-Text-Generierung.
• Integrationsleitfaden:Hier werden die wichtigsten Konzepte für die Integration in die API erläutert, z. B. Sitzungen, Nachrichtentypen und Funktionsaufrufe.
• Einschränkungen:Sehen Sie sich die aktuellen Einschränkungen der API an, einschließlich Sitzungsdauer und Authentifizierung.
• Nachrichten und Ereignisse:Hier finden Sie die detaillierte Referenz für alle Client- und Servernachrichten.

Das folgende Diagramm fasst den gesamten Workflow zusammen:

Mit der Live API können Sie latenzarme, bidirektionale Sprach- und Videounterhaltungen mit Gemini führen. Sie können natürliche, menschenähnliche Interaktionen für Ihre Nutzer erstellen, einschließlich der Möglichkeit, die Antworten des Modells mit Sprachbefehlen zu unterbrechen. Die Live API verarbeitet Text-, Audio- und Videoeingaben und gibt Text und Audio aus.

Weitere Informationen zur Live API finden Sie unter Live API.

Leistungsspektrum

Die Live API bietet die folgenden wichtigen Funktionen:

• Multimodalität: Das Modell kann sehen, hören und sprechen.
• Interaktion in Echtzeit mit geringer Latenz: Das Modell liefert schnelle Antworten für einen flüssigen Dialog.
• Sitzungsspeicher: Das Modell speichert alle Interaktionen innerhalb einer einzelnen Sitzung und ruft zuvor gehörte oder gesehene Informationen ab.
• Unterstützung von Funktionsaufrufen, Codeausführung und der Google Suche als Tool: Sie können das Modell in externe Dienste und Datenquellen einbinden.

Die Live API ist für die Server-zu-Server-Kommunikation konzipiert. Für Web- und mobile Apps empfehlen wir die Integration unserer Partner von Daily.

Unterstützte Modelle

• Gemini 2.5 Flash mit nativer Audio-Live-API
  previewVorschau
• Gemini 2.0 Flash mit Live API
  previewVorschau
• Gemini 2.5 Flash

Jetzt starten

Wenn Sie die Live API ausprobieren möchten, rufen Sie Vertex AI Studio auf und klicken Sie auf Sitzung starten.

Die Live API ist eine zustandsbehaftete API, die WebSockets verwendet.

In diesem Abschnitt finden Sie ein Beispiel für die Verwendung der Live API für die Text-zu-Text-Generierung mit Python 3.9 oder höher.

pip install --upgrade google-genai

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import (Content, HttpOptions, LiveConnectConfig,
                                Modality, Part)

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
model_id = "gemini-2.0-flash-live-preview-04-09"

async with client.aio.live.connect(
    model=model_id,
    config=LiveConnectConfig(response_modalities=[Modality.TEXT]),
) as session:
    text_input = "Hello? Gemini, are you there?"
    print("> ", text_input, "\n")
    await session.send_client_content(
        turns=Content(role="user", parts=[Part(text=text_input)])
    )

    response = []

    async for message in session.receive():
        if message.text:
            response.append(message.text)

    print("".join(response))
# Example output:
# >  Hello? Gemini, are you there?
# Yes, I'm here. What would you like to talk about?

Integrationsleitfaden

In diesem Abschnitt wird beschrieben, wie Sie Ihre Anwendung in die Live API einbinden.

Sitzungen

Über eine WebSocket-Verbindung wird eine Sitzung zwischen dem Client und dem Gemini-Server hergestellt. Nachdem Sie eine neue Verbindung hergestellt haben, kann Ihr Client Nachrichten mit dem Server austauschen, um Folgendes zu tun:

• Text, Audio oder Video an den Gemini-Server senden
• Audio-, Text- oder Funktionsaufrufanfragen vom Gemini-Server empfangen.

Senden Sie die Sitzungskonfiguration in der ersten Nachricht, nachdem Sie eine Verbindung hergestellt haben. Eine Sitzungskonfiguration umfasst das Modell, die Parameter für die Generierung, die Systemanweisungen und die Tools.

Hier sehen Sie eine Beispielkonfiguration:

{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object
  },

  "systemInstruction": string,
  "tools": [object]
}

Weitere Informationen finden Sie unter BidiGenerateContentSetup.

Nachrichten senden

Nachrichten sind JSON-formatierte Objekte, die über die WebSocket-Verbindung ausgetauscht werden.

Um eine Nachricht zu senden, sendet Ihr Client ein JSON-Objekt über eine offene WebSocket-Verbindung. Das JSON-Objekt muss genau eines der Felder aus der folgenden Objektgruppe enthalten:

{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

Unterstützte Client-Nachrichten

In der folgenden Tabelle werden die Nachrichten beschrieben, die Sie an den Server senden können.

Nachrichten empfangen

Wenn Sie Nachrichten von Gemini erhalten möchten, müssen Sie auf das WebSocket-Ereignis message warten. Parsen Sie dann das Ergebnis gemäß den Definitionen der unterstützten Servermeldungen.

Beispiel:

ws.addEventListener("message", async (evt) => {
  if (evt.data instanceof Blob) {
    // Process the received data (audio, video, etc.)
  } else {
    // Process JSON response
  }
});

Servernachrichten enthalten genau eines der Felder aus der folgenden Objektgruppe:

{
  "setupComplete": BidiGenerateContentSetupComplete,
  "serverContent": BidiGenerateContentServerContent,
  "toolCall": BidiGenerateContentToolCall,
  "toolCallCancellation": BidiGenerateContentToolCallCancellation
  "usageMetadata": UsageMetadata
  "goAway": GoAway
  "sessionResumptionUpdate": SessionResumptionUpdate
  "inputTranscription": BidiGenerateContentTranscription
  "outputTranscription": BidiGenerateContentTranscription
}

Unterstützte Servermeldungen

In der folgenden Tabelle werden die Nachrichten beschrieben, die Sie vom Server erhalten können.

Inkrementelle Inhaltsupdates

Verwenden Sie inkrementelle Updates, um Texteingaben zu senden, Sitzungskontext zu erstellen oder wiederherzustellen. Bei kurzen Kontexten können Sie Turn-by-Turn-Interaktionen senden, um die genaue Abfolge der Ereignisse darzustellen. Bei längeren Kontexten empfehlen wir, eine einzelne Nachrichtenzusammenfassung bereitzustellen, um das Kontextfenster für Folgeinteraktionen freizugeben.

Hier sehen Sie ein Beispiel für eine Kontextnachricht:

{
  "clientContent": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

Inhaltsteile können vom Typ functionResponse sein, aber verwenden Sie BidiGenerateContentClientContent nicht, um auf Funktionsaufrufe des Modells zu reagieren. Verwenden Sie stattdessen BidiGenerateContentToolResponse. Verwenden Sie BidiGenerateContentClientContent nur, um den vorherigen Kontext herzustellen oder Texteingaben für die Unterhaltung bereitzustellen.

Audio- und Videostreaming

Codeausführung

Weitere Informationen zur Codeausführung finden Sie unter Codeausführung.

Funktionsaufrufe

Sie müssen alle Funktionen zu Beginn der Sitzung deklarieren, indem Sie Tool-Definitionen als Teil der BidiGenerateContentSetup-Nachricht senden.

Sie definieren Funktionen mit JSON, insbesondere mit einer ausgewählten Teilmenge des OpenAPI-Schemaformats.

Eine einzelne Funktionsdeklaration kann die folgenden Parameter enthalten:

• name (String): Die eindeutige Kennung für die Funktion im API-Aufruf.
• description (String): Eine umfassende Erläuterung des Zwecks und der Funktionen der Funktion.
• parameters (Objekt): Definiert die Eingabedaten, die für die Funktion erforderlich sind.
  • type (String): Gibt den allgemeinen Datentyp an, z. B. „object“.
  • properties (Objekt): Listet einzelne Parameter auf, jeweils mit:
    • type (String): Der Datentyp des Parameters, z. B. String, Ganzzahl oder boolescher Wert.
    • description (String): Eine klare Erläuterung des Zwecks und des erwarteten Formats des Parameters.
  • required (Array): Ein Array mit Strings, in dem die Parameternamen aufgeführt sind, die für die Funktion erforderlich sind.

Codebeispiele für eine Funktionsdeklaration mit curl-Befehlen finden Sie unter Funktionsaufrufe mit der Gemini API. Beispiele für das Erstellen von Funktionsdeklarationen mit den Gemini API SDKs finden Sie im Tutorial zu Funktionsaufrufen.

Aus einem einzelnen Prompt kann das Modell mehrere Funktionsaufrufe und den Code zum Verketten ihrer Ausgaben generieren. Dieser Code wird in einer Sandbox-Umgebung ausgeführt und generiert nachfolgende BidiGenerateContentToolCall-Nachrichten. Die Ausführung wird angehalten, bis die Ergebnisse jedes Funktionsaufrufs verfügbar sind. So wird eine sequenzielle Verarbeitung ermöglicht.

Der Client sollte mit BidiGenerateContentToolResponse antworten.

Weitere Informationen finden Sie unter Einführung in Funktionsaufrufe.

Audioformate

Liste der unterstützten Audioformate

Systemanweisungen

Sie können Systemanweisungen angeben, um die Ausgabe des Modells besser zu steuern und den Ton und die Stimmung von Audioantworten festzulegen.

Systemanweisungen werden dem Prompt vor Beginn der Interaktion hinzugefügt und bleiben für die gesamte Sitzung in Kraft. Sie können sie nur zu Beginn einer Sitzung festlegen, unmittelbar nach der ersten Verbindung. Wenn Sie dem Modell während der Sitzung mehr Informationen zur Verfügung stellen möchten, verwenden Sie inkrementelle Inhaltsaktualisierungen.

Unterbrechungen

Nutzer können die Ausgabe des Modells jederzeit unterbrechen. Wenn die Sprachaktivitätserkennung (Voice Activity Detection, VAD) eine Unterbrechung erkennt, wird die laufende Generierung abgebrochen und verworfen. Im Sitzungsverlauf werden nur die Informationen aufbewahrt, die bereits an den Client gesendet wurden. Der Server sendet dann eine BidiGenerateContentServerContent-Nachricht, um die Unterbrechung zu melden.

Außerdem verwirft der Gemini-Server alle ausstehenden Funktionsaufrufe und sendet eine BidiGenerateContentServerContent-Nachricht mit den IDs der abgebrochenen Aufrufe.

Stimmen

Wenn Sie eine Stimme angeben möchten, legen Sie voiceName im Objekt speechConfig als Teil Ihrer Sitzungskonfiguration fest.

Im Folgenden finden Sie eine JSON-Darstellung eines speechConfig-Objekts:

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "VOICE_NAME"
    }
  }
}

Eine Liste der unterstützten Stimmen finden Sie unter Sprach- und Spracherkennungseinstellungen ändern.

Beschränkungen

Beachten Sie bei der Planung Ihres Projekts die folgenden Einschränkungen der Live API und von Gemini 2.0.

Clientauthentifizierung

Die Live API bietet nur die Server-zu-Server-Authentifizierung und wird nicht für die direkte Clientnutzung empfohlen. Leiten Sie Client-Eingaben über einen Zwischenanwendungsserver weiter, um eine sichere Authentifizierung mit der Live API zu ermöglichen.

Maximale Sitzungsdauer

Die maximale Länge einer Unterhaltungssitzung beträgt standardmäßig 10 Minuten. Weitere Informationen finden Sie unter Sitzungslänge.

Erkennung von Sprachaktivitäten (Voice Activity Detection, VAD)

Standardmäßig führt das Modell automatisch die Sprachaktivitätserkennung (Voice Activity Detection, VAD) für einen kontinuierlichen Audioeingabestream aus. Sie können VAD mit dem Feld RealtimeInputConfig.AutomaticActivityDetection der Einrichtungsnachricht konfigurieren.

Die API unterstützt zwei VAD-Modi:

• Automatische VAD (Standard): Der Server erkennt die Sprache des Nutzers.

  • Wenn der Audio-Stream länger als eine Sekunde pausiert wird (z. B. wenn der Nutzer das Mikrofon stummschaltet), wird ein AudioStreamEnd-Ereignis gesendet, um zwischengespeicherte Audioinhalte zu leeren.
  • Ihr Client kann das Senden von Audiodaten jederzeit fortsetzen.

• Manuelle VAD: Wenn Sie diesen Modus verwenden möchten, legen Sie in der Einrichtungsnachricht für RealtimeInputConfig.AutomaticActivityDetection.disabled den Wert true fest.

  • Ihr Client ist dafür verantwortlich, die Sprache des Nutzers zu erkennen und ActivityStart- und ActivityEnd-Nachrichten zum richtigen Zeitpunkt zu senden.
  • In dieser Konfiguration wird kein AudioStreamEnd-Ereignis gesendet. Stattdessen wird jede Unterbrechung des Streams mit einer ActivityEnd-Meldung gekennzeichnet.

Weitere Einschränkungen

• Manuelle Endpunkte werden nicht unterstützt.
• Audioeingaben und ‑ausgaben können sich negativ auf die Fähigkeit des Modells auswirken, Funktionsaufrufe zu verwenden.

Anzahl der Tokens

Die Anzahl der Tokens wird nicht unterstützt.

Ratenlimits

Es gelten die folgenden Ratenbegrenzungen:

• 5.000 gleichzeitige Sitzungen pro API-Schlüssel
• 4 Millionen Tokens pro Minute

Nachrichten und Ereignisse

Nächste Schritte

• Weitere Informationen zu Funktionsaufrufen
• Beispiele finden Sie in der Referenz zu Funktionsaufrufen.