Live API

L'API Live permet des interactions vocales et vidéo bidirectionnelles et à faible latence avec Gemini. Grâce à l'API Live, vous pouvez offrir aux utilisateurs finaux une expérience de conversation vocale naturelle et humaine, et la possibilité 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 Live dans Google AI Studio.

Nouveautés

L'API Live propose de nouvelles fonctionnalités.

Nouvelles fonctionnalités :

• Deux nouvelles voix et 30 nouvelles langues, avec une langue de sortie configurable
• Résolutions d'image configurables : 66/256 jetons
• Couverture de virage configurable: envoyez toutes les entrées en permanence ou uniquement lorsque l'utilisateur parle.
• Configurer si l'entrée doit interrompre le modèle ou non
• Détection de l'activité vocale configurable et nouveaux événements client pour la signalisation de fin de tour
• Nombre de jetons
• Événement client pour signaler la fin du flux
• Streaming de texte
• Réactivation de session configurable, avec les données de session stockées sur le serveur pendant 24 heures
• Compatibilité avec des sessions plus longues grâce à une fenêtre de contexte coulissante

Événements de nouveaux clients:

• Fin du flux audio / Micro fermé
• Événements de début/fin d'activité pour contrôler manuellement la transition de virage

Nouveaux événements de serveur:

• Notification de départ indiquant qu'une session doit être redémarrée
• Génération terminée

Utiliser l'API Live

Cette section explique comment utiliser l'API 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.

Envoyer et recevoir des SMS

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

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_client_content(
                turns={"role": "user", "parts": [{"text": message}]}, turn_complete=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-live-001"

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_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

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

            # Un-comment this code 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 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:

turns = [
    {"role": "user", "parts": [{"text": "What is the capital of France?"}]},
    {"role": "model", "parts": [{"text": "Paris"}]},
]

await session.send_client_content(turns=turns, turn_complete=False)

turns = [{"role": "user", "parts": [{"text": "What is the capital of Germany?"}]}]

await session.send_client_content(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 Live est compatible avec les voix suivantes: Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus et Zephyr.

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 Live. Consultez le tutoriel sur les appels de fonction pour en savoir plus.

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_client_content(
        turns={
            "role": "user",
            "parts": [{"text": "Turn the lights down to a romantic level"}],
        },
        turn_complete=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

Configurer la détection de l'activité vocale (VAD)

Par défaut, le modèle effectue automatiquement la détection de l'activité vocale (VAD) sur un flux d'entrée audio continu. La VAD peut être configurée avec le champ realtimeInputConfig.automaticActivityDetection de la configuration de configuration.

Lorsque le flux audio est mis en pause pendant plus d'une seconde (par exemple, parce que l'utilisateur a désactivé le micro), un événement audioStreamEnd doit être envoyé pour vider tout contenu audio mis en cache. Le client peut reprendre l'envoi de données audio à tout moment.

Vous pouvez également désactiver la suppression automatique du bruit en définissant realtimeInputConfig.automaticActivityDetection.disabled sur true dans le message de configuration. Dans cette configuration, le client est chargé de détecter la parole de l'utilisateur et d'envoyer des messages activityStart et activityEnd au moment opportun. Aucun audioStreamEnd n'est envoyé dans cette configuration. Au lieu de cela, toute interruption du flux est signalée par un message activityEnd.

La prise en charge de cette fonctionnalité par le SDK sera disponible dans les semaines à venir.

Obtenir le nombre de jetons

Vous trouverez le nombre total de jetons consommés dans le champ usageMetadata du message du serveur renvoyé.

from google.genai import types

async with client.aio.live.connect(
    model='gemini-2.0-flash-live-001',
    config=types.LiveConnectConfig(
        response_modalities=['AUDIO'],
    ),
) as session:
    # Session connected
    while True:
        await session.send_client_content(
            turns=types.Content(role='user', parts=[types.Part(text='Hello world!')])
        )
        async for message in session.receive():
            # The server will periodically send messages that include
            # UsageMetadata.
            if message.usage_metadata:
                usage = message.usage_metadata
                print(
                    f'Used {usage.total_token_count} tokens in total. Response token'
                    ' breakdown:'
                )
            for detail in usage.response_tokens_details:
                match detail:
                  case types.ModalityTokenCount(modality=modality, token_count=count):
                      print(f'{modality}: {count}')

            # For the purposes of this example, placeholder input is continually fed
            # to the model. In non-sample code, the model inputs would come from
            # the user.
            if message.server_content and message.server_content.turn_complete:
                break

Configurer la reprise de session

Pour éviter la fin de la session lorsque le serveur réinitialise périodiquement la connexion WebSocket, configurez le champ sessionResumption dans la configuration de configuration.

Si vous transmettez cette configuration, le serveur envoie des messages SessionResumptionUpdate, qui peuvent être utilisés pour reprendre la session en transmettant le dernier jeton de reprise en tant que SessionResumptionConfig.handle de la connexion suivante.

from google.genai import types

print(f"Connecting to the service with handle {previous_session_handle}...")
async with client.aio.live.connect(
    model="gemini-2.0-flash-live-001",
    config=types.LiveConnectConfig(
        response_modalities=["AUDIO"],
        session_resumption=types.SessionResumptionConfig(
            # The handle of the session to resume is passed here,
            # or else None to start a new session.
            handle=previous_session_handle
        ),
    ),
) as session:
    # Session connected
    while True:
        await session.send_client_content(
            turns=types.Content(
                role="user", parts=[types.Part(text="Hello world!")]
            )
        )
        async for message in session.receive():
            # Periodically, the server will send update messages that may
            # contain a handle for the current state of the session.
            if message.session_resumption_update:
                update = message.session_resumption_update
                if update.resumable and update.new_handle:
                    # The handle should be retained and linked to the session.
                    return update.new_handle

            # For the purposes of this example, placeholder input is continually fed
            # to the model. In non-sample code, the model inputs would come from
            # the user.
            if message.server_content and message.server_content.turn_complete:
                break

Recevoir un message avant la déconnexion de la session

Le serveur envoie un message GoAway qui signale que la connexion actuelle sera bientôt interrompue. Ce message inclut timeLeft, qui indique le temps restant et vous permet de prendre d'autres mesures avant que la connexion ne soit arrêtée en tant que ABORTED.

Recevoir un message une fois la génération terminée

Le serveur envoie un message generationComplete qui indique que le modèle a terminé de générer la réponse.

Activer la compression de la fenêtre de contexte

Pour permettre des sessions plus longues et éviter l'arrêt brutal de la connexion, vous pouvez activer la compression de la fenêtre de contexte en définissant le champ contextWindowCompression dans la configuration de la session.

Dans ContextWindowCompressionConfig, vous pouvez configurer un mécanisme de fenêtre glissante et le nombre de jetons qui déclenche la compression.

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    context_window_compression=(
        # Configures compression with default parameters.
        types.ContextWindowCompressionConfig(
            sliding_window=types.SlidingWindow(),
        )
    ),
)

Modifier la résolution des contenus multimédias

Vous pouvez spécifier la résolution multimédia pour le contenu multimédia d'entrée en définissant le champ mediaResolution dans la configuration de la session:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)

Limites

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

Modalités de réponse

Vous ne pouvez définir qu'une seule modalité de réponse (TEXT ou AUDIO) par session dans la configuration de la session. Si vous essayez de définir les deux, un message d'erreur de configuration s'affiche. Cela signifie que vous pouvez configurer le modèle pour qu'il réponde par du texte ou de l'audio, mais pas les deux dans la même session.

Authentification client

L'API 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 Live.

Durée de la session

La durée de la session peut être illimitée en activant la compression de la session. Sans compression, les sessions audio uniquement sont limitées à 15 minutes, et les sessions audio et vidéo sont limitées à deux minutes. Le dépassement de ces limites sans compression met fin à la connexion.

Fenêtre de contexte

La fenêtre de contexte d'une session est limitée à 32 000 jetons.

Langues disponibles

L'API Live est compatible avec les langues suivantes:

Intégrations tierces

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

• Tous les jours
• Livekit