API Gemini Live

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

L'API Gemini Live permet des interactions bidirectionnelles à faible latence qui utilisent du texte, de l'audio et de la vidéo en entrée, avec une sortie audio et textuelle. Cela facilite les conversations vocales naturelles et humaines, avec la possibilité d'interrompre le modèle à tout moment. La capacité de compréhension vidéo du modèle élargit les modalités de communication, ce qui vous permet de partager des entrées de l'appareil photo ou des enregistrements d'écran, et de poser des questions à leur sujet.

Capacité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 de session: le modèle conserve la mémoire de toutes les interactions au cours d'une même session, en rappelant les informations entendues ou vues précédemment.
• 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 de serveur à serveur.

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

Commencer

Pour essayer l'API Live, accédez à Vertex AI Studio, puis cliquez sur Start Session (Démarrer la session).

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

Cette section montre comment utiliser l'API Live pour la génération de texte à partir de 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=us-central1
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 explique comment fonctionne 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 de la vidéo au serveur Gemini
• Recevoir des requêtes d'appel audio, textuel ou de fonction à partir du serveur Gemini

La configuration de la session est envoyée dans le premier message après la connexion. Une configuration de session comprend 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 via la connexion WebSocket.

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

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

Messages client compatibles

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

Recevoir des messages

Pour recevoir des messages de Gemini, écoutez l'événement "message" WebSocket, puis analysez le résultat conformément à la définition des messages de serveur compatibles.

Consultez les références suivantes :

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

Les messages du serveur comportent exactement 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 de serveur compatibles

Consultez les messages de serveur compatibles dans le tableau suivant:

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. 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 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 de texte à la conversation.

Streaming audio et vidéo

Exécution du code

Pour en savoir plus sur l'exécution du code, consultez la section 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 seule 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 complète 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:

    • type (chaîne): type de données du paramètre, par exemple "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 de paramètres obligatoires pour que la fonction fonctionne.

Pour obtenir des exemples de code d'une déclaration de fonction à l'aide de commandes curl, consultez la section 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 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.

Le client doit répondre avec BidiGenerateContentToolResponse.

Pour en savoir plus, consultez la section Présentation des appels de fonction.

Formats audio

L'API Live est compatible avec les formats audio suivants:

• Format audio d'entrée: audio PCM brut 16 bits à 16 kHz, little-endian
• Format audio de sortie: audio PCM brut 16 bits à 24 kHz, little-endian

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 à l'invite avant le début de l'interaction et restent en vigueur 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 d'autres informations au modèle pendant la session, utilisez des mises à jour de contenu incrémentielles.

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.

Voix

L'API Live est compatible avec les voix suivantes:

• Palet
• Charon
• Kore
• Fenrir
• Aoede

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

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

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

Limites

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

Authentification client

L'API en direct 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.

Historique de la conversation

Bien que le modèle suive les interactions pendant la session, l'historique de la conversation n'est pas stocké. À la fin d'une session, le contexte correspondant est effacé.

Pour restaurer une session précédente ou fournir au modèle le contexte historique des interactions utilisateur, l'application doit gérer son propre journal de conversation et utiliser un message BidiGenerateContentClientContent pour envoyer ces informations au début d'une nouvelle session.

Durée maximale de la session

La durée de la session est limitée à 15 minutes pour l'audio ou à 2 minutes pour l'audio et la vidéo. Lorsque la durée de la session dépasse la limite, la connexion est interrompue.

Le modèle est également limité par la taille du contexte. L'envoi de grands blocs de contenu en plus des flux vidéo et audio peut entraîner la fin prématurée de la session.

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

Par défaut, le modèle effectue automatiquement la détection de l'activité vocale (VAD) 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, lorsque l'utilisateur éteint le micro), un événement AudioStreamEnd est envoyé pour vider tout contenu audio mis en cache. Le client peut reprendre l'envoi de 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 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.

Autres limites

Le point de terminaison manuel n'est pas accepté.

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 accepté.

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

Étape suivante

• En savoir plus sur les appels de fonction
• Pour obtenir des exemples, consultez la documentation de référence sur l'appel de fonction.