API Multimodal Live

L'API Multimodal Live permet des interactions bidirectionnelles à faible latence qui utilisent des entrées texte, audio et vidéo, avec une sortie audio et texte. Cela facilite les conversations vocales naturelles et humaines, avec la possibilité d'interrompre le modèle à tout moment. La capacité de compréhension vidéo du modèle élargit les modalités de communication, ce qui vous permet de partager des entrées de l'appareil photo ou des enregistrements d'écran, et de poser des questions à leur sujet.

Capacités

L'API Multimodal Live inclut les principales fonctionnalités suivantes:

  • Multimodalité: le modèle peut voir, entendre et parler.
  • Interaction en temps réel à faible latence: le modèle peut fournir des réponses rapides.
  • Mémoire de session: le modèle conserve la mémoire de toutes les interactions au cours d'une même session, en rappelant les informations entendues ou vues précédemment.
  • Compatibilité avec l'appel de fonction, l'exécution de code et la recherche en tant qu'outil : vous pouvez intégrer le modèle à des services et des sources de données externes.

L'API Multimodal Live est conçue pour la communication de serveur à serveur.

Pour les applications Web et mobiles, nous vous recommandons d'utiliser l'intégration de nos partenaires Daily.

Premiers pas

L'API Multimodal Live est une API avec état qui utilise des WebSockets.

Cette section montre comment utiliser l'API Multimodal Live pour la génération de texte à partir de texte, à l'aide de Python 3.9 ou version ultérieure.

Installer la bibliothèque de l'API Gemini

Pour installer le package google-genai, utilisez la commande pip suivante:

!pip3 install google-genai

Importer des dépendances

Pour importer des dépendances:

from google import genai

Définir des variables d'environnement

Pour définir les valeurs appropriées et exporter les variables:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=YOUR_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True

Envoyer et recevoir un SMS


client = genai.Client()
model_id = "gemini-2.0-flash-exp"
config = {"responseModalities": ["TEXT"]}

async with client.aio.live.connect(model=model_id, config=config) as session:
    message = "Hello? Gemini, are you there?"
    print("> ", message, "\n")
    await session.send(message, end_of_turn=True)

    async for response in session.receive():
        print(response.text)

Guide d'intégration

Cette section décrit le fonctionnement de l'intégration avec l'API Multimodal Live.

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

La configuration de la session est envoyée dans le premier message après la connexion. Une configuration de session comprend le modèle, les paramètres de génération, les instructions système et les outils.

Consultez l'exemple de configuration suivant:


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

Pour en savoir plus, consultez BidiGenerateContentSetup.

Envoyer des messages

Les messages sont des objets au format JSON échangés via la connexion WebSocket.

Pour envoyer un message, 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 Entrée audio ou vidéo 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 :

ws.addEventListener("message", async (evt) => {
  if (evt.data instanceof Blob) {
    // Process the received data (audio, video, etc.)
  } else {
    // Process JSON response
  }
});

Les messages du serveur comportent exactement un des champs de l'ensemble d'objets suivant:


{
  "setupComplete": BidiGenerateContentSetupComplete,
  "serverContent": BidiGenerateContentServerContent,
  "toolCall": BidiGenerateContentToolCall,
  "toolCallCancellation": BidiGenerateContentToolCallCancellation
}

Messages de serveur compatibles

Consultez les messages de serveur compatibles dans le tableau suivant:

Message Description
BidiGenerateContentSetupComplete Message BidiGenerateContentSetup du client, envoyé une fois la configuration terminée
BidiGenerateContentServerContent Contenu généré par le modèle en réponse à un message client
BidiGenerateContentToolCall Demander au client d'exécuter les appels de fonction et de renvoyer les réponses avec les ID correspondants
BidiGenerateContentToolCallCancellation Envoyée lorsqu'un appel de fonction est annulé parce que l'utilisateur interrompt la sortie du modèle

Mises à jour incrémentielles du contenu

Utilisez des mises à jour incrémentielles pour envoyer une saisie de texte, établir le contexte de session ou restaurer le contexte de session. Pour les contextes courts, vous pouvez envoyer des interactions par étape pour représenter la séquence exacte des événements. Pour les contextes plus longs, nous vous recommandons de fournir un seul résumé de message afin de libérer la fenêtre de contexte pour les interactions de suivi.

Consultez l'exemple de message de contexte suivant:

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

Notez que, bien que les parties de contenu puissent être de type functionResponse, BidiGenerateContentClientContent ne doit pas être utilisé pour fournir une réponse aux appels de fonction émis par le modèle. Utilisez BidiGenerateContentToolResponse à la place. BidiGenerateContentClientContent ne doit être utilisé que pour établir le contexte précédent ou fournir une entrée de texte à la conversation.

Streaming audio et vidéo

Appel de fonction

Toutes les fonctions doivent être déclarées au début de la session en envoyant des définitions d'outils dans le message BidiGenerateContentSetup.

Vous définissez des fonctions à l'aide de JSON, en particulier avec un sous-ensemble sélectionné du format de schéma OpenAPI. Une seule déclaration de fonction peut inclure les paramètres suivants:

  • name (chaîne): identifiant unique de la fonction dans l'appel d'API.

  • description (chaîne): explication complète de l'objectif et des fonctionnalités de la fonction.

  • parameters (objet): définit les données d'entrée requises par la fonction.

    • type (chaîne): spécifie le type de données global, tel qu'un objet.

    • properties (objet): liste les paramètres individuels, chacun avec:

      • type (chaîne): type de données du paramètre, par exemple "chaîne", "entier" ou "booléen".
      • description (chaîne): explication claire de l'objectif du paramètre et du format attendu.

    • required (tableau): tableau de chaînes listant les noms de paramètres obligatoires pour que la fonction fonctionne.

Pour obtenir des exemples de code d'une déclaration de fonction à l'aide de commandes curl, consultez la section Présentation des appels de fonction avec l'API Gemini. Pour savoir comment créer des déclarations de fonction à l'aide des SDK de l'API Gemini, consultez le tutoriel sur l'appel de fonction.

À partir d'une seule invite, le modèle peut générer plusieurs appels de fonction et le code nécessaire pour enchaîner leurs sorties. Ce code s'exécute dans un environnement bac à sable, générant des messages BidiGenerateContentToolCall ultérieurs. L'exécution est mise en pause jusqu'à ce que les résultats de chaque appel de fonction soient disponibles, ce qui garantit un traitement séquentiel.

Le client doit répondre avec BidiGenerateContentToolResponse.

Formats audio

L'API Multimodal Live est compatible avec les formats audio suivants:

  • Format audio d'entrée: audio PCM brut 16 bits à 16 kHz, little-endian
  • Format audio de sortie: audio PCM brut 16 bits à 24 kHz, little-endian

Instructions système

Vous pouvez fournir des instructions système pour mieux contrôler la sortie du modèle et spécifier le ton et le sentiment des réponses audio.

Les instructions système sont ajoutées à l'invite avant le début de l'interaction et restent en vigueur pendant toute la session.

Les instructions système ne peuvent être définies qu'au début d'une session, immédiatement après la connexion initiale. Pour fournir d'autres informations au modèle pendant la session, utilisez des mises à jour de contenu incrémentielles.

Interruptions

Les utilisateurs peuvent interrompre la sortie du modèle à tout moment. Lorsque la détection d'activité vocale (VAD) détecte une interruption, la génération en cours est annulée et supprimée. Seules les informations déjà envoyées au client sont conservées dans l'historique de la session. Le serveur envoie ensuite un message BidiGenerateContentServerContent pour signaler l'interruption.

En outre, le serveur Gemini supprime tous les appels de fonction en attente et envoie un message BidiGenerateContentServerContent avec les ID des appels annulés.

Voix

L'API Multimodal Live est compatible avec les voix suivantes:

  • Palet
  • Charon
  • Kore
  • Fenrir
  • Aoede

Pour spécifier une voix, définissez voiceName dans l'objet speechConfig, dans le cadre de la configuration de la session.

Consultez la représentation JSON suivante d'un objet speechConfig:

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

Limites

Tenez compte des limites suivantes de l'API Multimodal Live et de Gemini 2.0 lorsque vous planifiez votre projet.

Authentification client

L'API Multimodal Live ne fournit qu'une authentification de serveur à serveur et n'est pas recommandée pour une utilisation directe par le client. L'entrée client doit être acheminée via un serveur d'application intermédiaire pour une authentification sécurisée avec l'API Multimodal Live.

Historique de la conversation

Bien que le modèle suive les interactions pendant la session, l'historique de la conversation n'est pas stocké. À la fin d'une session, le contexte correspondant est effacé.

Pour restaurer une session précédente ou fournir au modèle le contexte historique des interactions utilisateur, l'application doit gérer son propre journal de conversation et utiliser un message BidiGenerateContentClientContent pour envoyer ces informations au début d'une nouvelle session.

Durée maximale de la session

La durée de la session est limitée à 15 minutes pour l'audio ou à 2 minutes pour l'audio et la vidéo. Lorsque la durée de la session dépasse la limite, la connexion est interrompue.

Le modèle est également limité par la taille du contexte. L'envoi de grands blocs de contenu en plus des flux vidéo et audio peut entraîner la fin prématurée de la session.

Détection de l'activité vocale (VAD)

Le modèle effectue automatiquement la détection de l'activité vocale (VAD) sur un flux d'entrée audio continu. La suppression de la voix active est toujours activée et ses paramètres ne sont pas configurables.

Autres limites

Le point de terminaison manuel n'est pas accepté.

Les entrées et les sorties audio ont un impact négatif sur la capacité du modèle à utiliser l'appel de fonction.

Nombre de jetons

Le nombre de jetons n'est pas accepté.

Limites de débit

Les limites de débit suivantes s'appliquent:

  • 3 sessions simultanées par clé API
  • 4 millions de jetons par minute

Messages et événements

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

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 attendra d'autres messages avant de commencer la génération.

BidiGenerateContentRealtimeInput

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

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

  • Peut être envoyé en continu sans interruption de la génération du modèle.
  • Si vous devez mélanger des données entrelacées sur les ClientContentUpdate et les RealtimeUpdate, 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.
  • Il est toujours considéré comme l'entrée de l'utilisateur (ne peut pas être utilisé pour renseigner l'historique des conversations).
Champs
media_chunks[]

Blob

Facultatif. Données d'octets intégrées pour l'entrée multimédia.

BidiGenerateContentServerContent

Mise à jour incrémentielle du serveur générée par le modèle en réponse aux messages du 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
turn_complete

bool

Uniquement en sortie. Si la valeur est "true", cela signifie que la génération du modèle est terminée. La génération ne commencera qu'en réponse à des messages client supplémentaires. Peut être défini avec content, ce qui indique que content est le dernier élément du virage.
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 actuelle. 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.
grounding_metadata

GroundingMetadata

Uniquement en sortie. Les métadonnées spécifient les sources utilisées pour ancrer le contenu généré.
model_turn

Content

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

BidiGenerateContentSetup

Message à envoyer dans le premier et seul message client. Contient la configuration qui s'applique pendant toute la durée de la session de streaming.

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

Champs
model

string

Obligatoire. Nom complet du modèle éditeur ou du point de terminaison du modèle affiné à utiliser.

Format du modèle d'éditeur: projects/{project}/locations/{location}/publishers/\*/models/\*
generation_config

GenerationConfig

Facultatif. Configuration de génération.

Les champs suivants ne sont pas acceptés:

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

Content

Facultatif. Instructions système fournies par l'utilisateur pour le modèle. Remarque: Seul du texte doit être utilisé dans les parties. 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.

BidiGenerateContentSetupComplete

Ce type ne comporte aucun champ.

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

BidiGenerateContentToolCall

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

Champs
function_calls[]

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
function_responses[]

FunctionResponse

Facultatif. Réponse aux appels de fonction.

Étape suivante