Documentation de référence de l'API Live

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

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.

Pour en savoir plus sur l'API Live, consultez API Live.

Fonctionnalités

L'API Live inclut les principales fonctionnalités suivantes :

• Multimodalité : le modèle peut voir, entendre et parler.
• Interaction en temps réel à faible latence : le modèle peut fournir des réponses rapides.
• Mémoire par session : le modèle conserve en mémoire toutes les interactions au cours d'une même session, en rappelant les informations déjà entendues ou vues.
• Compatibilité avec l'appel de fonction, l'exécution de code et la recherche en tant qu'outil : vous pouvez intégrer le modèle à des services et des sources de données externes.

L'API Live est conçue pour la communication entre serveurs.

Pour les applications Web et mobiles, nous vous recommandons d'utiliser l'intégration de nos partenaires sur Daily.

Modèles compatibles

• Gemini 2.0 Flash

Commencer

Pour essayer l'API Live, accédez à Vertex AI Studio, puis cliquez sur Lancer une session.

L'API Live est une API avec état qui utilise WebSockets.

Cette section présente un exemple d'utilisation de l'API Live pour la génération de texte à texte à l'aide de Python 3.9 ou version ultérieure.

pip install --upgrade google-genai

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import (
    Content,
    LiveConnectConfig,
    HttpOptions,
    Modality,
    Part,
)

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
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?

Guide d'intégration

Cette section décrit le fonctionnement de l'intégration avec l'API Live.

Sessions

Une connexion WebSocket établit une session entre le client et le serveur Gemini.

Une fois qu'un client a établi une nouvelle connexion, la session peut échanger des messages avec le serveur pour :

• envoyer du texte, de l'audio ou des vidéos au serveur Gemini ;
• recevoir des requêtes audio, textuelles ou d'appel de fonction du serveur Gemini.

La configuration de la session est envoyée dans le premier message après la connexion. Une configuration de session inclut le modèle, les paramètres de génération, les instructions système et les outils.

Consultez l'exemple de configuration suivant :

{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object
  },

  "systemInstruction": string,
  "tools": [object]
}

Pour en savoir plus, consultez BidiGenerateContentSetup.

Envoyer des messages

Les messages sont des objets au format JSON échangés par le biais de la connexion WebSocket.

Pour envoyer un message, le client doit envoyer un objet JSON par le biais d'une connexion WebSocket ouverte. L'objet JSON doit comporter exactement l'un des champs de l'ensemble d'objets suivant :

{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

Messages client acceptés

Consultez les messages client acceptés dans le tableau suivant :

Recevoir des messages

Pour recevoir des messages de Gemini, écoutez l'événement "message" de WebSocket, puis analysez le résultat en fonction de la définition des messages serveur acceptés.

Examinez le code suivant :

ws.addEventListener("message", async (evt) => {
  if (evt.data instanceof Blob) {
    // Process the received data (audio, video, etc.)
  } else {
    // Process JSON response
  }
});

Les messages serveur doivent comporter exactement l'un des champs de l'ensemble d'objets suivant :

{
  "setupComplete": BidiGenerateContentSetupComplete,
  "serverContent": BidiGenerateContentServerContent,
  "toolCall": BidiGenerateContentToolCall,
  "toolCallCancellation": BidiGenerateContentToolCallCancellation
  "usageMetadata": UsageMetadata
  "goAway": GoAway
  "sessionResumptionUpdate": SessionResumptionUpdate
  "inputTranscription": BidiGenerateContentTranscription
  "outputTranscription": BidiGenerateContentTranscription
}

Messages serveur acceptés

Consultez les messages serveur acceptés dans le tableau suivant :

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. 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 de suivi.

Consultez l'exemple de message de contexte suivant :

{
  "clientContent": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

Notez que, bien que les parties de contenu puissent être de type functionResponse, BidiGenerateContentClientContent ne doit pas être utilisé pour fournir une réponse aux appels de fonction émis par le modèle. Utilisez BidiGenerateContentToolResponse à la place. BidiGenerateContentClientContent ne doit être utilisé que pour établir le contexte précédent ou fournir une entrée textuelle à la conversation.

Contenu audio et vidéo en streaming

Exécution du code

Pour en savoir plus sur l'exécution du code, consultez Exécution du code.

Appel de fonction

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

Vous définissez des fonctions à l'aide de JSON, en particulier avec un sous-ensemble sélectionné du format de schéma OpenAPI. Une déclaration de fonction peut inclure les paramètres suivants :

• name (chaîne) : identifiant unique de la fonction dans l'appel d'API.

• description (chaîne) : explication détaillée de l'objectif et des fonctionnalités de la fonction.

• parameters (objet) : définit les données d'entrée requises par la fonction.

  • type (chaîne) : spécifie le type de données global, tel qu'un objet.

  • properties (objet) : liste les paramètres individuels, chacun avec les éléments suivants :

    • type (chaîne) : type de données du paramètre, tel que chaîne, entier ou booléen.
    • description (chaîne) : explication claire de l'objectif du paramètre et du format attendu.

  • required (tableau) : tableau de chaînes listant les noms des paramètres obligatoires pour le bon fonctionnement de la fonction.

Pour obtenir des exemples de code d'une déclaration de fonction à l'aide de commandes curl, consultez Appel de fonction avec l'API Gemini. Pour obtenir des exemples de création de déclarations de fonction à l'aide des SDK de l'API Gemini, consultez le tutoriel sur l'appel de fonction.

À partir d'une seule requête, le modèle peut générer plusieurs appels de fonction et le code nécessaire pour chaîner leurs sorties. Ce code s'exécute dans un environnement de bac à sable, générant par la suite des messages BidiGenerateContentToolCall. L'exécution est interrompue jusqu'à ce que les résultats de chaque appel de fonction soient disponibles, ce qui assure un traitement séquentiel.

Le client doit répondre avec BidiGenerateContentToolResponse.

Pour en savoir plus, consultez Présentation de l'appel de fonction.

Formats audio

Consultez la liste des formats audio acceptés.

Instructions système

Vous pouvez fournir des instructions système pour mieux contrôler la sortie du modèle et spécifier le ton et le sentiment des réponses audio.

Les instructions système sont ajoutées à la requête avant le début de l'interaction et s'appliquent pendant toute la session.

Les instructions système ne peuvent être définies qu'au début d'une session, immédiatement après la connexion initiale. Pour fournir des entrées supplémentaires au modèle pendant la session, utilisez des mises à jour incrémentielles du contenu.

Interruptions

Les utilisateurs peuvent interrompre la sortie du modèle à tout moment. Lorsque la détection de l'activité vocale (VAD, Voice Activity Detection) 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.

De plus, le serveur Gemini supprime tous les appels de fonction en attente et envoie un message BidiGenerateContentServerContent avec les ID des appels annulés.

Voix

Pour spécifier une voix, définissez voiceName dans l'objet speechConfig lors de la configuration de la session.

Examinez la représentation JSON suivante d'un objet speechConfig :

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "VOICE_NAME"
    }
  }
}

Pour afficher la liste des voix acceptées, consultez Modifier les paramètres de voix et de langue.

Limites

Tenez compte des limites suivantes de l'API Live et de Gemini 2.0 lorsque vous planifiez votre projet.

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 au moyen d'un serveur d'applications intermédiaire pour assurer une authentification sécurisée avec l'API Live.

Durée maximale de la session

La durée maximale par défaut d'une session de conversation est de 10 minutes. Pour en savoir plus, consultez Durée des sessions.

Détection de l'activité vocale (VAD)

Par défaut, le modèle détecte automatiquement l'activité vocale 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 est 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.

Autres limites

La sélection manuelle du point de terminaison n'est pas prise en charge.

Les entrées et les sorties audio ont un impact négatif sur la capacité du modèle à utiliser l'appel de fonction.

Nombre de jetons

Le nombre de jetons n'est pas pris en charge.

Limites de débit

Les limites de débit suivantes s'appliquent :

• 3 sessions simultanées par clé API
• 4 millions de jetons par minute

Messages et événements

Étapes suivantes

• Apprenez-en plus sur l'appel de fonction.
• Consultez la documentation de référence sur l'appel de fonction pour obtenir des exemples.