Skill de développement Gemini Live API

Aperçu

La Live API permet des interactions voix et vidéo en temps réel à faible latence avec Gemini sur WebSockets. Elle traite des flux continus d'audio, vidéo ou texte pour offrir des réponses parlées immédiates et naturelles.

Capacités clés :

• Streaming audio bidirectionnel — conversations en temps réel micro-vers-haut-parleur
• Streaming vidéo — envoi de frames caméra/écran aux côtés de l'audio
• Entrée/sortie texte — envoi et réception de texte dans une session en direct
• Transcriptions audio — obtenez des transcriptions texte de l'audio d'entrée et de sortie
• Détection d'activité vocale (VAD) — gestion automatique des interruptions
• Audio natif — thinking (avec thinkingLevel configurable)
• Function calling — utilisation synchrone d'outils
• Grounding Google Search — ancrage des réponses dans les résultats de recherche en temps réel
• Gestion de session — compression de contexte, reprise de session, signaux GoAway
• Tokens éphémères — authentification sécurisée côté client

[!NOTE] La Live API supporte actuellement uniquement WebSockets. Pour le support WebRTC ou une intégration simplifiée, utilisez une intégration partenaire.

Modèles

• gemini-3.1-flash-live-preview — Optimisé pour le dialogue en temps réel à faible latence. Sortie audio native, thinking (via thinkingLevel). Fenêtre de contexte 128k. Ceci est le modèle recommandé pour tous les cas d'usage Live API.

[!WARNING] Les modèles Live API suivants sont dépréciés et seront arrêtés. Migrez vers gemini-3.1-flash-live-preview.

• gemini-2.5-flash-native-audio-preview-12-2025 — Migrez vers gemini-3.1-flash-live-preview.
• gemini-live-2.5-flash-preview — Publié 17 juin 2025. Arrêt : 9 décembre 2025.
• gemini-2.0-flash-live-001 — Publié 9 avril 2025. Arrêt : 9 décembre 2025.

SDKs

• Python: google-genai — pip install google-genai
• JavaScript/TypeScript: @google/genai — npm install @google/genai

[!WARNING] Les SDKs legacy google-generativeai (Python) et @google/generative-ai (JS) sont dépréciés. Utilisez les nouveaux SDKs ci-dessus.

Intégrations partenaires

Pour simplifier le développement d'applications audio/vidéo en temps réel, utilisez une intégration tierce supportant la Gemini Live API sur WebRTC ou WebSockets :

• LiveKit — Utilisez Gemini Live API avec LiveKit Agents.
• Pipecat by Daily — Créez un chatbot IA en temps réel utilisant Gemini Live et Pipecat.
• Fishjam by Software Mansion — Créez des applications de streaming vidéo et audio en direct avec Fishjam.
• Vision Agents by Stream — Construisez des applications IA voix et vidéo en temps réel avec Vision Agents.
• Voximplant — Connectez les appels entrants et sortants à Live API avec Voximplant.
• Firebase AI SDK — Commencez avec Gemini Live API en utilisant Firebase AI Logic.

Formats audio

• Entrée : Raw PCM, little-endian, 16-bit, mono. 16kHz natif (rééchantillonnera les autres). Type MIME : audio/pcm;rate=16000
• Sortie : Raw PCM, little-endian, 16-bit, mono. Fréquence d'échantillonnage 24kHz.

[!IMPORTANT] Utilisez send_realtime_input / sendRealtimeInput pour toute entrée utilisateur en temps réel (audio, vidéo, et texte). send_client_content / sendClientContent est uniquement supporté pour l'amorçage de l'historique de contexte initial (nécessite de définir initial_history_in_client_content dans history_config). Ne l'utilisez pas pour envoyer de nouveaux messages utilisateur pendant la conversation.

[!WARNING] Ne pas utiliser media dans sendRealtimeInput. Utilisez les clés spécifiques : audio pour les données audio, video pour les images/frames vidéo, et text pour l'entrée texte.

Démarrage rapide

Authentification

Python

from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

JavaScript

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });

Connexion à la Live API

Python

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=[types.Modality.AUDIO],
    system_instruction=types.Content(
        parts=[types.Part(text="You are a helpful assistant.")]
    )
)

async with client.aio.live.connect(model="gemini-3.1-flash-live-preview", config=config) as session:
    pass  # Session is active

JavaScript

const session = await ai.live.connect({
  model: 'gemini-3.1-flash-live-preview',
  config: {
    responseModalities: ['audio'],
    systemInstruction: { parts: [{ text: 'You are a helpful assistant.' }] }
  },
  callbacks: {
    onopen: () => console.log('Connected'),
    onmessage: (response) => console.log('Message:', response),
    onerror: (error) => console.error('Error:', error),
    onclose: () => console.log('Closed')
  }
});

Envoi de texte

Python

await session.send_realtime_input(text="Hello, how are you?")

JavaScript

session.sendRealtimeInput({ text: 'Hello, how are you?' });

Envoi d'audio

Python

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

JavaScript

session.sendRealtimeInput({
  audio: { data: chunk.toString('base64'), mimeType: 'audio/pcm;rate=16000' }
});

Envoi de vidéo

Python

# frame: raw JPEG-encoded bytes
await session.send_realtime_input(
    video=types.Blob(data=frame, mime_type="image/jpeg")
)

JavaScript

session.sendRealtimeInput({
  video: { data: frame.toString('base64'), mimeType: 'image/jpeg' }
});

Réception d'audio et de texte

[!IMPORTANT] Un événement serveur unique peut contenir plusieurs parties de contenu simultanément (par ex. chunks audio et transcription). Traitez toujours toutes les parties dans chaque événement pour éviter de manquer du contenu.

Python

async for response in session.receive():
    content = response.server_content
    if content:
        # Audio — traiter TOUTES les parties dans chaque événement
        if content.model_turn:
            for part in content.model_turn.parts:
                if part.inline_data:
                    audio_data = part.inline_data.data
        # Transcription
        if content.input_transcription:
            print(f"User: {content.input_transcription.text}")
        if content.output_transcription:
            print(f"Gemini: {content.output_transcription.text}")
        # Interruption
        if content.interrupted is True:
            pass  # Stop playback, clear audio queue

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; // Base64 encoded
    }
  }
}
if (content?.inputTranscription) console.log('User:', content.inputTranscription.text);
if (content?.outputTranscription) console.log('Gemini:', content.outputTranscription.text);
if (content?.interrupted) { /* Stop playback, clear audio queue */ }

Limitations

• Modalité de réponse — Uniquement TEXT ou AUDIO par session, pas les deux
• Session audio uniquement — 15 min sans compression
• Session audio+vidéo — 2 min sans compression
• Durée de vie de la connexion — ~10 min (utilisez la reprise de session)
• Fenêtre de contexte — 128k tokens (audio natif) / 32k tokens (standard)
• Function calling asynchrone — Pas encore supporté ; le function calling est synchrone uniquement. Le modèle ne commencera pas à répondre tant que vous n'aurez pas envoyé la réponse de l'outil.
• Audio proactif — Pas encore supporté dans Gemini 3.1 Flash Live. Supprimez toute configuration pour cette fonctionnalité.
• Dialogue affectif — Pas encore supporté dans Gemini 3.1 Flash Live. Supprimez toute configuration pour cette fonctionnalité.
• Exécution de code — Non supportée
• Contexte URL — Non supporté

Migration depuis Gemini 2.5 Flash Live

Lors de la migration de gemini-2.5-flash-native-audio-preview-12-2025 vers gemini-3.1-flash-live-preview :

1. Chaîne modèle — Mettez à jour de gemini-2.5-flash-native-audio-preview-12-2025 vers gemini-3.1-flash-live-preview.
2. Configuration thinking — Utilisez thinkingLevel (minimal, low, medium, high) à la place de thinkingBudget. Par défaut minimal pour la latence la plus basse.
3. Événements serveur — Un événement unique peut contenir plusieurs parties de contenu simultanément (audio + transcription). Traitez toutes les parties dans chaque événement.
4. Client content — send_client_content est uniquement pour l'amorçage de l'historique de contexte initial (définissez initial_history_in_client_content dans history_config). Utilisez send_realtime_input pour le texte pendant la conversation.
5. Couverture de tour — Par défaut TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO au lieu de TURN_INCLUDES_ONLY_ACTIVITY. Si vous envoyez des frames vidéo constants, envisagez d'envoyer uniquement lors de l'activité audio pour réduire les coûts.
6. Function calling asynchrone — Pas encore supporté. Le function calling est synchrone uniquement.
7. Audio proactif & dialogue affectif — Pas encore supportés. Supprimez toute configuration pour ces fonctionnalités.

Bonnes pratiques

1. Utilisez des écouteurs lors du test audio micro pour éviter l'écho/l'auto-interruption
2. Activez la compression de fenêtre de contexte pour les sessions dépassant 15 minutes
3. Implémentez la reprise de session pour gérer gracieusement les réinitialisations de connexion
4. Utilisez des tokens éphémères pour les déploiements côté client — ne jamais exposer les clés API dans les navigateurs
5. Utilisez send_realtime_input pour toute entrée utilisateur en temps réel (audio, vidéo, texte). Réservez send_client_content uniquement pour l'amorçage de l'historique de contexte initial
6. Envoyez audioStreamEnd quand le micro est mis en pause pour vider l'audio en cache
7. Videz les files d'attente de lecture audio lors des signaux d'interruption
8. Traitez toutes les parties dans chaque événement serveur — les événements peuvent contenir plusieurs parties de contenu

Recherche de documentation

Quand MCP est installé (Préféré)

Si l'outil search_docs (depuis le serveur MCP Google) est disponible, utilisez-le comme unique source de documentation :

1. Appelez search_docs avec votre requête
2. Lisez la documentation retournée
3. Faites confiance aux résultats MCP comme source de vérité pour les détails API — ils sont toujours à jour.

[!IMPORTANT] Quand les outils MCP sont présents, ne cherchez jamais manuellement des URLs. MCP fournit une documentation indexée à jour qui est plus précise et plus efficace en tokens que le fetching d'URL.

Quand MCP n'est PAS installé (Fallback uniquement)

Si aucun outil de documentation MCP n'est disponible, récupérez depuis l'index de documentation officiel :

URL llms.txt : https://ai.google.dev/gemini-api/docs/llms.txt

Cet index contient des liens vers toutes les pages de documentation au format .md.txt. Utilisez les outils web fetch pour :

1. Récupérer llms.txt pour découvrir les pages de documentation disponibles
2. Récupérer des pages spécifiques (par ex. https://ai.google.dev/gemini-api/docs/live-session.md.txt)

Pages de documentation clés

[!IMPORTANT] Ce ne sont pas toutes les pages de documentation. Utilisez l'index llms.txt pour découvrir les pages de documentation disponibles

• Vue d'ensemble Live API — premiers pas, utilisation brute WebSocket
• Guide des capacités Live API — config voix, config transcription, audio natif (thinking), configuration VAD, résolution des médias
• Utilisation des outils Live API — function calling (sync et async), grounding Google Search
• Gestion de session — compression de fenêtre de contexte, reprise de session, signaux GoAway
• Tokens éphémères — authentification sécurisée côté client pour navigateur/mobile
• Référence API WebSockets — détails du protocole WebSocket brut

Langues supportées

La Live API supporte 70 langues dont : anglais, espagnol, français, allemand, italien, portugais, chinois, japonais, coréen, hindi, arabe, russe, et bien d'autres. Les modèles audio natifs détectent et basculent automatiquement les langues.