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

Consultez le journal des modifications pour découvrir les dernières fonctionnalités de l'API Live.

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.

Pour utiliser toutes les fonctionnalités, assurez-vous d'installer la dernière version du SDK, par exemple : pip install -U google-genai.

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")
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

Les données audio de l'API Live sont toujours brutes, au format PCM 16 bits little-endian. La sortie audio utilise toujours un taux d'échantillonnage de 24 kHz. L'audio d'entrée est nativement de 16 kHz, mais l'API Live effectue un nouvel échantillonnage si nécessaire afin que n'importe quel taux d'échantillonnage puisse être envoyé. Pour transmettre le taux d'échantillonnage de l'audio d'entrée, définissez le type MIME de chaque Blob contenant de l'audio sur une valeur telle que audio/pcm;rate=16000.

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:

Python

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)

JSON

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

Python

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")
        )
    )
)

JSON

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

Changer de langue

L'API Live est compatible avec plusieurs langues.

Pour modifier la langue, définissez le code de langue 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(
        language_code="de-DE",
    )
)

Utiliser des outils

Vous pouvez définir des outils tels que l'appel de fonction, l'exécution de code et la recherche Google avec l'API Live.

Utiliser l'appel de fonction

Vous pouvez définir des déclarations de fonction dans la configuration de la session. Pour en savoir plus, consultez le tutoriel sur les appels de fonction.

Après avoir reçu des appels d'outil, le client doit répondre avec une liste d'objets FunctionResponse à l'aide de la méthode session.send_tool_response.

import asyncio
from google import genai
from google.genai import types

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

# Simple function definitions
turn_on_the_lights = {"name": "turn_on_the_lights"}
turn_off_the_lights = {"name": "turn_off_the_lights"}

tools = [{"function_declarations": [turn_on_the_lights, turn_off_the_lights]}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Turn on the lights please"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            elif chunk.tool_call:
                function_responses = []
                for fc in tool_call.function_calls:
                    function_response = types.FunctionResponse(
                        id=fc.id,
                        name=fc.name,
                        response={ "result": "ok" } # simple, hard-coded function response
                    )
                    function_responses.append(function_response)

                await session.send_tool_response(function_responses=function_responses)


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

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

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

Utiliser l'exécution de code

Vous pouvez définir l'exécution du code dans la configuration de la session. Pour en savoir plus, consultez le tutoriel sur l'exécution du code.

import asyncio
from google import genai
from google.genai import types

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

tools = [{'code_execution': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Compute the largest prime palindrome under 100000."
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                      if part.executable_code is not None:
                        print(part.executable_code.code)

                      if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

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

Vous pouvez activer l'ancrage avec la recherche Google dans la configuration de la session. Pour en savoir plus, consultez le tutoriel sur l'ancrage.

import asyncio
from google import genai
from google.genai import types

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

tools = [{'google_search': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "When did the last Brazil vs. Argentina soccer match happen?"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)

                # The model might generate and execute Python code to use Search
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                      if part.executable_code is not None:
                        print(part.executable_code.code)

                      if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

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

Combiner plusieurs outils

Vous pouvez combiner plusieurs outils dans l'API Live:

prompt = """
Hey, I need you to do three things for me.

1. Compute the largest prime palindrome under 100000.
2. Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024?
3. Turn on the lights

Thanks!
"""

tools = [
    {"google_search": {}},
    {"code_execution": {}},
    {"function_declarations": [turn_on_the_lights, turn_off_the_lights]},
]

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

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 True:
        # The generation was interrupted

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

Vous pouvez configurer ou désactiver la détection de l'activité vocale (VAD).

Utiliser la suppression automatique du silence

Par défaut, le modèle effectue automatiquement la 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.

# example audio file to try:
# URL = "https://storage.googleapis.com/generativeai-downloads/data/hello_are_you_there.pcm"
# !wget -q $URL -O sample.pcm
import asyncio
from pathlib import Path
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:
        audio_bytes = Path("sample.pcm").read_bytes()

        await session.send_realtime_input(
            audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
        )

        # if stream gets paused, send:
        # await session.send_realtime_input(audio_stream_end=True)

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

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

Avec send_realtime_input, l'API répond automatiquement à l'audio en fonction de la suppression du bruit de fond. Alors que send_client_content ajoute des messages au contexte du modèle dans l'ordre, send_realtime_input est optimisé pour la réactivité au détriment de l'ordonnancement déterministe.

Configurer la suppression automatique du bruit

Pour mieux contrôler l'activité de suppression de la voix, vous pouvez configurer les paramètres suivants. Pour en savoir plus, consultez la documentation de référence de l'API.

from google.genai import types

config = {
    "response_modalities": ["TEXT"],
    "realtime_input_config": {
        "automatic_activity_detection": {
            "disabled": False, # default
            "start_of_speech_sensitivity": types.StartSensitivity.START_SENSITIVITY_LOW,
            "end_of_speech_sensitivity": types.EndSensitivity.END_SENSITIVITY_LOW,
            "prefix_padding_ms": 20,
            "silence_duration_ms": 100,
        }
    }
}

Désactiver la suppression automatique du bruit

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.

config = {
    "response_modalities": ["TEXT"],
    "realtime_input_config": {"automatic_activity_detection": {"disabled": True}},
}

async with client.aio.live.connect(model=model, config=config) as session:
    # ...
    await session.send_realtime_input(activity_start=types.ActivityStart())
    await session.send_realtime_input(
        audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
    )
    await session.send_realtime_input(activity_end=types.ActivityEnd())
    # ...

Obtenir le nombre de jetons

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

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}")

Prolonger la durée de la session

La durée maximale de la session peut être étendue à illimitée avec deux mécanismes:

De plus, vous recevrez un message GoAway avant la fin de la session, ce qui vous permettra de prendre d'autres mesures.

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(),
        )
    ),
)

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.

import asyncio
from google import genai
from google.genai import types

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

async def main():
    print(f"Connecting to the service with handle {previous_session_handle}...")
    async with client.aio.live.connect(
        model=model,
        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:
        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

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

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.

async for response in session.receive():
    if response.go_away is not None:
        # The connection will soon be terminated
        print(response.go_away.time_left)

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.

async for response in session.receive():
    if response.server_content.generation_complete is True:
        # The generation is complete

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,
)

Recevoir des transcriptions audio

Vous pouvez activer la transcription de la sortie audio du modèle. La langue de la transcription est déduite de la réponse du modèle.

import asyncio
from google import genai
from google.genai import types

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

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

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        message = "Hello? Gemini are you there?"

        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for response in session.receive():
            if response.server_content.model_turn:
                print("Model turn:", response.server_content.model_turn)
            if response.server_content.output_transcription:
                print("Transcript:", response.server_content.output_transcription.text)


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

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.

En outre, vous pouvez configurer la reprise de session pour permettre au client de reprendre une session qui a été arrêtée.

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:

Langue Code BCP-47
Allemand (Allemagne) de-DE
Anglais (Australie) en-AU
Anglais (Royaume-Uni) en-GB
Anglais (Inde) en-IN
Anglais (États-Unis) en-US
Espagnol (États-Unis) es-US
Français (France) fr-FR
Hindi (Inde) hi-IN
Portugais (Brésil) pt-BR
Arabe (générique) ar-XA
Espagnol (Espagne) es-ES
Français (Canada) fr-CA
Indonésien (Indonésie) id-ID
Italien (Italie) it-IT
Japonais (Japon) ja-JP
Turc (Turquie) tr-TR
Vietnamien (Viêt Nam) vi-VN
Bengali (Inde) bn-IN
Gujarati (Inde) gu-IN
Kannada (Inde) kn-IN
Malayalam (Inde) ml-IN
Marathi (Inde) mr-IN
Tamoul (Inde) ta-IN
Télougou (Inde) te-IN
Néerlandais (Pays-Bas) nl-NL
Coréen (Corée du Sud) ko-KR
Chinois mandarin (Chine) cmn-CN
Polonais (Pologne) pl-PL
Russe (Russie) ru-RU
Thaï (Thaïlande) th-TH

Intégrations tierces

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