Multimodal Live API

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

Leistungsspektrum

Die Multimodal Live API bietet folgende Hauptfunktionen:

  • Multimodalität: Das Modell kann sehen, hören und sprechen.
  • Echtzeitinteraktion mit geringer Latenz: Das Modell kann schnell reagieren.
  • 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 „Suchen als Tool“: Sie können das Modell in externe Dienste und Datenquellen einbinden.

Die Multimodal 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 Multimodal Live API ausprobieren möchten, rufen Sie Vertex AI Studio auf und klicken Sie dann auf Multimodal Live ausprobieren.

Die Multimodal Live API ist eine zustandsorientierte API, die WebSockets verwendet.

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

Gen AI SDK für Python

Informationen zum Installieren oder Aktualisieren des Google Gen AI SDK for Python
Weitere Informationen finden Sie in der Referenzdokumentation zur Gen AI SDK for Python API oder im python-genaiGitHub-Repository.
Umgebungsvariablen für die Verwendung des Gen AI SDK mit Vertex AI festlegen: 

# 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 LiveConnectConfig, HttpOptions, Modality

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
model_id = "gemini-2.0-flash-exp"

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(input=text_input, end_of_turn=True)

    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 Multimodal 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:

Meldung Beschreibung
BidiGenerateContentSetup Sitzungskonfiguration, die in der ersten Nachricht gesendet werden soll
BidiGenerateContentClientContent Inkrementenelle Inhaltsaktualisierung der aktuellen Unterhaltung, die vom Client gesendet wird
BidiGenerateContentRealtimeInput Audio- oder Videoeingabe in Echtzeit
BidiGenerateContentToolResponse Antwort auf eine vom Server empfangene ToolCallMessage

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
}

Unterstützte Servernachrichten

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

Meldung Beschreibung
BidiGenerateContentSetupComplete Eine BidiGenerateContentSetup-Nachricht vom Client, die gesendet wird, wenn die Einrichtung abgeschlossen ist
BidiGenerateContentServerContent Vom Modell generierte Inhalte als Antwort auf eine Kundennachricht
BidiGenerateContentToolCall Der Client wird aufgefordert, die Funktionsaufrufe auszuführen und die Antworten mit den übereinstimmenden IDs zurückzugeben.
BidiGenerateContentToolCallCancellation Wird gesendet, wenn ein Funktionsaufruf abgebrochen wird, weil der Nutzer die Modellausgabe unterbrochen hat.

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 den Typ functionResponse haben, 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 Einführung in Funktionsaufrufe 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 Multimodal 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 Multimodal 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 Multimodal Live API und Gemini 2.0.

Clientauthentifizierung

Die Multimodal Live API bietet nur eine Server-zu-Server-Authentifizierung und wird für die direkte Verwendung durch Clients nicht empfohlen. Die Clienteingabe sollte für eine sichere Authentifizierung mit der Multimodal Live API über einen Zwischenanwendungsserver geleitet 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)

Das Modell führt automatisch eine Sprachaktivitätserkennung (VAD) auf einem kontinuierlichen Audioeingangsstream aus. Die Sprachaktivitätserkennung ist immer aktiviert und ihre Parameter können nicht konfiguriert werden.

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

BidiGenerateContentClientContent

Inkrementelle Aktualisierung der aktuellen Unterhaltung, die vom Client gesendet wird. Alle Inhalte hier werden dem Unterhaltungsverlauf angefügt und als Teil des Prompts an das Modell zur Generierung von Inhalten verwendet.

Eine Nachricht hier unterbricht die aktuelle Modellgenerierung.

Felder
turns[]

Content

Optional. Der Inhalt, der an die aktuelle Unterhaltung mit dem Modell angehängt wird.

Bei Einzelabfragen ist dies eine einzelne Instanz. Bei Mehrfachabfragen ist dies ein wiederkehrendes Feld, das den Unterhaltungsverlauf und die letzte Anfrage enthält.
turn_complete

bool

Optional. Wenn „wahr“ ist, sollte die Serverinhaltsgenerierung mit dem aktuell angesammelten Prompt beginnen. Andernfalls wartet der Server auf weitere Nachrichten, bevor die Generierung gestartet wird.

BidiGenerateContentRealtimeInput

Nutzereingaben, die in Echtzeit gesendet werden.

Dieser unterscheidet sich in einigen Punkten von ClientContentUpdate:

  • Kann kontinuierlich und ohne Unterbrechung an die Modellgenerierung gesendet werden.
  • Wenn Daten zwischen ClientContentUpdate und RealtimeUpdate verschachtelt werden müssen, versucht der Server, die Antwort zu optimieren. Es gibt jedoch keine Garantie dafür.
  • „Ende der Äußerung“ wird nicht explizit angegeben, sondern wird vielmehr aus Nutzeraktivitäten abgeleitet (z. B. Ende der Spracheingabe).
  • Die Daten werden bereits vor dem Ende des Gesprächsschritts inkrementell verarbeitet, um einen schnellen Start der Antwort des Modells zu ermöglichen.
  • Wird immer als Eingabe des Nutzers angenommen und kann nicht zum Ausfüllen des Unterhaltungsverlaufs verwendet werden.
Felder
media_chunks[]

Blob

Optional. Inline-Byte-Daten für die Medieneingabe.

BidiGenerateContentServerContent

Inkrementelle Serveraktualisierung, die vom Modell als Reaktion auf Clientnachrichten generiert wird.

Die Inhalte werden so schnell wie möglich, aber nicht in Echtzeit generiert. Clients können die Daten zwischenspeichern und in Echtzeit wiedergeben.

Felder
turn_complete

bool

Nur Ausgabe. Wenn „true“ (wahr) ist, ist die Generierung des Modells abgeschlossen. Die Generierung beginnt nur als Reaktion auf weitere Clientnachrichten. Kann zusammen mit content festgelegt werden, um anzugeben, dass content der letzte Wert in der Kurve ist.
interrupted

bool

Nur Ausgabe. Wenn dieser Wert „true“ ist, wurde die aktuelle Modellgenerierung durch eine Clientnachricht unterbrochen. Wenn der Client die Inhalte in Echtzeit wiedergibt, ist dies ein gutes Signal, um die Wiedergabe anzuhalten und die aktuelle Warteschlange zu leeren. Wenn der Client die Inhalte in Echtzeit wiedergibt, ist dies ein gutes Signal, die Wiedergabe zu beenden und die aktuelle Wiedergabeliste zu leeren.
grounding_metadata

GroundingMetadata

Nur Ausgabe. In den Metadaten werden die Quellen angegeben, die zum Fundieren der generierten Inhalte verwendet wurden.
model_turn

Content

Nur Ausgabe. Die Inhalte, die das Modell im Rahmen der aktuellen Unterhaltung mit dem Nutzer generiert hat.

BidiGenerateContentSetup

Nachricht, die in der ersten und einzigen ersten Kundennachricht gesendet werden soll. Enthält die Konfiguration, die für die Dauer der Streamingsitzung gilt.

Clients sollten auf eine BidiGenerateContentSetupComplete-Nachricht warten, bevor sie weitere Nachrichten senden.

Felder
model

string

Pflichtangabe. Der voll qualifizierte Name des Endpunkts des Publisher-Modells oder des optimierten Modells, der verwendet werden soll.

Format des Publisher-Modells: projects/{project}/locations/{location}/publishers/\*/models/\*
generation_config

GenerationConfig

Optional. Generierungskonfiguration

Die folgenden Felder werden nicht unterstützt:

  • responseLogprobs
  • responseMimeType
  • logprobs
  • responseSchema
  • stopSequence
  • routingConfig
  • audioTimestamp
system_instruction

Content

Optional. Der Nutzer hat Systemanweisungen für das Modell bereitgestellt. Hinweis: Nur Text sollte in Teilen verwendet werden. Der Inhalt jedes Teils steht in einem separaten Absatz.
tools[]

Tool

Optional. Eine Liste von Tools, die das Modell zum Generieren der nächsten Antwort verwenden kann.

Ein Tool ist ein Code, der es dem System ermöglicht, mit externen Systemen zu interagieren, um eine Aktion oder eine Reihe von Aktionen außerhalb des Wissens und Umfangs des Modells auszuführen.

BidiGenerateContentSetupComplete

Dieser Typ hat keine Felder.

Wird als Antwort auf eine BidiGenerateContentSetup-Nachricht vom Client gesendet.

BidiGenerateContentToolCall

Bitte den Kunden, die functionCalls auszuführen und die Antworten mit den übereinstimmenden ids zurückzugeben.

Felder
function_calls[]

FunctionCall

Nur Ausgabe. Der auszuführende Funktionsaufruf.

BidiGenerateContentToolCallCancellation

Benachrichtigung für den Kunden, dass eine zuvor ausgestellte ToolCallMessage mit den angegebenen ids nicht ausgeführt und storniert werden sollte. Wenn diese Toolaufrufe Nebenwirkungen hatten, können Kunden versuchen, sie rückgängig zu machen. Diese Meldung wird nur angezeigt, wenn die Clients die Server-Runden unterbrechen.

Felder
ids[]

string

Nur Ausgabe. Die IDs der abzubrechenden Toolaufrufe.

BidiGenerateContentToolResponse

Vom Client generierte Antwort auf eine vom Server empfangene ToolCall. Einzelne FunctionResponse-Objekte werden über das Feld id mit den entsprechenden FunctionCall-Objekten abgeglichen.

Bei den unary- und serverseitigen Streaming-GenerateContent APIs erfolgt der Funktionsaufruf durch den Austausch der Content-Teile, während bei den bidi-GenerateContent APIs der Funktionsaufruf über diese speziellen Nachrichten erfolgt.

Felder
function_responses[]

FunctionResponse

Optional. Die Antwort auf die Funktionsaufrufe.

Nächste Schritte