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())
Utiliser l'ancrage avec la recherche Google
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: