API Live

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

Spécifications

L'API Live présente les spécifications techniques suivantes :

  • Entrées : texte, audio et vidéo
  • Sorties : texte et audio (synthèse vocale)
  • Durée de session par défaut : 10 minutes
    • La durée de la session peut être prolongée par incréments de 10 minutes, si nécessaire.
  • Fenêtre de contexte : 32 000 jetons
  • Choix parmi huit voix pour les réponses
  • Prise en charge des réponses dans 31 langues

Utiliser l'API Live

Les sections suivantes fournissent des exemples d'utilisation des fonctionnalités de l'API Live.

Pour en savoir plus, consultez le guide de référence de l'API Live.

Envoyer et recevoir du texte

SDK Gen AI pour Python

    # Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
    # with appropriate values for your project.
    
    from google import genai
    from google.genai.types import (
        Content,
        LiveConnectConfig,
        Modality,
        Part,
    )
    
    client = genai.Client(
        vertexai=True,
        project=GOOGLE_CLOUD_PROJECT,
        location=GOOGLE_CLOUD_LOCATION
    )
    MODEL_ID = "gemini-2.0-flash-live-preview-04-09"
    
    async with client.aio.live.connect(
        model=MODEL_ID,
        config=LiveConnectConfig(response_modalities=[Modality.TEXT]),
    ) as session:
        text_input = "Hello? Gemini, are you there?"
        print("> ", text_input, "\n")
        await session.send_client_content(
            turns=Content(role="user", parts=[Part(text=text_input)])
        )
    
        response = []
    
        async for message in session.receive():
            if message.text:
                response.append(message.text)
    
        print("".join(response))
    # Example output:
    # >  Hello? Gemini, are you there?
    # Yes, I'm here. What would you like to talk about?
  

Envoyer du texte et recevoir de l'audio

SDK Gen AI pour Python

  import asyncio
  import numpy as np
  from IPython.display import Audio, Markdown, display
  from google import genai
  from google.genai.types import (
      Content,
      LiveConnectConfig,
      HttpOptions,
      Modality,
      Part,
      SpeechConfig,
      VoiceConfig,
      PrebuiltVoiceConfig,
  )

  client = genai.Client(
      vertexai=True,
      project=GOOGLE_CLOUD_PROJECT,
      location=GOOGLE_CLOUD_LOCATION,
  )

  voice_name = "Aoede"  # @param ["Aoede", "Puck", "Charon", "Kore", "Fenrir", "Leda", "Orus", "Zephyr"]

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

  async with client.aio.live.connect(
      model=MODEL_ID,
      config=config,
  ) as session:
      text_input = "Hello? Gemini are you there?"
      display(Markdown(f"**Input:** {text_input}"))

      await session.send_client_content(
          turns=Content(role="user", parts=[Part(text=text_input)]))

      audio_data = []
      async for message in session.receive():
          if (
              message.server_content.model_turn
              and message.server_content.model_turn.parts
          ):
              for part in message.server_content.model_turn.parts:
                  if part.inline_data:
                      audio_data.append(
                          np.frombuffer(part.inline_data.data, dtype=np.int16)
                      )

      if audio_data:
          display(Audio(np.concatenate(audio_data), rate=24000, autoplay=True))
      

Pour en savoir plus sur l'envoi de messages, consultez le guide de démarrage.

Envoyer de l'audio

Vous pouvez envoyer des fichiers audio et recevoir du texte en les convertissant au format PCM 16 bits, 16 kHz, mono. Cet exemple lit un fichier WAV et l'envoie au format approprié:

SDK Gen AI pour Python

# Test file: https://storage.googleapis.com/generativeai-downloads/data/16000.wav
# Install helpers for converting files: pip install librosa soundfile

import asyncio
import io
from pathlib import Path
from google import genai
from google.genai import types
import soundfile as sf
import librosa

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION
    )
model = "gemini-2.0-flash-live-preview-04-09"
config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:

        buffer = io.BytesIO()
        y, sr = librosa.load("sample.wav", sr=16000)
        sf.write(buffer, y, sr, format="RAW", subtype="PCM_16")
        buffer.seek(0)
        audio_bytes = buffer.read()

        # If already in correct format, you can use this:
        # audio_bytes = Path("sample.pcm").read_bytes()

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

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

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

Formats audio acceptés

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

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

Transcription audio

L'API Live peut transcrire à la fois l'audio d'entrée et de sortie :

SDK Gen AI pour Python

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

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
model = "gemini-2.0-flash-live-preview-04-09"

config = {
    "response_modalities": ["AUDIO"],
    "input_audio_transcription": {},
    "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.input_transcription:
                print("Input transcript:", response.server_content.input_transcription.text)
            if response.server_content.output_transcription:
                print("Output transcript:", response.server_content.output_transcription.text)


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

      

Modifier les paramètres de voix et de langue

L'API Live utilise Chirp 3 pour prendre en charge les réponses vocales synthétisées dans diverses voix et langues HD. Pour obtenir la liste complète et des exemples de la façon dont chaque voix sonne, consultez Chirp 3: voix HD.

Pour définir la langue et la voix de la réponse :

SDK Gen AI pour Python

config = LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=SpeechConfig(
        voice_config=VoiceConfig(
            prebuilt_voice_config=PrebuiltVoiceConfig(
                voice_name=voice_name,
            )
        ),
        language_code="en-US",
    ),
)
      

Console

  1. Ouvrez Vertex AI Studio > Flux en temps réel.
  2. Développez Sorties et sélectionnez une voix dans la liste déroulante Voix.
  3. Dans le même panneau, sélectionnez une langue dans la liste déroulante Langue.
  4. Cliquez sur Démarrer la session pour démarrer la session.

Pour obtenir les meilleurs résultats lorsque vous demandez au modèle de répondre dans une langue autre que l'anglais, incluez les éléments suivants dans vos instructions système :

RESPOND IN LANGUAGE. YOU MUST RESPOND UNMISTAKABLY IN LANGUAGE.

Avoir une conversation en streaming

Pour voir un exemple d'utilisation de l'API Live dans un format audio en streaming, exécutez cet exemple sur un ordinateur local avec accès au micro et aux haut-parleurs (plutôt qu'à l'aide d'un notebook Colab).

SDK Gen AI pour Python

Configurez une conversation avec l'API qui vous permet d'envoyer des requêtes textuelles et de recevoir des réponses audio :

"""
# Installation
# on linux
sudo apt-get install portaudio19-dev

# on mac
brew install portaudio

python3 -m venv env
source env/bin/activate
pip install google-genai
"""

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

CHUNK=4200
FORMAT=pyaudio.paInt16
CHANNELS=1
RECORD_SECONDS=5
MODEL = 'gemini-2.0-flash-live-preview-04-09'
INPUT_RATE=16000
OUTPUT_RATE=24000

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
config = {
    "response_modalities": ["AUDIO"],
    "input_audio_transcription": {},  # Configure input transcription
    "output_audio_transcription": {},  # Configure output transcription
}

async def main():
    print(MODEL)
    p = pyaudio.PyAudio()
    async with client.aio.live.connect(model=MODEL, config=config) as session: 
        #exit()
        async def send():
            stream = p.open(
                format=FORMAT, channels=CHANNELS, rate=INPUT_RATE, input=True, frames_per_buffer=CHUNK)
            while True:
                frame = stream.read(CHUNK)
                await session.send(input={"data": frame, "mime_type": "audio/pcm"})
                await asyncio.sleep(10**-12)
        async def receive():
            output_stream = p.open(
                format=FORMAT, channels=CHANNELS, rate=OUTPUT_RATE, output=True, frames_per_buffer=CHUNK)
            async for message in session.receive():
                if message.server_content.input_transcription:
                  print(message.server_content.model_dump(mode="json", exclude_none=True))
                if message.server_content.output_transcription:
                  print(message.server_content.model_dump(mode="json", exclude_none=True))
                if message.server_content.model_turn:
                    for part in message.server_content.model_turn.parts:
                        if part.inline_data.data:
                            audio_data=part.inline_data.data
                            output_stream.write(audio_data)
                            await asyncio.sleep(10**-12)
        send_task = asyncio.create_task(send())
        receive_task = asyncio.create_task(receive())
        await asyncio.gather(send_task, receive_task)

asyncio.run(main())

      

Console

  1. Ouvrez Vertex AI Studio > Flux en temps réel.
  2. Cliquez sur Démarrer la session pour lancer la session de conversation.

Pour mettre fin à la session, cliquez sur Arrêter la session.

Durée des sessions

La durée maximale par défaut d'une session de conversation est de 10 minutes. Une notification go_away (BidiGenerateContentServerMessage.go_away) est renvoyée au client 60 secondes avant la fin de la session.

Lorsque vous utilisez l'API, vous pouvez prolonger la durée de votre session par incréments de 10 minutes. Vous pouvez prolonger une session autant de fois que vous le souhaitez. Pour obtenir un exemple montrant comment prolonger la durée de la session, consultez Activer et désactiver la reprise de session. Cette fonctionnalité n'est disponible que dans l'API, et non dans Vertex AI Studio.

Fenêtre de contexte

La longueur de contexte maximale d'une session dans l'API Live est de 32 768 jetons par défaut. Ils sont alloués pour stocker les données en temps réel diffusées à un débit de 25 jetons par seconde (TPS) pour l'audio et de 258 TPS pour la vidéo, ainsi que d'autres contenus, y compris des entrées textuelles, des sorties de modèle, etc.

Si la fenêtre de contexte dépasse la longueur de contexte maximale, les contextes des tours les plus anciens de la fenêtre de contexte seront tronqués. Cela permet d'assurer que la taille globale de la fenêtre de contexte reste inférieure à la limite.

La longueur de contexte par défaut de la session et la longueur de contexte cible après la troncation peuvent être configurées à l'aide des champs respectifs context_window_compression.trigger_tokens et context_window_compression.sliding_window.target_tokens du message de configuration.

Sessions simultanées

Par défaut, vous pouvez avoir jusqu'à 10 sessions simultanées par projet.

Mettre à jour les instructions système en cours de session

L'API Live vous permet de mettre à jour les instructions système au milieu d'une session active. Cela vous permet d'adapter les réponses du modèle en cours de session, par exemple en changeant la langue dans laquelle le modèle répond ou en modifiant le ton de la réponse du modèle.

Pour modifier ce paramètre, vous pouvez envoyer du contenu textuel avec le rôle system. L'instruction système mise à jour restera en vigueur pendant le reste de la session.

SDK Gen AI pour Python

session.send_client_content(
      turns=types.Content(
          role="system", parts=[types.Part(text="new system instruction")]
      ),
      turn_complete=False
  )
      

Modifier les paramètres de détection de l'activité vocale

Par défaut, le modèle détecte automatiquement l'activité vocale (VAD) sur un flux d'entrée audio continu. La VAD peut être configurée avec le champ realtimeInputConfig.automaticActivityDetection du message 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 l'audio mis en cache. Le client peut reprendre l'envoi des données audio à tout moment.

Vous pouvez également désactiver la VAD automatique 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 les messages activityStart et activityEnd au moment opportun. Un audioStreamEnd n'est pas envoyé dans cette configuration. Au lieu de cela, toute interruption du flux est marquée par un message activityEnd.

Activer et désactiver la reprise de session

Cette fonctionnalité est désactivée par défaut. L'utilisateur doit l'activer chaque fois qu'il appelle l'API en spécifiant le champ dans la requête d'API. La confidentialité au niveau du projet est appliquée aux données mises en cache. L'activation de la reprise de session permet à l'utilisateur de se reconnecter à une session précédente dans un délai de 24 heures en stockant les données mises en cache, y compris les données de requête textuelle, vidéo et audio, ainsi que les sorties du modèle, pendant un maximum de 24 heures. Si vous ne souhaitez pas conserver de données, ne l'activez pas.

Pour activer la fonctionnalité de reprise de session, définissez le champ session_resumption du message LiveConnectConfig. Si cette option est activée, le serveur prend régulièrement un instantané des contextes de la session en cours mise en cache et le stocke dans la mémoire de stockage interne. Lorsqu'un instantané est pris, un resumption_update est renvoyé avec l'ID de handle que vous pouvez enregistrer et utiliser ultérieurement pour reprendre la session à partir de l'instantané.

Voici un exemple d'activation de la fonctionnalité de reprise de session et de collecte des informations sur l'ID de handle :

SDK Gen AI pour Python

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

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION
)
model = "gemini-2.0-flash-live-preview-04-09"

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

Si vous souhaitez que la session reprenne de façon fluide, vous pouvez activer le mode transparent :

SDK Gen AI pour Python

types.LiveConnectConfig(
            response_modalities=["AUDIO"],
            session_resumption=types.SessionResumptionConfig(
                transparent=True,
    ),
)
      

Une fois le mode transparent activé, l'index du message client correspondant à l'instantané de contexte est renvoyé explicitement. Cela permet d'identifier le message client que vous devez renvoyer lorsque vous reprenez la session à partir du handle de reprise.

Utiliser l'appel de fonction

Vous pouvez utiliser l'appel de fonction pour créer une description de fonction, puis transmettre cette description au modèle dans une requête. La réponse du modèle inclut le nom d'une fonction correspondant à la description et les arguments avec lesquels l'appeler.

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

SDK Gen AI pour Python

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

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
model = "gemini-2.0-flash-live-preview-04-09"

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

Utiliser l'exécution de code

Vous pouvez utiliser l'exécution de code avec l'API Live pour générer et exécuter directement du code Python.

SDK Gen AI pour Python

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


client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
model = "gemini-2.0-flash-live-preview-04-09"

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 utiliser l'ancrage avec la recherche Google avec l'API Live à l'aide de google_search :

SDK Gen AI pour Python

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

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
model = "gemini-2.0-flash-live-preview-04-09"


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

Audio natif

Gemini 2.5 Flash avec l'API Live propose des fonctionnalités audio natives. En plus des fonctionnalités standards de l'API Live, l'audio natif inclut les éléments suivants:

  • Qualité et adaptabilité vocales améliorées:l'audio natif de l'API Live offre des interactions vocales plus riches et plus naturelles avec 30 voix HD dans 24 langues.
  • Présentation de l'audio proactif:lorsque l'audio proactif est activé, le modèle ne répond que lorsqu'il est pertinent. Le modèle ne génère des transcriptions textuelles et des réponses audio de manière proactive que pour les requêtes adressées à l'appareil, et ne répond pas aux requêtes non adressées à l'appareil.
  • Présentation du dialogue affectif:les modèles utilisant l'audio natif de l'API Live peuvent comprendre et répondre de manière appropriée aux expressions émotionnelles des utilisateurs pour des conversations plus nuancées.

Utiliser l'audio proactif

Pour utiliser l'audio proactif, configurez le champ proactivity dans le message de configuration et définissez proactive_audio sur true:

SDK Gen AI pour Python

config = LiveConnectConfig(
    response_modalities=["AUDIO"],
    proactivity=ProactivityConfig(proactive_audio=True),
)
  

Utiliser le dialogue affectif

Pour utiliser la boîte de dialogue affective, définissez enable_affective_dialog sur true dans le message de configuration:

SDK Gen AI pour Python

config = LiveConnectConfig(
    response_modalities=["AUDIO"],
    enable_affective_dialog=True,
)
  

Limites

Consultez la section Limites de l'API Live de notre documentation de référence pour obtenir la liste complète des limites actuelles de l'API Live.

La version preview privée de Gemini 2.5 Flash avec l'audio natif de l'API Live est limitée à trois sessions simultanées.

Tarifs

Pour en savoir plus, consultez la page Tarifs.

En savoir plus

Pour en savoir plus sur l'API Live, par exemple pour obtenir la documentation de référence de l'API WebSocket, consultez la documentation de l'API Gemini.