Ce guide complet présente les fonctionnalités et les configurations disponibles avec l'API Live. Consultez la page Premiers pas avec l'API Live pour obtenir une présentation et des exemples de code pour les cas d'utilisation courants.
Avant de commencer
- Familiarisez-vous avec les concepts de base : si vous ne l'avez pas encore fait, commencez par lire la page Premiers pas avec l'API Live . Vous y découvrirez les principes fondamentaux de l'API Live, son fonctionnement et les différentes approches d'implémentation.
- Essayez l'API Live dans AI Studio : il peut être utile d'essayer l'API Live dans Google AI Studio avant de commencer à développer. Pour utiliser l'API Live dans Google AI Studio, sélectionnez Stream.
Comparaison de modèles
Le tableau suivant récapitule les principales différences entre les modèles Aperçu en direct de Gemini 3.1 Flash et Aperçu en direct de Gemini 2.5 Flash :
| Fonctionnalité | Preview Gemini 3.1 Flash Live | Aperçu en direct de Gemini 2.5 Flash |
|---|---|---|
| Réflexion | Utilise thinkingLevel pour contrôler la profondeur de réflexion avec des paramètres tels que minimal, low, medium et high. La valeur par défaut est minimal pour optimiser la latence la plus faible. Consultez Niveaux de réflexion et budgets. |
Utilise thinkingBudget pour définir le nombre de jetons de réflexion. La réflexion dynamique est activée par défaut. Définissez thinkingBudget sur 0 pour désactiver la fonctionnalité. Consultez Niveaux de réflexion et budgets. |
| Recevoir une réponse | Un même événement serveur peut contenir plusieurs parties de contenu simultanément (par exemple, inlineData et une transcription). Assurez-vous que votre code traite toutes les parties de chaque événement pour ne manquer aucun contenu. |
Chaque événement de serveur ne contient qu'une seule partie de contenu. Les pièces sont fournies dans des événements distincts. |
| Contenu client | send_client_content n'est compatible qu'avec l'amorçage de l'historique du contexte initial (nécessite de définir initial_history_in_client_content dans la configuration de la session). Pour envoyer des mises à jour textuelles pendant la conversation, utilisez plutôt send_realtime_input. |
send_client_content est compatible tout au long de la conversation pour envoyer des mises à jour de contenu incrémentielles et établir le contexte. |
| Couverture des tours | La valeur par défaut est TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO. Le tour du modèle inclut l'activité audio détectée et toutes les images vidéo. |
La valeur par défaut est TURN_INCLUDES_ONLY_ACTIVITY. Le tour du modèle n'inclut que l'activité détectée. |
VAD personnalisée (activity_start/activity_end) |
Compatible. Désactivez la détection d'activité vocale automatique et envoyez manuellement les messages activityStart et activityEnd pour contrôler les limites de tour de parole. |
Compatible. Désactivez la détection d'activité vocale automatique et envoyez manuellement les messages activityStart et activityEnd pour contrôler les limites de tour de parole. |
| Configuration automatique de la VAD | Compatible. Configurez des paramètres tels que start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms et silence_duration_ms. |
Compatible. Configurez des paramètres tels que start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms et silence_duration_ms. |
Appel de fonction asynchrone (behavior: NON_BLOCKING) |
Non compatible L'appel de fonction est séquentiel uniquement. Le modèle ne commencera à répondre que lorsque vous aurez envoyé la réponse de l'outil. | Compatible. Définissez behavior sur NON_BLOCKING dans une déclaration de fonction pour permettre au modèle de continuer à interagir pendant l'exécution de la fonction. Contrôlez la façon dont le modèle gère les réponses avec le paramètre scheduling (INTERRUPT, WHEN_IDLE ou SILENT). |
| Audio proactif | Not supported | Compatible. Lorsqu'il est activé, le modèle peut décider de ne pas répondre de manière proactive si le contenu saisi n'est pas pertinent. Définissez proactive_audio sur true dans la configuration proactivity (nécessite v1beta). |
| Dialogue affectif | Not supported | Compatible. Le modèle adapte son style de réponse en fonction de l'expression et du ton de l'entrée. Définissez enable_affective_dialog sur true dans la configuration de session (nécessite v1beta). |
Pour migrer de Gemini 2.5 Flash Live vers Gemini 3.1 Flash Live, consultez le guide de migration.
Établir une connexion
L'exemple suivant montre comment créer une connexion avec une clé API :
Python
import asyncio
from google import genai
client = genai.Client()
model = "gemini-3.1-flash-live-preview"
config = {"response_modalities": ["AUDIO"]}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
print("Session started")
# Send content...
if __name__ == "__main__":
asyncio.run(main())
JavaScript
import { GoogleGenAI, Modality } from '@google/genai';
const ai = new GoogleGenAI({});
const model = 'gemini-3.1-flash-live-preview';
const config = { responseModalities: [Modality.AUDIO] };
async function main() {
const session = await ai.live.connect({
model: model,
callbacks: {
onopen: function () {
console.debug('Opened');
},
onmessage: function (message) {
console.debug(message);
},
onerror: function (e) {
console.debug('Error:', e.message);
},
onclose: function (e) {
console.debug('Close:', e.reason);
},
},
config: config,
});
console.debug("Session started");
// Send content...
session.close();
}
main();
Modalités d'interaction
Les sections suivantes fournissent des exemples et un contexte pour les différentes modalités d'entrée et de sortie disponibles dans l'API Live.
Envoi de l'audio
L'audio doit être envoyé sous forme de données PCM brutes (audio PCM 16 bits brut, 16 kHz, little-endian).
Python
# Assuming 'chunk' is your raw PCM audio bytes
await session.send_realtime_input(
audio=types.Blob(
data=chunk,
mime_type="audio/pcm;rate=16000"
)
)
JavaScript
// Assuming 'chunk' is a Buffer of raw PCM audio
session.sendRealtimeInput({
audio: {
data: chunk.toString('base64'),
mimeType: 'audio/pcm;rate=16000'
}
});
Formats audio
Les données audio de l'API Live sont toujours brutes, little-endian et PCM 16 bits. La sortie audio utilise toujours un taux d'échantillonnage de 24 kHz. L'entrée audio est nativement à 16 kHz, mais l'API Live rééchantillonnera si nécessaire, de sorte que n'importe quel taux d'échantillonnage peut être envoyé. Pour indiquer la fréquence d'échantillonnage de l'entrée audio, définissez le type MIME de chaque Blob contenant de l'audio sur une valeur telle que audio/pcm;rate=16000.
Réception de l'audio
Les réponses audio du modèle sont reçues sous forme de blocs de données.
Python
async for response in session.receive():
if response.server_content and response.server_content.model_turn:
for part in response.server_content.model_turn.parts:
if part.inline_data:
audio_data = part.inline_data.data
# Process or play the audio data
JavaScript
// Inside the onmessage callback
const content = response.serverContent;
if (content?.modelTurn?.parts) {
for (const part of content.modelTurn.parts) {
if (part.inlineData) {
const audioData = part.inlineData.data;
// Process or play audioData (base64 encoded string)
}
}
}
Envoi d'un SMS…
Le texte peut être envoyé à l'aide de send_realtime_input (Python) ou sendRealtimeInput (JavaScript).
Python
await session.send_realtime_input(text="Hello, how are you?")
JavaScript
session.sendRealtimeInput({
text: 'Hello, how are you?'
});
Envoi de la vidéo…
Les images vidéo sont envoyées individuellement (par exemple, au format JPEG ou PNG) à une fréquence d'images spécifique (1 image par seconde maximum).
Python
# Assuming 'frame' is your JPEG-encoded image bytes
await session.send_realtime_input(
video=types.Blob(
data=frame,
mime_type="image/jpeg"
)
)
JavaScript
// Assuming 'frame' is a Buffer of JPEG-encoded image data
session.sendRealtimeInput({
video: {
data: frame.toString('base64'),
mimeType: 'image/jpeg'
}
});
Mises à jour incrémentielles du contenu
Utilisez des mises à jour incrémentielles pour envoyer une entrée textuelle, ou établir ou restaurer le contexte de la session. Pour les contextes courts, vous pouvez envoyer des interactions au fur et à mesure 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)
JavaScript
let inputTurns = [
{ "role": "user", "parts": [{ "text": "What is the capital of France?" }] },
{ "role": "model", "parts": [{ "text": "Paris" }] },
]
session.sendClientContent({ turns: inputTurns, turnComplete: false })
inputTurns = [{ "role": "user", "parts": [{ "text": "What is the capital of Germany?" }] }]
session.sendClientContent({ turns: inputTurns, turnComplete: true })
Pour les contextes plus longs, il est recommandé de fournir un seul résumé des messages afin de libérer la fenêtre de contexte pour les interactions ultérieures. Consultez la section Reprise de session pour découvrir une autre méthode de chargement du contexte de session.
Transcriptions audio
En plus de la réponse du modèle, vous pouvez également recevoir des transcriptions de la sortie audio et de l'entrée audio.
Pour activer la transcription de la sortie audio du modèle, envoyez output_audio_transcription dans la configuration. La langue de transcription est déduite de la réponse du modèle.
Python
import asyncio
from google import genai
from google.genai import types
client = genai.Client()
model = "gemini-3.1-flash-live-preview"
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())
JavaScript
import { GoogleGenAI, Modality } from '@google/genai';
const ai = new GoogleGenAI({});
const model = 'gemini-3.1-flash-live-preview';
const config = {
responseModalities: [Modality.AUDIO],
outputAudioTranscription: {}
};
async function live() {
const responseQueue = [];
async function waitMessage() {
let done = false;
let message = undefined;
while (!done) {
message = responseQueue.shift();
if (message) {
done = true;
} else {
await new Promise((resolve) => setTimeout(resolve, 100));
}
}
return message;
}
async function handleTurn() {
const turns = [];
let done = false;
while (!done) {
const message = await waitMessage();
turns.push(message);
if (message.serverContent && message.serverContent.turnComplete) {
done = true;
}
}
return turns;
}
const session = await ai.live.connect({
model: model,
callbacks: {
onopen: function () {
console.debug('Opened');
},
onmessage: function (message) {
responseQueue.push(message);
},
onerror: function (e) {
console.debug('Error:', e.message);
},
onclose: function (e) {
console.debug('Close:', e.reason);
},