Live API - WebSockets API reference

Die Live API ist eine zustandsorientierte API, die WebSockets verwendet. In diesem Abschnitt finden Sie weitere Informationen zur WebSockets API.

Sitzungen

Eine WebSocket-Verbindung stellt eine Sitzung zwischen dem Client und dem Gemini-Server her. Nachdem ein Client eine neue Verbindung initiiert 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.

WebSocket-Verbindung

Um eine Sitzung zu starten, verbinde dich mit diesem WebSocket-Endpunkt:

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent

Sitzungskonfiguration

Mit der ersten Nachricht nach der Verbindung wird die Sitzungskonfiguration festgelegt, die das Modell, die Generierungsparameter, die Systemanweisungen und die Tools enthält.

Sie können die Konfigurationsparameter mit Ausnahme des Modells während der Sitzung ändern.

Siehe die folgende Beispielkonfiguration. Die Groß- und Kleinschreibung der Namen in SDKs kann variieren. Hier finden Sie die Konfigurationsoptionen für das Python SDK.


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

Weitere Informationen zum API-Feld finden Sie unter generationConfig.

Nachrichten senden

Um Nachrichten über die WebSocket-Verbindung auszutauschen, 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:

Nachricht Beschreibung
BidiGenerateContentSetup Sitzungskonfiguration, die in der ersten Nachricht gesendet werden soll
BidiGenerateContentClientContent Inkrementelle Inhaltsaktualisierung der aktuellen Unterhaltung, die vom Client gesendet wird
BidiGenerateContentRealtimeInput Echtzeit-Audio-, Video- oder Texteingaben
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:

async with client.aio.live.connect(model='...', config=config) as session:
    await session.send(input='Hello world!', end_of_turn=True)
    async for message in session.receive():
        print(message)

Servernachrichten können ein usageMetadata-Feld enthalten, enthalten aber ansonsten genau eins der anderen Felder aus der BidiGenerateContentServerMessage-Nachricht. Die Union messageType wird nicht in JSON ausgedrückt, sodass das Feld auf der obersten Ebene der Nachricht angezeigt wird.

Nachrichten und Ereignisse

ActivityEnd

Dieser Typ hat keine Felder.

Markiert das Ende der Nutzeraktivität.

ActivityHandling

Die verschiedenen Möglichkeiten, mit Nutzeraktivitäten umzugehen.

Enums
ACTIVITY_HANDLING_UNSPECIFIED Wenn keine Angabe erfolgt, ist das Standardverhalten START_OF_ACTIVITY_INTERRUPTS.
START_OF_ACTIVITY_INTERRUPTS Wenn „true“ festgelegt ist, wird die Antwort des Modells durch den Beginn einer Aktivität unterbrochen (auch als „Barge-in“ bezeichnet). Die aktuelle Antwort des Modells wird im Moment der Unterbrechung abgeschnitten. Das ist das Standardverhalten.
NO_INTERRUPTION Die Antwort des Modells wird nicht unterbrochen.

ActivityStart

Dieser Typ hat keine Felder.

Markiert den Beginn der Nutzeraktivität.

AudioTranscriptionConfig

Dieser Typ hat keine Felder.

Die Konfiguration der Audiotranskription.

AutomaticActivityDetection

Hier können Sie die automatische Erkennung von Aktivitäten konfigurieren.

Felder
disabled

bool

Optional. Wenn diese Option aktiviert ist (Standardeinstellung), werden erkannte Sprach- und Texteingaben als Aktivität gezählt. Wenn diese Option deaktiviert ist, muss der Client Aktivitätssignale senden.
startOfSpeechSensitivity

StartSensitivity

Optional. Bestimmt, wie wahrscheinlich es ist, dass Sprache erkannt wird.
prefixPaddingMs

int32

Optional. Die erforderliche Dauer der erkannten Sprache, bevor der Sprachbeginn festgelegt wird. Je niedriger dieser Wert ist, desto empfindlicher ist die Erkennung des Sprachbeginns und desto kürzere Sprachinhalte können erkannt werden. Dadurch erhöht sich jedoch auch die Wahrscheinlichkeit von falsch positiven Ergebnissen.
endOfSpeechSensitivity

EndSensitivity

Optional. Bestimmt, wie wahrscheinlich es ist, dass erkannte Sprache beendet wird.
silenceDurationMs

int32

Optional. Die erforderliche Dauer der erkannten Sprachpause (z.B. Stille), bevor das Ende der Spracheingabe festgelegt wird. Je höher dieser Wert ist, desto länger können die Pausen zwischen den gesprochenen Texten sein, ohne die Aktivitäten des Nutzers zu unterbrechen. Dies erhöht jedoch die Latenz des Modells.

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.
turnComplete

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.

Die verschiedenen Modalitäten (Audio, Video und Text) werden als parallele Streams verarbeitet. Die Reihenfolge dieser Streams ist nicht garantiert.

Dieser unterscheidet sich in einigen Punkten von BidiGenerateContentClientContent:

  • Kann kontinuierlich und ohne Unterbrechung an die Modellgenerierung gesendet werden.
  • Wenn Daten zwischen BidiGenerateContentClientContent und BidiGenerateContentRealtimeInput 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 der Nutzeraktivität abgeleitet (z. B. Ende der Spracheingabe).
  • Die Daten werden bereits vor dem Ende des Turns inkrementell verarbeitet, um einen schnellen Beginn der Antwort des Modells zu ermöglichen.
Felder
mediaChunks[]

Blob

Optional. Inline-Byte-Daten für die Medieneingabe. Mehrere mediaChunks werden nicht unterstützt. Alle außer der ersten werden ignoriert.

VERWORFEN: Verwenden Sie stattdessen einen der Werte audio, video oder text.
audio

Blob

Optional. Diese bilden den Echtzeit-Audioeingangsstream.
video

Blob

Optional. Diese bilden den Echtzeit-Video-Eingabestream.
activityStart

ActivityStart

Optional. Markiert den Beginn der Nutzeraktivität. Diese Daten können nur gesendet werden, wenn die automatische (d.h. serverseitige) Aktivitätserkennung deaktiviert ist.
activityEnd

ActivityEnd

Optional. Markiert das Ende der Nutzeraktivität. Diese Daten können nur gesendet werden, wenn die automatische (d.h. serverseitige) Aktivitätserkennung deaktiviert ist.
audioStreamEnd

bool

Optional. Gibt an, dass der Audiostream beendet wurde, z.B. weil das Mikrofon deaktiviert wurde.

Diese Daten sollten nur gesendet werden, wenn die automatische Aktivitätserkennung aktiviert ist (Standardeinstellung).

Der Client kann den Stream wieder öffnen, indem er eine Audionachricht sendet.
text

string

Optional. Diese bilden den Echtzeit-Eingabestream für Text.

BidiGenerateContentServerContent

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

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

Felder
generationComplete

bool

Nur Ausgabe. Wenn „true“ (wahr) ist, ist die Generierung des Modells abgeschlossen.

Wenn das Modell während der Generierung unterbrochen wird, wird in der unterbrochenen Runde keine „generation_complete“-Nachricht gesendet. Stattdessen wird „interrupted > turn_complete“ verwendet.

Wenn das Modell eine Echtzeitwiedergabe annimmt, gibt es eine Verzögerung zwischen „generation_complete“ und „turn_complete“, weil das Modell auf das Ende der Wiedergabe wartet.
turnComplete

bool

Nur Ausgabe. Wenn „true“, gibt an, dass das Modell seinen Zug beendet hat. Die Generierung beginnt nur als Reaktion auf weitere Clientnachrichten.
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, die Wiedergabe zu beenden und die aktuelle Wiedergabeliste zu leeren.
groundingMetadata

GroundingMetadata

Nur Ausgabe. Metadaten für die generierten Inhalte.
outputTranscription

BidiGenerateContentTranscription

Nur Ausgabe. Audiotranskript ausgeben Die Transkription wird unabhängig von den anderen Servernachrichten gesendet und es gibt keine garantierte Reihenfolge, insbesondere nicht zwischen serverContent und dieser outputTranscription.
modelTurn

Content

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

BidiGenerateContentServerMessage

Antwortnachricht für den BidiGenerateContent-Aufruf.

Felder
usageMetadata

UsageMetadata

Nur Ausgabe. Nutzungsmetadaten zu den Antworten.
Union-Feld messageType. Der Typ der Nachricht. Für messageType ist nur einer der folgenden Werte zulässig:
setupComplete

BidiGenerateContentSetupComplete

Nur Ausgabe. Wird als Antwort auf eine BidiGenerateContentSetup-Nachricht vom Client gesendet, wenn die Einrichtung abgeschlossen ist.
serverContent

BidiGenerateContentServerContent

Nur Ausgabe. Vom Modell generierte Inhalte als Antwort auf Kundennachrichten.
toolCall

BidiGenerateContentToolCall

Nur Ausgabe. Bitte den Kunden, die functionCalls auszuführen und die Antworten mit den entsprechenden ids zurückzugeben.
toolCallCancellation

BidiGenerateContentToolCallCancellation

Nur Ausgabe. Benachrichtigung für den Kunden, dass eine zuvor ausgestellte ToolCallMessage mit den angegebenen ids storniert werden soll.
goAway

GoAway

Nur Ausgabe. Eine Benachrichtigung, dass die Verbindung zum Server bald getrennt wird.
sessionResumptionUpdate

SessionResumptionUpdate

Nur Ausgabe. Aktualisierung des Status der Sitzungswiederaufnahme.

BidiGenerateContentSetup

Nachricht, die in der ersten (und nur in der ersten) BidiGenerateContentClientMessage gesendet werden soll. Enthält eine Konfiguration, die für die Dauer des Streaming-RPC gilt.

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

Felder
model

string

Erforderlich. Der Ressourcenname des Modells. Diese dient als ID für das Modell.

Format: models/{model}
generationConfig

GenerationConfig

Optional. Generierungskonfiguration

Die folgenden Felder werden nicht unterstützt:

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

Content

Optional. Der Nutzer hat Systemanweisungen für das Modell bereitgestellt.

Hinweis: In den Teilen sollte nur Text verwendet werden. Der Inhalt jedes Teils wird in einem separaten Absatz angezeigt.
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.
realtimeInputConfig

RealtimeInputConfig

Optional. Hiermit wird die Verarbeitung von Echtzeiteingängen konfiguriert.
sessionResumption

SessionResumptionConfig

Optional. Konfiguriert den Mechanismus zur Sitzungswiederaufnahme.

Wenn das Flag enthalten ist, sendet der Server SessionResumptionUpdate-Nachrichten.
contextWindowCompression

ContextWindowCompressionConfig

Optional. Konfiguriert einen Komprimierungsmechanismus für den Kontextfenster.

Wenn diese Option aktiviert ist, reduziert der Server die Größe des Kontexts automatisch, wenn er die konfigurierte Länge überschreitet.
outputAudioTranscription

AudioTranscriptionConfig

Optional. Wenn diese Option aktiviert ist, wird die Audioausgabe des Modells transkribiert. Die Transkription entspricht dem Sprachcode, der für die Audioausgabe angegeben ist, sofern konfiguriert.

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 entsprechenden ids zurückzugeben.

Felder
functionCalls[]

FunctionCall

Nur Ausgabe. Der auszuführende Funktionsaufruf.

BidiGenerateContentToolCallCancellation

Benachrichtigung für den Kunden, dass eine zuvor ausgestellte ToolCallMessage mit den angegebenen ids nicht hätte ausgeführt werden sollen und storniert werden muss. 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
functionResponses[]

FunctionResponse

Optional. Die Antwort auf die Funktionsaufrufe.

BidiGenerateContentTranscription

Transkription von Audio (Eingabe oder Ausgabe).

Felder
text

string

Transkripttext

ContextWindowCompressionConfig

Aktiviert die Komprimierung des Kontextfensters – ein Mechanismus zum Verwalten des Kontextfensters des Modells, damit es eine bestimmte Länge nicht überschreitet.

Felder
Union-Feld compressionMechanism. Der verwendete Komprimierungsmechanismus für den Kontextfenster. Für compressionMechanism ist nur einer der folgenden Werte zulässig:
slidingWindow

SlidingWindow

Ein Gleitfenstermechanismus.
triggerTokens

int64

Die Anzahl der Tokens, die vor dem Ausführen eines Zuges erforderlich sind, um eine Komprimierung des Kontextfensters auszulösen.

So lässt sich die Qualität mit der Latenz in Einklang bringen, da kürzere Kontextfenster zu schnelleren Modellantworten führen können. Jeder Komprimierungsvorgang führt jedoch zu einer vorübergehenden Erhöhung der Latenz und sollte daher nicht häufig ausgelöst werden.

Wenn nicht festgelegt, beträgt der Standardwert 80% des Grenzwerts für das Kontextfenster des Modells. 20% bleiben für die nächste Nutzeranfrage/Modellantwort übrig.

EndSensitivity

Bestimmt, wie das Ende der Sprache erkannt wird.

Enums
END_SENSITIVITY_UNSPECIFIED Die Standardeinstellung ist END_SENSITIVITY_HIGH.
END_SENSITIVITY_HIGH Bei der automatischen Erkennung wird die Sprache häufiger beendet.
END_SENSITIVITY_LOW Bei der automatischen Erkennung wird die Sprache seltener beendet.

GoAway

Eine Benachrichtigung, dass die Verbindung zum Server bald getrennt wird.

Felder
timeLeft

Duration

Die verbleibende Zeit, bevor die Verbindung als ABGEBROCHEN beendet wird.

Diese Dauer ist immer länger als ein modellspezifisches Minimum, das zusammen mit den Ratenlimits für das Modell angegeben wird.

RealtimeInputConfig

Hiermit wird das Verhalten der Echtzeiteingabe in BidiGenerateContent konfiguriert.

Felder
automaticActivityDetection

AutomaticActivityDetection

Optional. Wenn Sie nichts festlegen, ist die automatische Aktivitätserkennung standardmäßig aktiviert. Wenn die automatische Spracherkennung deaktiviert ist, muss der Client Aktivitätssignale senden.
activityHandling

ActivityHandling

Optional. Hier wird definiert, welche Auswirkungen die Aktivität hat.
turnCoverage

TurnCoverage

Optional. Hier wird festgelegt, welche Eingabe in den Zug des Nutzers eingeschlossen ist.

SessionResumptionConfig

Konfiguration der Sitzungswiederaufnahme

Diese Nachricht ist in der Sitzungskonfiguration als BidiGenerateContentSetup.sessionResumption enthalten. Wenn konfiguriert, sendet der Server SessionResumptionUpdate Nachrichten.

Felder
handle

string

Der Handle einer vorherigen Sitzung. Ist das nicht der Fall, wird eine neue Sitzung erstellt.

Sitzungs-Handles stammen aus SessionResumptionUpdate.token-Werten in vorherigen Verbindungen.

SessionResumptionUpdate

Aktualisierung des Status der Sitzungswiederaufnahme.

Wird nur gesendet, wenn BidiGenerateContentSetup.sessionResumption festgelegt wurde.

Felder
newHandle

string

Neuer Alias, der einen Status darstellt, der fortgesetzt werden kann. Ist leer, wenn resumable=false.
resumable

bool

„Wahr“, wenn die aktuelle Sitzung an dieser Stelle fortgesetzt werden kann.

An einigen Stellen in der Sitzung ist die Fortsetzung nicht möglich. Beispielsweise, wenn das Modell Funktionsaufrufe ausführt oder generiert. Wenn die Sitzung in einem solchen Zustand fortgesetzt wird (mit einem vorherigen Sitzungstoken), kommt es zu Datenverlusten. In diesen Fällen ist newHandle leer und resumable ist falsch.

SlidingWindow

Bei der SlidingWindow-Methode werden Inhalte am Anfang des Kontextfensters verworfen. Der resultierende Kontext beginnt immer am Anfang einer USER-Rollenäußerung. Systemanweisungen und alle BidiGenerateContentSetup.prefixTurns bleiben immer am Anfang des Ergebnisses.

Felder
targetTokens

int64

Die Zielanzahl der zu behaltenden Tokens. Der Standardwert ist „trigger_tokens/2“.

Wenn Teile des Kontextfensters verworfen werden, führt dies zu einer vorübergehenden Erhöhung der Latenz. Daher sollte dieser Wert so kalibriert werden, dass häufige Komprimierungsvorgänge vermieden werden.

StartSensitivity

Bestimmt, wie der Beginn der Sprache erkannt wird.

Enums
START_SENSITIVITY_UNSPECIFIED Die Standardeinstellung ist START_SENSITIVITY_HIGH.
START_SENSITIVITY_HIGH Bei der automatischen Erkennung wird der Beginn von Spracheingaben häufiger erkannt.
START_SENSITIVITY_LOW Die automatische Erkennung erkennt den Beginn von Sprache dann seltener.

TurnCoverage

Optionen, welche Eingaben in den Beitrag des Nutzers aufgenommen werden sollen.

Enums
TURN_COVERAGE_UNSPECIFIED Wenn keine Angabe erfolgt, ist das Standardverhalten TURN_INCLUDES_ONLY_ACTIVITY.
TURN_INCLUDES_ONLY_ACTIVITY Der Nutzerbeitrag enthält nur Aktivitäten seit dem letzten Beitrag, ausgenommen Inaktivität (z.B. Stille im Audiostream). Das ist das Standardverhalten.
TURN_INCLUDES_ALL_INPUT Der Nutzerbeitrag enthält alle Echtzeiteingaben seit dem letzten Beitrag, einschließlich Inaktivität (z.B. Stille im Audiostream).

UsageMetadata

Nutzungsmetadaten zu Antworten.

Felder
promptTokenCount

int32

Nur Ausgabe. Anzahl der Tokens im Prompt. Wenn cachedContent festgelegt ist, ist dies immer noch die effektive Gesamtgröße des Prompts, einschließlich der Anzahl der Tokens im Cache-Inhalt.
cachedContentTokenCount

int32

Anzahl der Tokens im im Cache gespeicherten Teil des Prompts (im Cache gespeicherte Inhalte)
responseTokenCount

int32

Nur Ausgabe. Die Gesamtzahl der Tokens aller generierten Antwortkandidaten.
toolUsePromptTokenCount

int32

Nur Ausgabe. Anzahl der Tokens in den Prompts zur Toolnutzung.
thoughtsTokenCount

int32

Nur Ausgabe. Anzahl der Gedankentokens für Denkmodelle.
totalTokenCount

int32

Nur Ausgabe. Die Gesamtzahl der Tokens für die Generierungsanfrage (Prompt + Antwortkandidaten).
promptTokensDetails[]

ModalityTokenCount

Nur Ausgabe. Liste der Modalitäten, die in der Anfrageeingabe verarbeitet wurden.
cacheTokensDetails[]

ModalityTokenCount

Nur Ausgabe. Liste der Modalitäten der im Cache gespeicherten Inhalte in der Anfrage.
responseTokensDetails[]

ModalityTokenCount

Nur Ausgabe. Liste der Modalitäten, die in der Antwort zurückgegeben wurden.
toolUsePromptTokensDetails[]

ModalityTokenCount

Nur Ausgabe. Liste der Modalitäten, die für Eingaben von Toolnutzungsanfragen verarbeitet wurden.

Weitere Informationen zu gängigen Typen

Weitere Informationen zu den gängigen API-Ressourcentypen Blob, Content, FunctionCall, FunctionResponse, GenerationConfig, GroundingMetadata, ModalityTokenCount und Tool findest du unter Inhalte generieren.