Live API-Referenz

Die Live API ermöglicht bidirektionale Sprach- und Videointeraktionen mit geringer Latenz mit Gemini. Mit der Live API können Sie Endnutzern natürliche, menschenähnliche Sprachkonversationen ermöglichen und die Möglichkeit bieten, die Antworten des Modells mit Sprachbefehlen zu unterbrechen. Die Live API kann Text-, Audio- und Videoeingaben verarbeiten und Text- und Audioausgaben bereitstellen.

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.
• Echtzeitinteraktion mit geringer Latenz: Das Modell kann schnelle Antworten liefern.
• Sitzungsspeicher: Das Modell speichert alle Interaktionen innerhalb einer einzelnen Sitzung und ruft zuvor gehörte oder gesehene Informationen ab.
• Unterstützung für Funktionsaufrufe, Codeausführung und die 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 bei 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+.

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,
    LiveConnectConfig,
    HttpOptions,
    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 die Integration mit der Live API funktioniert.

Sitzungen

Über eine WebSocket-Verbindung wird eine Sitzung zwischen dem Client und dem Gemini-Server hergestellt.

Nachdem ein Client eine neue Verbindung hergestellt hat, können in der Sitzung Nachrichten mit dem Server ausgetauscht werden, um:

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

Die Sitzungskonfiguration wird in der ersten Nachricht nach der Verbindung gesendet. Eine Sitzungskonfiguration umfasst das Modell, die Generierungsparameter, 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, muss der Client ein JSON-Objekt über eine offene WebSocket-Verbindung senden. Das JSON-Objekt muss genau eines der Felder aus der folgenden Objektgruppe enthalten:

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

Unterstützte Clientnachrichten

Die unterstützten Clientnachrichten sind in der folgenden Tabelle aufgeführt:

Nachrichten empfangen

Wenn Sie Nachrichten von Gemini empfangen möchten, müssen Sie auf das WebSocket-Ereignis „message“ warten und das Ergebnis dann gemäß der Definition der unterstützten Servernachrichten parsen.

Weitere Informationen finden Sie hier:

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

Die unterstützten Servernachrichten sind in der folgenden Tabelle aufgeführt:

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 empfiehlt es sich, eine einzelne Nachrichtenzusammenfassung bereitzustellen, um das Kontextfenster für die Folgeinteraktionen freizugeben.

Hier ein Beispiel für eine Kontextnachricht:

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

Inhaltsabschnitte können zwar vom Typ functionResponse sein, BidiGenerateContentClientContent sollte jedoch nicht verwendet werden, um eine Antwort auf die vom Modell ausgegebenen Funktionsaufrufe zu geben. Verwenden Sie stattdessen BidiGenerateContentToolResponse. BidiGenerateContentClientContent sollte nur verwendet werden, um 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

Alle Funktionen müssen zu Beginn der Sitzung deklariert werden, indem Tool-Definitionen als Teil der BidiGenerateContentSetup-Nachricht gesendet werden.

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 Erklärung 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): Hier werden die einzelnen Parameter mit folgenden Attributen aufgeführt:

    • type (string): Der Datentyp des Parameters, z. B. „string“, „integer“ oder „boolean“.
    • description (string): Eine klare Erläuterung des Zwecks und des erwarteten Formats des Parameters.

  • required (Array): Ein Array von Strings mit den Parameternamen, 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 generieren, der zum Verketten ihrer Ausgaben erforderlich ist. 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 sichergestellt.

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 verwenden, 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.

Systemanweisungen können nur zu Beginn einer Sitzung festgelegt werden, unmittelbar nach der ersten Verbindung. Wenn Sie dem Modell während der Sitzung weitere Eingaben zur Verfügung stellen möchten, verwenden Sie inkrementelle Inhaltsaktualisierungen.

Unterbrechungen

Nutzer können die Ausgabe des Modells jederzeit unterbrechen. Wenn durch die Spracherkennung (Voice Activity Detection, VAD) eine Unterbrechung erkannt wird, wird die laufende Generierung abgebrochen und verworfen. Im Sitzungsverlauf werden nur die Informationen gespeichert, 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.

Hier sehen Sie die 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. Die Clienteingabe sollte über einen Zwischenanwendungsserver weitergeleitet werden, um eine sichere Authentifizierung bei 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 Spracherkennung (Voice Activity Detection, VAD) für einen kontinuierlichen Audioeingabestream durch. VAD kann mit dem Feld RealtimeInputConfig.AutomaticActivityDetection der Einrichtungsnachricht konfiguriert werden.

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

Alternativ kann die automatische VAD deaktiviert werden, indem in der Einrichtungsnachricht RealtimeInputConfig.AutomaticActivityDetection.disabled auf true gesetzt wird. In dieser Konfiguration ist der Client dafür verantwortlich, die Sprache des Nutzers zu erkennen und ActivityStart- und ActivityEnd-Nachrichten zu den entsprechenden Zeiten zu senden. In dieser Konfiguration wird kein AudioStreamEnd gesendet. Stattdessen wird jede Unterbrechung des Streams durch eine ActivityEnd-Meldung gekennzeichnet.

Zusätzliche Einschränkungen

Manuelle Endpunkte werden nicht unterstützt.

Audioeingaben und ‑ausgaben beeinträchtigen die Fähigkeit des Modells, Funktionsaufrufe zu verwenden.

Tokenanzahl

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.