Live API - WebSockets API reference

L'API Live est une API avec état qui utilise WebSockets. Cette section contient des informations supplémentaires sur l'API WebSockets.

Sessions

Une connexion WebSocket établit une session entre le client et le serveur Gemini. Une fois qu'un client a établi une nouvelle connexion, la session peut échanger des messages avec le serveur pour:

  • Envoyer du texte, de l'audio ou de la vidéo au serveur Gemini
  • Recevoir des requêtes d'appel audio, textuel ou de fonction à partir du serveur Gemini

Connexion WebSocket

Pour démarrer une session, connectez-vous à ce point de terminaison WebSocket:

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

Configuration de la session

Le message initial après la connexion définit la configuration de la session, qui comprend le modèle, les paramètres de génération, les instructions système et les outils.

Vous pouvez modifier les paramètres de configuration, à l'exception du modèle, pendant la session.

Consultez l'exemple de configuration suivant. Notez que la casse des noms dans les SDK peut varier. Vous pouvez consulter les options de configuration du SDK Python ici.


{
  "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]
}

Pour en savoir plus sur le champ de l'API, consultez generationConfig.

Envoyer des messages

Pour échanger des messages via la connexion WebSocket, le client doit envoyer un objet JSON via une connexion WebSocket ouverte. L'objet JSON doit comporter exactement un des champs de l'ensemble d'objets suivant:


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

Messages client compatibles

Consultez les messages client acceptés dans le tableau suivant:

Message Description
BidiGenerateContentSetup Configuration de la session à envoyer dans le premier message
BidiGenerateContentClientContent Mise à jour incrémentielle du contenu de la conversation en cours envoyée par le client
BidiGenerateContentRealtimeInput Saisie audio, vidéo ou textuelle en temps réel
BidiGenerateContentToolResponse Réponse à un ToolCallMessage reçu du serveur

Recevoir des messages

Pour recevoir des messages de Gemini, écoutez l'événement "message" WebSocket, puis analysez le résultat conformément à la définition des messages de serveur compatibles.

Consultez les références suivantes :

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)

Les messages du serveur peuvent comporter un champ usageMetadata, mais incluent exactement un des autres champs du message BidiGenerateContentServerMessage. (L'union messageType n'est pas exprimée en JSON. Le champ apparaît donc au niveau supérieur du message.)

Messages et événements

ActivityEnd

Ce type ne comporte aucun champ.

Indique la fin de l'activité de l'utilisateur.

ActivityHandling

Différentes façons de gérer l'activité des utilisateurs.

Enums
ACTIVITY_HANDLING_UNSPECIFIED Si aucune valeur n'est spécifiée, le comportement par défaut est START_OF_ACTIVITY_INTERRUPTS.
START_OF_ACTIVITY_INTERRUPTS Si la valeur est "true", le début de l'activité interrompt la réponse du modèle (également appelé "barrage"). La réponse actuelle du modèle sera interrompue au moment de l'interruption. Il s'agit du comportement par défaut.
NO_INTERRUPTION La réponse du modèle ne sera pas interrompue.

ActivityStart

Ce type ne comporte aucun champ.

Indique le début de l'activité de l'utilisateur.

AudioTranscriptionConfig

Ce type ne comporte aucun champ.

Configuration de la transcription audio.

AutomaticActivityDetection

Configure la détection automatique de l'activité.

Champs
disabled

bool

Facultatif. Si cette option est activée (valeur par défaut), la saisie vocale et textuelle détectée est comptabilisée comme activité. Si elle est désactivée, le client doit envoyer des signaux d'activité.

startOfSpeechSensitivity

StartSensitivity

Facultatif. Détermine la probabilité de détection de la parole.

prefixPaddingMs

int32

Facultatif. Durée requise de la parole détectée avant que le début de la parole ne soit validé. Plus cette valeur est faible, plus la détection du début de la parole est sensible et plus la parole peut être courte. Cependant, cela augmente également la probabilité de faux positifs.

endOfSpeechSensitivity

EndSensitivity

Facultatif. Détermine la probabilité que la parole détectée soit terminée.

silenceDurationMs

int32

Facultatif. Durée requise de contenu non vocal détecté (par exemple, silence) avant que la fin de la parole ne soit confirmée. Plus cette valeur est élevée, plus les pauses de parole peuvent être longues sans interrompre l'activité de l'utilisateur. Toutefois, cela augmente la latence du modèle.

BidiGenerateContentClientContent

Mise à jour incrémentielle de la conversation en cours envoyée par le client. Tout le contenu est ajouté sans condition à l'historique de la conversation et utilisé dans l'invite envoyée au modèle pour générer du contenu.

Un message s'affichera pour interrompre toute génération de modèle en cours.

Champs
turns[]

Content

Facultatif. Contenu ajouté à la conversation en cours avec le modèle.

Pour les requêtes à un seul tour, il s'agit d'une instance unique. Pour les requêtes multitours, il s'agit d'un champ répété contenant l'historique de la conversation et la dernière requête.

turnComplete

bool

Facultatif. Si la valeur est "true", la génération de contenu du serveur doit commencer par l'invite actuellement accumulée. Sinon, le serveur attend d'autres messages avant de commencer la génération.

BidiGenerateContentRealtimeInput

Entrée utilisateur envoyée en temps réel.

Les différentes modalités (audio, vidéo et texte) sont gérées en tant que flux simultanés. L'ordre de ces flux n'est pas garanti.

Cette méthode diffère de BidiGenerateContentClientContent de plusieurs manières:

  • Peut être envoyé en continu sans interruption pour la génération du modèle.
  • Si vous devez mélanger des données entrelacées sur BidiGenerateContentClientContent et BidiGenerateContentRealtimeInput, le serveur tente d'optimiser la réponse, mais aucune garantie n'est fournie.
  • La fin du tour n'est pas spécifiée explicitement, mais dérive de l'activité de l'utilisateur (par exemple, la fin de la parole).
  • Même avant la fin du tour, les données sont traitées de manière incrémentielle pour optimiser le démarrage rapide de la réponse du modèle.
Champs
mediaChunks[]

Blob

Facultatif. Données d'octets intégrées pour l'entrée multimédia. Plusieurs mediaChunks ne sont pas acceptés. Tous les éléments, sauf le premier, seront ignorés.

"DEPRECATED" (Obsolète) : utilisez plutôt audio, video ou text.

audio

Blob

Facultatif. Ils constituent le flux d'entrée audio en temps réel.

video

Blob

Facultatif. Ils constituent le flux d'entrée vidéo en temps réel.

activityStart

ActivityStart

Facultatif. Indique le début de l'activité de l'utilisateur. Cette information ne peut être envoyée que si la détection automatique (c'est-à-dire côté serveur) de l'activité est désactivée.

activityEnd

ActivityEnd

Facultatif. Indique la fin de l'activité de l'utilisateur. Cette information ne peut être envoyée que si la détection automatique (c'est-à-dire côté serveur) de l'activité est désactivée.

audioStreamEnd

bool

Facultatif. Indique que le flux audio a pris fin, par exemple parce que le micro a été désactivé.

Cette valeur ne doit être envoyée que lorsque la détection automatique des activités est activée (par défaut).

Le client peut rouvrir le flux en envoyant un message audio.

text

string

Facultatif. Ils constituent le flux d'entrée de texte en temps réel.

BidiGenerateContentServerContent

Mise à jour incrémentielle du serveur générée par le modèle en réponse aux messages client.

Le contenu est généré aussi rapidement que possible, et non en temps réel. Les clients peuvent choisir de mettre en mémoire tampon et de lire le contenu en temps réel.

Champs
generationComplete

bool

Uniquement en sortie. Si la valeur est "true", cela signifie que la génération du modèle est terminée.

Lorsque le modèle est interrompu pendant la génération, aucun message "generation_complete" n'est envoyé pendant le tour interrompu. Il passe par "interrupted > turn_complete".

Lorsque le modèle suppose une lecture en temps réel, un délai s'écoule entre generation_complete et turn_complete, car le modèle attend la fin de la lecture.

turnComplete

bool

Uniquement en sortie. Si la valeur est "true", cela signifie que le modèle a terminé son tour. La génération ne commencera qu'en réponse à des messages client supplémentaires.

interrupted

bool

Uniquement en sortie. Si la valeur est "true", cela indique qu'un message client a interrompu la génération de modèle en cours. Si le client lit le contenu en temps réel, c'est un bon signal pour arrêter et vider la file d'attente de lecture actuelle.

groundingMetadata

GroundingMetadata

Uniquement en sortie. Métadonnées de référence pour le contenu généré.

outputTranscription

BidiGenerateContentTranscription

Uniquement en sortie. Transcrire l'audio. La transcription est envoyée indépendamment des autres messages du serveur. Aucun ordre n'est garanti, en particulier entre serverContent et outputTranscription.

modelTurn

Content

Uniquement en sortie. Contenu généré par le modèle dans le cadre de la conversation en cours avec l'utilisateur.

BidiGenerateContentServerMessage

Message de réponse pour l'appel BidiGenerateContent.

Champs
usageMetadata

UsageMetadata

Uniquement en sortie. Métadonnées d'utilisation des réponses.

Champ d'union messageType. Type du message. messageType ne peut être qu'un des éléments suivants :
setupComplete

BidiGenerateContentSetupComplete

Uniquement en sortie. Envoyée en réponse à un message BidiGenerateContentSetup du client une fois la configuration terminée.

serverContent

BidiGenerateContentServerContent

Uniquement en sortie. Contenu généré par le modèle en réponse aux messages des clients.

toolCall

BidiGenerateContentToolCall

Uniquement en sortie. Demandez au client d'exécuter functionCalls et de renvoyer les réponses avec les id correspondants.

toolCallCancellation

BidiGenerateContentToolCallCancellation

Uniquement en sortie. Notification au client indiquant qu'un ToolCallMessage précédemment émis avec les id spécifiés doit être annulé.

goAway

GoAway

Uniquement en sortie. Notification indiquant que le serveur sera bientôt déconnecté.

sessionResumptionUpdate

SessionResumptionUpdate

Uniquement en sortie. Mise à jour de l'état de reprise de la session.

BidiGenerateContentSetup

Message à envoyer dans le premier (et seul) BidiGenerateContentClientMessage. Contient la configuration qui s'appliquera pendant toute la durée de l'RPC en streaming.

Les clients doivent attendre un message BidiGenerateContentSetupComplete avant d'envoyer des messages supplémentaires.

Champs
model

string

Obligatoire. Nom de la ressource du modèle. Il s'agit d'un identifiant que le modèle doit utiliser.

Format : models/{model}

generationConfig

GenerationConfig

Facultatif. Configuration de génération.

Les champs suivants ne sont pas acceptés:

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

Content

Facultatif. Instructions système fournies par l'utilisateur pour le modèle.

Remarque: Seul du texte doit être utilisé dans les parties et le contenu de chaque partie figurera dans un paragraphe distinct.

tools[]

Tool

Facultatif. Liste des Tools que le modèle peut utiliser pour générer la réponse suivante.

Un Tool est un morceau de code qui permet au système d'interagir avec des systèmes externes pour effectuer une action ou un ensemble d'actions en dehors du champ d'application et des connaissances du modèle.

realtimeInputConfig

RealtimeInputConfig

Facultatif. Configure la gestion des entrées en temps réel.

sessionResumption

SessionResumptionConfig

Facultatif. Configure le mécanisme de reprise de session.

Si elle est incluse, le serveur envoie des messages SessionResumptionUpdate.

contextWindowCompression

ContextWindowCompressionConfig

Facultatif. Configure un mécanisme de compression de fenêtre de contexte.

Si elle est incluse, le serveur réduit automatiquement la taille du contexte lorsqu'elle dépasse la longueur configurée.

outputAudioTranscription

AudioTranscriptionConfig

Facultatif. Si défini, active la transcription de la sortie audio du modèle. La transcription correspond au code de langue spécifié pour l'audio de sortie, le cas échéant.

BidiGenerateContentSetupComplete

Ce type ne comporte aucun champ.

Envoyée en réponse à un message BidiGenerateContentSetup du client.

BidiGenerateContentToolCall

Demandez au client d'exécuter functionCalls et de renvoyer les réponses avec les id correspondants.

Champs
functionCalls[]

FunctionCall

Uniquement en sortie. Appel de fonction à exécuter.

BidiGenerateContentToolCallCancellation

Notification au client indiquant qu'une ToolCallMessage précédemment émise avec les id spécifiées n'aurait pas dû être exécutée et doit être annulée. Si ces appels d'outils ont des effets secondaires, les clients peuvent essayer de les annuler. Ce message ne s'affiche que lorsque les clients interrompent les tours du serveur.

Champs
ids[]

string

Uniquement en sortie. ID des appels d'outil à annuler.

BidiGenerateContentToolResponse

Réponse générée par le client à un ToolCall reçu du serveur. Les objets FunctionResponse individuels sont mis en correspondance avec les objets FunctionCall respectifs par le champ id.

Notez que dans les API GenerateContent unary et server-streaming, l'appel de fonction s'effectue en échangeant les parties Content, tandis que dans les API GenerateContent bidi, l'appel de fonction s'effectue sur cet ensemble de messages dédié.

Champs
functionResponses[]

FunctionResponse

Facultatif. Réponse aux appels de fonction.

BidiGenerateContentTranscription

Transcription de l'audio (entrée ou sortie).

Champs
text

string

Texte de la transcription.

ContextWindowCompressionConfig

Active la compression de la fenêtre de contexte, un mécanisme permettant de gérer la fenêtre de contexte du modèle afin qu'elle ne dépasse pas une longueur donnée.

Champs
Champ d'union compressionMechanism. Mécanisme de compression de la fenêtre de contexte utilisé. compressionMechanism ne peut être qu'un des éléments suivants :
slidingWindow

SlidingWindow

Un mécanisme de fenêtre glissante.

triggerTokens

int64

Nombre de jetons (avant l'exécution d'un tour) requis pour déclencher une compression de la fenêtre de contexte.

Vous pouvez l'utiliser pour équilibrer la qualité et la latence, car des fenêtres contextuelles plus courtes peuvent entraîner des réponses plus rapides du modèle. Toutefois, toute opération de compression entraîne une augmentation temporaire de la latence. Par conséquent, elles ne doivent pas être déclenchées fréquemment.

Si ce paramètre n'est pas défini, la valeur par défaut est de 80% de la limite de la fenêtre contextuelle du modèle. Il reste donc 20% pour la prochaine requête utilisateur/réponse du modèle.

EndSensitivity

Détermine comment la fin de la parole est détectée.

Enums
END_SENSITIVITY_UNSPECIFIED La valeur par défaut est END_SENSITIVITY_HIGH.
END_SENSITIVITY_HIGH La détection automatique met fin à la parole plus souvent.
END_SENSITIVITY_LOW La détection automatique met fin à la parole moins souvent.

GoAway

Notification indiquant que le serveur sera bientôt déconnecté.

Champs
timeLeft

Duration

Temps restant avant que la connexion ne soit arrêtée en tant que "ABORTED".

Cette durée ne sera jamais inférieure à une durée minimale spécifique au modèle, qui sera spécifiée avec les limites de débit du modèle.

RealtimeInputConfig

Configure le comportement des entrées en temps réel dans BidiGenerateContent.

Champs
automaticActivityDetection

AutomaticActivityDetection

Facultatif. Si ce champ n'est pas défini, la détection automatique des activités est activée par défaut. Si la détection vocale automatique est désactivée, le client doit envoyer des signaux d'activité.

activityHandling

ActivityHandling

Facultatif. Définit l'effet de l'activité.

turnCoverage

TurnCoverage

Facultatif. Définit l'entrée incluse au tour de l'utilisateur.

SessionResumptionConfig

Configuration de la reprise de session.

Ce message est inclus dans la configuration de la session sous la forme BidiGenerateContentSetup.sessionResumption. Si le serveur est configuré, il envoie des messages SessionResumptionUpdate.

Champs
handle

string

Poignée d'une session précédente. Si ce n'est pas le cas, une session est créée.

Les poignées de session proviennent des valeurs SessionResumptionUpdate.token des connexions précédentes.

SessionResumptionUpdate

Mise à jour de l'état de reprise de la session.

N'est envoyé que si BidiGenerateContentSetup.sessionResumption a été défini.

Champs
newHandle

string

Nouvel identifiant représentant un état pouvant être repris. Vide si resumable=false.

resumable

bool

"True" si la session en cours peut être reprise à ce stade.

La reprise n'est pas possible à certains moments de la session. Par exemple, lorsque le modèle exécute des appels de fonction ou génère des données. La reprise de la session (à l'aide d'un jeton de session précédent) dans cet état entraînera une perte de données. Dans ce cas, newHandle sera vide et resumable sera défini sur "false".

SlidingWindow

La méthode SlidingWindow fonctionne en supprimant le contenu au début de la fenêtre de contexte. Le contexte obtenu commence toujours au début d'un tour de rôle UTILISATEUR. Les instructions système et les BidiGenerateContentSetup.prefixTurns restent toujours au début du résultat.

Champs
targetTokens

int64

Nombre cible de jetons à conserver. La valeur par défaut est "trigger_tokens/2".

L'abandon de parties de la fenêtre de contexte entraîne une augmentation temporaire de la latence. Cette valeur doit donc être calibrée pour éviter les opérations de compression fréquentes.

StartSensitivity

Détermine comment le début de la parole est détecté.

Enums
START_SENSITIVITY_UNSPECIFIED La valeur par défaut est START_SENSITIVITY_HIGH.
START_SENSITIVITY_HIGH La détection automatique détectera plus souvent le début de la parole.
START_SENSITIVITY_LOW La détection automatique détectera moins souvent le début de la parole.

TurnCoverage

Options concernant l'entrée incluse dans le tour de l'utilisateur.

Enums
TURN_COVERAGE_UNSPECIFIED Si aucune valeur n'est spécifiée, le comportement par défaut est TURN_INCLUDES_ONLY_ACTIVITY.
TURN_INCLUDES_ONLY_ACTIVITY Le tour de l'utilisateur n'inclut que l'activité depuis le dernier tour, à l'exclusion de l'inactivité (par exemple, le silence sur le flux audio). Il s'agit du comportement par défaut.
TURN_INCLUDES_ALL_INPUT Le tour de l'utilisateur inclut toutes les entrées en temps réel depuis le dernier tour, y compris l'inactivité (par exemple, le silence sur le flux audio).

UsageMetadata

Métadonnées d'utilisation des réponses.

Champs
promptTokenCount

int32

Uniquement en sortie. Nombre de jetons dans l'invite. Lorsque cachedContent est défini, il s'agit toujours de la taille totale effective de la requête, ce qui signifie qu'elle inclut le nombre de jetons dans le contenu mis en cache.

cachedContentTokenCount

int32

Nombre de jetons dans la partie mise en cache de l'invite (le contenu mis en cache)

responseTokenCount

int32

Uniquement en sortie. Nombre total de jetons pour toutes les réponses candidates générées.

toolUsePromptTokenCount

int32

Uniquement en sortie. Nombre de jetons présents dans la ou les requêtes d'utilisation de l'outil.

thoughtsTokenCount

int32

Uniquement en sortie. Nombre de jetons de pensées pour les modèles de réflexion.

totalTokenCount

int32

Uniquement en sortie. Nombre total de jetons pour la requête de génération (invite + candidats de réponse).

promptTokensDetails[]

ModalityTokenCount

Uniquement en sortie. Liste des modalités traitées dans l'entrée de la requête.

cacheTokensDetails[]

ModalityTokenCount

Uniquement en sortie. Liste des modalités du contenu mis en cache dans l'entrée de la requête.

responseTokensDetails[]

ModalityTokenCount

Uniquement en sortie. Liste des modalités renvoyées dans la réponse.

toolUsePromptTokensDetails[]

ModalityTokenCount

Uniquement en sortie. Liste des modalités qui ont été traitées pour les entrées de requêtes d'utilisation d'outils.

En savoir plus sur les types courants

Pour en savoir plus sur les types de ressources d'API couramment utilisés (Blob, Content, FunctionCall, FunctionResponse, GenerationConfig, GroundingMetadata, ModalityTokenCount et Tool), consultez la section Générer du contenu.