Gemini API reference

Cette référence d'API décrit les API standards, de streaming et en temps réel que vous pouvez utiliser pour interagir avec les modèles Gemini. Vous pouvez utiliser les API REST dans n'importe quel environnement compatible avec les requêtes HTTP. Consultez le guide de démarrage rapide pour savoir comment effectuer votre premier appel d'API. Si vous recherchez les références de nos bibliothèques et SDK spécifiques à chaque langage, accédez au lien correspondant dans le panneau de navigation de gauche, sous Références du SDK.

Points de terminaison principaux

L'API Gemini est organisée autour des principaux points de terminaison suivants :

  • Génération de contenu standard (generateContent) : point de terminaison REST standard qui traite votre demande et renvoie la réponse complète du modèle dans un seul package. Cette approche est idéale pour les tâches non interactives pour lesquelles vous pouvez attendre le résultat complet.
  • Génération de contenu en streaming (streamGenerateContent) : utilise les événements envoyés par le serveur (SSE) pour vous envoyer des blocs de la réponse à mesure qu'ils sont générés. Cela permet d'offrir une expérience plus rapide et plus interactive pour les applications telles que les chatbots.
  • API Live (BidiGenerateContent) : API avec état basée sur WebSocket pour le streaming bidirectionnel, conçue pour les cas d'utilisation conversationnels en temps réel.
  • Mode batch (batchGenerateContent) : point de terminaison REST standard pour envoyer des lots de requêtes generateContent.
  • Embeddings (embedContent) : point de terminaison REST standard qui génère un vecteur d'embedding de texte à partir de l'entrée Content.
  • API Gen Media : points de terminaison pour générer des contenus multimédias avec nos modèles spécialisés tels qu'Imagen pour la génération d'images et Veo pour la génération de vidéos. Ces fonctionnalités sont également intégrées à Gemini, et vous pouvez y accéder à l'aide de l'API generateContent.
  • API de plate-forme : points de terminaison utilitaires qui prennent en charge les fonctionnalités de base telles que l'importation de fichiers et le comptage de jetons.

Authentification

Toutes les requêtes envoyées à l'API Gemini doivent inclure un en-tête x-goog-api-key avec votre clé API. Créez-en une en quelques clics dans Google AI Studio.

Voici un exemple de requête avec la clé API incluse dans l'en-tête :

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

Pour savoir comment transmettre votre clé à l'API à l'aide des SDK Gemini, consultez le guide Utiliser les clés API Gemini.

Génération de contenu

Il s'agit du point de terminaison central pour envoyer des requêtes au modèle. Il existe deux points de terminaison pour générer du contenu. La principale différence réside dans la façon dont vous recevez la réponse :

  • generateContent (REST) : reçoit une requête et fournit une seule réponse une fois que le modèle a terminé toute sa génération.
  • streamGenerateContent (SSE) : reçoit exactement la même requête, mais le modèle renvoie des fragments de la réponse au fur et à mesure de leur génération. Cela améliore l'expérience utilisateur pour les applications interactives, car vous pouvez afficher immédiatement les résultats partiels.

Structure du corps de la requête

Le corps de la requête est un objet JSON identique pour les modes standard et streaming. Il est construit à partir de quelques objets principaux :

  • Objet Content : représente un seul tour de conversation.
  • Objet Part : élément de données dans un tour Content (comme du texte ou une image).
  • inline_data (Blob) : conteneur pour les octets média bruts et leur type MIME.

Au plus haut niveau, le corps de la requête contient un objet contents, qui est une liste d'objets Content, chacun représentant un tour de conversation. Dans la plupart des cas, pour la génération de texte de base, vous n'aurez qu'un seul objet Content. Toutefois, si vous souhaitez conserver l'historique des conversations, vous pouvez utiliser plusieurs objets Content.

Voici un exemple de corps de requête generateContent typique :

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
          "role": "user",
          "parts": [
              // A list of Part objects goes here
          ]
      },
      {
          "role": "model",
          "parts": [
              // A list of Part objects goes here
          ]
      }
    ]
  }'

Structure du corps de la réponse

Le corps de la réponse est semblable pour les modes streaming et standard, à l'exception des éléments suivants :

De manière générale, le corps de la réponse contient un objet candidates, qui est une liste d'objets Candidate. L'objet Candidate contient un objet Content qui inclut la réponse générée renvoyée par le modèle.

Exemples de requêtes

Les exemples suivants montrent comment ces composants s'assemblent pour différents types de requêtes.

Requête textuelle uniquement

Une requête textuelle simple se compose d'un tableau contents avec un seul objet Content. Le tableau parts de cet objet contient à son tour un seul objet Part avec un champ text.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a single paragraph."
          }
        ]
      }
    ]
  }'

Requête multimodale (texte et image)

Pour fournir à la fois du texte et une image dans une requête, le tableau parts doit contenir deux objets Part : un pour le texte et un pour l'image inline_data.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "contents": [{
    "parts":[
        {
            "inline_data": {
            "mime_type":"image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ... (base64-encoded image)"
            }
        },
        {"text": "What is in this picture?"},
      ]
    }]
  }'

Conversations multitours (chat)

Pour créer une conversation avec plusieurs tours, vous définissez le tableau contents avec plusieurs objets Content. L'API utilisera l'intégralité de cet historique comme contexte pour la prochaine réponse. La valeur role de chaque objet Content doit alterner entre user et model.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Hello." }
        ]
      },
      {
        "role": "model",
        "parts": [
          { "text": "Hello! How can I help you today?" }
        ]
      },
      {
        "role": "user",
        "parts": [
          { "text": "Please write a four-line poem about the ocean." }
        ]
      }
    ]
  }'

Points à retenir

  • Content est l'enveloppe : il s'agit du conteneur de premier niveau pour un tour de message, qu'il provienne de l'utilisateur ou du modèle.
  • Part permet la multimodalité : utilisez plusieurs objets Part dans un même objet Content pour combiner différents types de données (texte, URI d'image, URI de vidéo, etc.).
  • Choisissez votre méthode de données :
    • Pour les petits éléments multimédias intégrés directement (comme la plupart des images), utilisez un Part avec inline_data.
    • Pour les fichiers volumineux ou ceux que vous souhaitez réutiliser dans plusieurs requêtes, utilisez l'API File pour importer le fichier et le référencer avec une partie file_data.
  • Gérer l'historique des conversations : pour les applications de chat utilisant l'API REST, créez le tableau contents en ajoutant des objets Content pour chaque tour de conversation, en alternant les rôles "user" et "model". Si vous utilisez un SDK, consultez sa documentation pour connaître la méthode recommandée pour gérer l'historique des conversations.

Exemples de réponses

Les exemples suivants montrent comment ces composants s'assemblent pour différents types de requêtes.

Réponse textuelle uniquement

Une réponse textuelle simple se compose d'un tableau candidates contenant un ou plusieurs objets content qui contiennent la réponse du modèle.

Voici un exemple de réponse standard :

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "At its core, Artificial Intelligence works by learning from vast amounts of data ..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 1
    }
  ],
}

Voici une série de réponses en streaming. Chaque réponse contient un responseId qui relie l'ensemble de la réponse :

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "The image displays"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  },
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

...

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " the following materials:\n\n*   **Wood:** The accordion and the violin are primarily"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  }
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

API Live (BidiGenerateContent) WebSockets

L'API Live propose une API avec état basée sur WebSocket pour le streaming bidirectionnel afin d'activer les cas d'utilisation du streaming en temps réel. Pour en savoir plus, consultez le guide de l'API Live et la documentation de référence de l'API Live.

Modèles spécialisés

En plus de la famille de modèles Gemini, l'API Gemini propose des points de terminaison pour des modèles spécialisés tels que les modèles Imagen, Lyria et embedding. Vous trouverez ces guides dans la section "Modèles".

API de plate-forme

Les autres points de terminaison permettent d'utiliser des fonctionnalités supplémentaires avec les points de terminaison principaux décrits jusqu'à présent. Pour en savoir plus, consultez les rubriques Mode batch et API File dans la section "Guides".

Étape suivante

Si vous débutez, consultez les guides suivants, qui vous aideront à comprendre le modèle de programmation de l'API Gemini :

Vous pouvez également consulter les guides sur les capacités, qui présentent différentes fonctionnalités de l'API Gemini et fournissent des exemples de code :