Multimodal Live API

L'API Multimodal Live permet des interactions vocales et vidéo bidirectionnelles et à faible latence avec Gemini. L'API Multimodal Live vous permet de proposer aux utilisateurs finaux des conversations vocales naturelles et humaines, et de leur permettre d'interrompre les réponses du modèle à l'aide de commandes vocales. Le modèle peut traiter des entrées textuelles, audio et vidéo, et peut fournir des sorties textuelles et audio.

Vous pouvez essayer l'API Multimodal Live dans Google AI Studio.

Utiliser l'API Multimodal Live

Cette section explique comment utiliser l'API Multimodal Live avec l'un de nos SDK. Pour en savoir plus sur l'API WebSockets sous-jacente, consultez la documentation de référence de l'API WebSockets ci-dessous.

Envoyer et recevoir des SMS

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-exp"

config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send(input=message, end_of_turn=True)

            async for response in session.receive():
                if response.text is not None:
                    print(response.text, end="")

if __name__ == "__main__":
    asyncio.run(main())

Recevoir l'audio

L'exemple suivant montre comment recevoir des données audio et les écrire dans un fichier .wav.

import asyncio
import wave
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-exp"

config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        wf = wave.open("audio.wav", "wb")
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(24000)

        message = "Hello? Gemini are you there?"
        await session.send(input=message, end_of_turn=True)

        async for idx,response in async_enumerate(session.receive()):
            if response.data is not None:
                wf.writeframes(response.data)

            # Comment this out to print audio data info
            # if response.server_content.model_turn is not None:
            #      print(response.server_content.model_turn.parts[0].inline_data.mime_type)

        wf.close()

if __name__ == "__main__":
    asyncio.run(main())

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

Streaming audio et vidéo

Instructions système

Les instructions système vous permettent d'orienter le comportement d'un modèle en fonction de vos besoins et de vos cas d'utilisation spécifiques. Les instructions système peuvent être définies dans la configuration de configuration et resteront en vigueur pendant toute la session.

from google.genai import types

config = {
    "system_instruction": types.Content(
        parts=[
            types.Part(
                text="You are a helpful assistant and answer in a friendly tone."
            )
        ]
    ),
    "response_modalities": ["TEXT"],
}

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:

from google.genai import types

turns = [
    types.Content(parts=[types.Part(text="What is the capital of France?")], role="user"),
    types.Content(parts=[types.Part(text="Paris")], role="model")
]
await session.send(input=types.LiveClientContent(turns=turns))

turns = [types.Content(parts=[types.Part(text="What is the capital of Germany?")], role="user")]
await session.send(input=types.LiveClientContent(turns=turns, turn_complete=True))

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

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 ultérieures.

Changer de voix

L'API Multimodal Live est compatible avec les voix suivantes: Aoede, Charon, Fenrir, Kore et Puck.

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

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
        )
    )
)

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "Kore"
    }
  }
}

Utiliser l'appel de fonction

Vous pouvez définir des outils avec l'API Multimodal Live. Pour en savoir plus sur les appels de fonction, consultez le tutoriel sur les appels de fonction.

Les outils doivent être définis dans la configuration de la session:

config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    tools=[set_light_values]
)

async with client.aio.live.connect(model=model, config=config) as session:
    await session.send(input="Turn the lights down to a romantic level", end_of_turn=True)

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

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

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

Gérer les 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.

async for response in session.receive():
    if response.server_content.interrupted is not None:
        # The generation was interrupted

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 l'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.

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

Documentation de référence de l'API WebSockets

L'API Multimodal 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

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.

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
  },
  "systemInstruction": string,
  "tools": [object]
}

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:

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

Messages et événements

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 et Tool), consultez la section Générer du contenu.

Intégrations tierces

Pour les déploiements d'applications Web et mobiles, vous pouvez explorer les options suivantes:

• Tous les jours
• Livekit