Guide du développeur pour Gemini 3.8 Live

Gemini 3.8 Live est un modèle conversationnel en temps réel conçu pour les interactions vocales et vidéo bidirectionnelles à faible latence, ainsi que pour la synthèse d'avatars en direct en face à face. Conçu pour les workflows conversationnels continus, 3.8 Live fournit un dialogue affectif activé par défaut, un filtrage audio proactif, des outils de blocage à annulation automatique et une commutation multilingue dynamique.

Ce document traite des sujets suivants :

• Comment 3.8 Live s'intègre à la famille de modèles Gemini
• Principales fonctionnalités de 3.8 Live
• Intégration au SDK Google Gen AI
• Règles et conventions d'API requises
• Migration depuis des modèles d'API Gemini Live antérieurs

Rôle dans la famille Gemini

3.8 Live est conçu pour les interactions de streaming en temps réel. Il fonctionne sur des WebSockets bidirectionnels, traite la parole, les flux de caméras en direct et les diffusions d'écran avec une latence inférieure à une seconde, tout en générant un son à 24 kHz et des avatars vidéo synchronisés à 24 FPS.

Spécifications et comparaisons des modèles

Le tableau suivant compare les spécifications de 3.8 Live et des modèles d'API Gemini Live antérieurs :

Quand utiliser Gemini 3.8 Live

Utilisez 3.8 Live dans les cas suivants :

• Vous avez besoin d'une faible latence conversationnelle, d'une prise de parole naturelle et d'une récupération rapide lorsque l'utilisateur interrompt (interruption).
• Votre application appelle des outils externes et nécessite une exécution non bloquante afin que la sortie audio se poursuive pendant que les systèmes backend traitent les requêtes.
• Vous souhaitez afficher des avatars numériques parlants avec une animation faciale et une synchronisation labiale à 24 FPS sans pipelines de rendu externes.
• Vos utilisateurs conversent dans plusieurs langues, ce qui nécessite une détection et une commutation de langue en cours de flux entre les langues acceptées.
• Vous avez besoin d'un biais de vocabulaire spécifique à un domaine pour la terminologie technique, les SKU ou les noms de marque.

Pour obtenir les spécifications complètes et les limites de quota, consultez la page du modèle 3.8 Live.

Principales fonctionnalités de Gemini 3.8 Live

3.8 Live introduit les fonctionnalités suivantes :

• Synthèse vidéo d'avatars live à 24 FPS : 3.8 Live génère des flux vidéo MP4 synchronisés à 24 FPS (response_modalities=["VIDEO"]) directement à partir de la sortie du modèle. Les expressions faciales et les mouvements des lèvres générés s'alignent sur la parole synthétisée en temps réel.

  Vous pouvez utiliser des avatars prédéfinis ou fournir des images de référence personnalisées pour créer des concierges numériques, des agents du service client, des tuteurs virtuels ou des personnages interactifs. Pour en savoir plus sur la configuration, consultez Configurer des avatars en direct.

• Dialogue affectif et audio proactif activés par défaut :

  • Dialogue affectif : activé par défaut dans 3.8 Live. Le modèle traite la prosodie acoustique, les signaux vocaux, les pauses et l'inflexion de la parole dans l'entrée audio de l'utilisateur pour ajuster le ton de la voix et le rythme de la conversation.
  • Audio proactif : activé par défaut dans 3.8 Live. Le modèle filtre le bruit ambiant et la parole en arrière-plan, et ne génère des réponses audio que lorsque l'utilisateur s'adresse à lui.

• Appel de fonction bloquant asynchrone et à annulation automatique: 3.8 Live fournit des comportements d'appel d'outils conçus pour la parole en temps réel :

  • Exécution asynchrone non bloquante : lorsque le modèle génère un appel d'outil, la session audio reste active afin que l'agent puisse diffuser des confirmations conversationnelles ("Laissez-moi afficher les détails de votre compte...") et gérer les entrées de suivi pendant que votre application cliente appelle les API backend.
  • Appels bloquants à annulation automatique (behavior="BLOCKING") : lorsqu'une déclaration de fonction définit behavior="BLOCKING", la génération s'interrompt jusqu'à ce que la réponse de l'outil arrive. Si une nouvelle entrée utilisateur arrive pendant l'exécution de l'appel bloquant, le serveur de l'API Gemini Live annule l'appel en attente.
  • Gestion des interruptions polies : dans les modèles précédents, le renvoi d'une réponse d'outil avec scheduling="INTERRUPT" pendant que l'utilisateur parlait chevauchait l'audio de l'utilisateur. Dans 3.8 Live, le serveur rétrograde la planification à WHEN_IDLE lorsque la parole de l'utilisateur est active et lit la réponse une fois que l'utilisateur a fini de parler.

• Commutation multilingue dynamique et vocabulaire personnalisé:

  • Compatibilité multilingue : détecte et bascule entre les langues acceptées en cours de session sans redémarrer ni reconfigurer la connexion.
  • Biais de vocabulaire personnalisé : accepte les mots clés spécifiques à un domaine, les noms propres, les termes médicaux et les codes produit dans AudioTranscriptionConfig (via input_audio_transcription) à l'aide de custom_vocabulary pour améliorer la précision de la transcription.

• Ancrage visuel multimodal avec contrôle media_resolution: accepte les flux vidéo en temps réel (frames JPEG 1 FPS, résolution recommandée 768x768) et vous permet de configurer media_resolution (MEDIA_RESOLUTION_LOW, MEDIA_RESOLUTION_MEDIUM, MEDIA_RESOLUTION_HIGH) pour équilibrer l'utilisation des jetons par frame et les détails visuels.

Guide de démarrage rapide

Avant de commencer, authentifiez-vous à Cloud de Confiance by S3NS l'aide des identifiants par défaut de l'application (ADC).

Dans l'exemple de code suivant, remplacez PROJECT_ID par l'ID de votre Cloud de Confiance projet.

Installer le SDK

Installez ou mettez à jour le SDK Google Gen AI et les dépendances audio :

pip install --upgrade google-genai websockets numpy

Démarrer une session bidirectionnelle avec un appel d'outil asynchrone

L'exemple suivant établit une session en temps réel avec gemini-3.8-live, configure un biais de vocabulaire personnalisé et exécute des appels de fonction asynchrones non bloquants :

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

PROJECT_ID = "PROJECT_ID"
LOCATION = "us-central1"
MODEL_ID = "gemini-3.8-live"

# Initialize the Gen AI client for enterprise.
client = genai.Client(enterprise=True, project=PROJECT_ID, location=LOCATION)

# Define a tool for asynchronous execution.
order_lookup_tool = types.FunctionDeclaration(
    name="lookup_order_status",
    description="Fetches real-time shipping status for a customer order ID.",
    parameters=types.Schema(
        type="OBJECT",
        properties={
            "order_id": types.Schema(
                type="STRING",
                description="The order ID, for example, ORD-8472",
            ),
        },
        required=["order_id"],
    ),
)

# Configure the live connection.
config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    system_instruction=types.Content(
        parts=[
            types.Part.from_text(
                text=(
                    "You are an enterprise concierge. When you call a tool, "
                    "briefly acknowledge the request and tell the user what you're doing. "
                    "If a tool returns no results, inform the user before trying again. "
                    "Never issue more than two consecutive tool calls without speaking."
                )
            )
        ]
    ),
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Aoede")
        ),
    ),
    input_audio_transcription=types.AudioTranscriptionConfig(
        custom_vocabulary=["ORD-8472", "Gemini Live", "Express Shipping"]
    ),
    output_audio_transcription=types.AudioTranscriptionConfig(),
    tools=[types.Tool(function_declarations=[order_lookup_tool])],
)

async def handle_tool_call(session, function_call):
    """Executes backend calls asynchronously without blocking incoming audio."""
    order_id = function_call.args.get("order_id", "")
    await asyncio.sleep(2.0)  # Simulate backend API latency.

    if not order_id.startswith("ORD-"):
        result = {
            "status": "invalid_argument",
            "retryable": False,
            "message": f"Order ID '{order_id}' is invalid. Ask the user to verify.",
        }
    else:
        result = {
            "status": "ok",
            "retryable": False,
            "order_id": order_id,
            "shipping_status": "Out for delivery by 4:00 PM",
        }

    # Send tool response matching the call ID.
    await session.send_tool_response(
        function_responses=[
            types.FunctionResponse(
                id=function_call.id,
                name=function_call.name,
                response=result,
            )
        ]
    )

async def main():
    async with client.aio.live.connect(model=MODEL_ID, config=config) as session:
        print(f"Connected to {MODEL_ID}")

        # Send initial text or stream 16 kHz PCM audio chunks.
        await session.send_realtime_input(
            text="Hi! Can you check the status of order ORD-8472?"
        )

        async for message in session.receive():
            # Handle asynchronous tool calls.
            if message.tool_call:
                for call in message.tool_call.function_calls:
                    asyncio.create_task(handle_tool_call(session, call))

            # Process audio output chunks and transcriptions.
            if message.server_content:
                if (
                    message.server_content.output_transcription
                    and message.server_content.output_transcription.text
                ):
                    print(
                        f"Agent: {message.server_content.output_transcription.text}",
                        end="",
                        flush=True,
                    )

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

Règles et conventions d'API requises

Lorsque vous créez avec 3.8 Live, suivez ces conventions d'API :

• Réponses de fonction informatives : ne renvoyez pas de dictionnaire vide ({}) ni None à partir d'un gestionnaire d'outils. Lorsqu'un outil renvoie une erreur ou une charge utile vide, 3.8 Live peut générer des appels de fonction répétés avec des arguments modifiés, sauf si la réponse inclut des champs d'état. Renvoie des champs structurés dans chaque réponse d'outil :
  • status : chaîne d'état lisible par machine, telle que "ok", "no_results" ou "invalid_argument".
  • retryable: défini sur false lorsque la répétition de l'appel renvoie le même résultat.
  • message ou guidance : texte spécifiant l'état à signaler à l'utilisateur.
• Limites de nouvelles tentatives au niveau de l'invite : incluez une limite de nouvelles tentatives dans votre system_instruction. Par exemple : "Si un appel d'outil ne renvoie aucun résultat, informez l'utilisateur au lieu de rechercher de manière répétée avec des variations de paramètres. N'exécutez jamais plus de deux appels d'outils consécutifs sans parler à l'utilisateur."
• Correspondance stricte FunctionResponse:
  • Chaque tour FunctionResponse doit fournir l'élément id exact du FunctionCall précédent.
  • Transmettez directement les objets de réponse dans FunctionResponse.response.
• Formats audio en streaming:
  • Audio d'entrée : PCM mono 16 kHz, 16 bits, little-endian (audio/pcm;rate=16000), diffusé en flux continu par blocs de 20 à 100 ms.
  • Audio de sortie : PCM mono 24 kHz.
• Paramètres hérités supprimés : ne transmettez pas enable_affective_dialog ou proactivity dans votre configuration. Ces fonctionnalités sont activées par défaut dans 3.8 Live.
• Historique des conversations de départ : si vous amorcez l'historique multi-tours à l'aide de send_client_content, attendez que l'application cliente reçoive le setup_complete frame de serveur et configurez HistoryConfig(initial_history_in_client_content=True).

Migrer vers Gemini 3.8 Live

Pour en savoir plus sur la migration de gemini-live-2.5-flash-native-audio vers gemini-3.8-live, consultez Migrer de Gemini 2.5 Flash Live API Native Audio vers Gemini 3.8 Live.

Checklist du développeur

Vérifiez les éléments suivants avant de déployer votre application :

Autres ressources

Pour en savoir plus, consultez les ressources suivantes :

• Page du modèle Gemini 3.8 Live
• Configurer des avatars en direct
• Bonnes pratiques avec l'API Gemini Live
• Migrer de Gemini 2.5 Flash Live API Native Audio vers Gemini 3.8 Live
• Tutoriel Python sur l'API Gemini Live
• Présentation du notebook Live Avatar
• Compétence de service de l'API Gemini Live