Gemini Live API

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Die Gemini Live API ermöglicht bidirektionale Interaktionen mit niedriger Latenz, bei denen Text-, Audio- und Videoeingaben mit Audio- und Textausgaben verwendet werden. So sind natürliche, menschenähnliche Unterhaltungen möglich, bei denen das Modell jederzeit unterbrochen werden kann. Die Videoerkennung des Modells erweitert die Kommunikationsmodi. Sie können Kameraeingaben oder Bildschirmaufzeichnungen teilen und Fragen dazu stellen.

Leistungsspektrum

Die Live API bietet folgende Hauptfunktionen:

• Multimodalität: Das Modell kann sehen, hören und sprechen.
• Echtzeitinteraktion mit geringer Latenz: Das Modell kann schnell reagieren.
• Sitzungsgedächtnis: 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 von Daily.

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 zustandsorientierte API, die WebSockets verwendet.

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

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=us-central1
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

Eine WebSocket-Verbindung stellt eine Sitzung zwischen dem Client und dem Gemini-Server her.

Nachdem ein Client eine neue Verbindung gestartet hat, kann die Sitzung Nachrichten mit dem Server austauschen, 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, Systemanweisungen und Tools.

Hier 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 ein Feld aus der folgenden Objektmenge enthalten:

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

Unterstützte Clientnachrichten

Die unterstützten Clientnachrichten findest du in der folgenden Tabelle:

Nachrichten empfangen

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

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 ein Feld aus dem folgenden Objektsatz:

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

Unterstützte Servernachrichten

Die unterstützten Servernachrichten finden Sie in der folgenden Tabelle:

Inkrementelle Inhaltsaktualisierungen

Verwenden Sie inkrementelle Updates, um Texteingaben zu senden, den Sitzungskontext festzulegen oder den Sitzungskontext wiederherzustellen. Bei kurzen Kontexten können Sie Schritt-für-Schritt-Interaktionen senden, um die genaue Abfolge der Ereignisse darzustellen. Bei längeren Kontexten wird empfohlen, eine einzelne Nachrichtenzusammenfassung anzugeben, um das Kontextfenster für die nachfolgenden Interaktionen freizugeben.

Hier ein Beispiel für eine Kontextnachricht:

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

Inhaltsteile können zwar vom Typ functionResponse sein, BidiGenerateContentClientContent sollte jedoch nicht verwendet werden, um eine Antwort auf die vom Modell gesendeten Funktionsaufrufe zu geben. Stattdessen sollte BidiGenerateContentToolResponse verwendet werden. BidiGenerateContentClientContent sollte nur verwendet werden, um den vorherigen Kontext herzustellen oder Text in die Unterhaltung einzugeben.

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. Dazu müssen Sie Tooldefinitionen als Teil der BidiGenerateContentSetup-Nachricht senden.

Sie definieren Funktionen mit JSON, insbesondere mit einem ausgewählten Teil 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): Hier werden die von der Funktion benötigten Eingabedaten definiert.

  • type (String): Gibt den allgemeinen Datentyp an, z. B. „object“.

  • properties (Objekt): Hier werden einzelne Parameter mit folgenden Angaben aufgelistet:

    • 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 von Strings, das die Parameternamen enthält, die für die Funktion erforderlich sind.

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

Anhand eines einzelnen Prompts kann das Modell mehrere Funktionsaufrufe und den Code generieren, der zum Verketten der Ausgaben erforderlich ist. Dieser Code wird in einer Sandbox-Umgebung ausgeführt und generiert nachfolgende BidiGenerateContentToolCall-Nachrichten. Die Ausführung wird pausiert, bis die Ergebnisse der einzelnen Funktionsaufrufe 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

Die Live API unterstützt die folgenden Audioformate:

• Audioformat für Eingabe: Rohes 16-Bit-PCM-Audio mit 16 kHz und Little Endian
• Audioausgabeformat: Rohes 16-Bit-PCM-Audio mit 24 kHz, Little Endian

Systemanweisungen

Sie können Systemanweisungen bereitstellen, um die Ausgabe des Modells besser zu steuern und den Ton und die Stimmung der Audioantworten anzugeben.

Systemanweisungen werden dem Prompt vor Beginn der Interaktion hinzugefügt und bleiben für die gesamte Sitzung aktiv.

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 die Sprachaktivitätserkennung (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

Die Live API unterstützt die folgenden Stimmen:

• Puck
• Charon
• Kore
• Fenrir
• Aoede

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

Hier sehen Sie die JSON-Darstellung eines speechConfig-Objekts:

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

Beschränkungen

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

Clientauthentifizierung

Die Live API bietet nur eine Server-zu-Server-Authentifizierung und wird für die direkte Verwendung durch Clients nicht empfohlen. Der Client-Eingabe sollte für eine sichere Authentifizierung mit der Live API ein Zwischenanwendungsserver vorangestellt werden.

Unterhaltungsverlauf

Das Modell überwacht zwar die Interaktionen während einer Sitzung, der Unterhaltungsverlauf wird jedoch nicht gespeichert. Wenn eine Sitzung endet, wird der entsprechende Kontext gelöscht.

Um eine vorherige Sitzung wiederherzustellen oder dem Modell den bisherigen Kontext der Nutzerinteraktionen zur Verfügung zu stellen, sollte die Anwendung ein eigenes Unterhaltungsprotokoll führen und diese Informationen zu Beginn einer neuen Sitzung mit einer BidiGenerateContentClientContent-Nachricht senden.

Maximale Sitzungsdauer

Die Sitzungsdauer ist auf 15 Minuten für Audio oder 2 Minuten für Audio und Video beschränkt. Wenn die Sitzungsdauer das Limit überschreitet, wird die Verbindung beendet.

Das Modell ist außerdem durch die Kontextgröße begrenzt. Wenn du neben den Video- und Audiostreams große Inhaltsblöcke sendest, kann die Sitzung früher beendet werden.

Erkennung der Sprachaktivitäten (VAD)

Standardmäßig führt das Modell automatisch eine Sprachaktivitätserkennung (VAD) für einen kontinuierlichen Audioeingangsstream durch. Die Sprachaktivitätserkennung 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 alle im Cache gespeicherten Audioinhalte zu löschen. 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. Bei dieser Konfiguration ist der Client 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 gesendet. Stattdessen wird jede Unterbrechung des Streams durch eine ActivityEnd-Meldung gekennzeichnet.

Weitere Einschränkungen

Manuelles Endpunkt-Routing wird nicht unterstützt.

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

Tokenanzahl

Die Tokenanzahl wird nicht unterstützt.

Ratenlimits

Es gelten die folgenden Ratenbegrenzungen:

• 3 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.