Guide de l'API Gemini Pro : Clé, Point d'accès, Identifiants de modèle et Compatibilité OpenAI

L’API Gemini Pro est accessible via l’API Gemini avec une clé créée dans Google AI Studio. Pour une requête REST directe, appelez le point d’accès generateContent du modèle ; pour une intégration SDK OpenAI existante, pointez le client vers l’URL de base compatible OpenAI de Google et utilisez un identifiant de modèle Gemini actuel tel que gemini-3.1-pro-preview. Le détail important est que « Gemini Pro » est un terme de recherche de famille de produits, et non un identifiant API permanent. Par conséquent, les applications de production devraient lire la liste des modèles actuels de Google avant de fixer un identifiant.

Configuration rapide de l’API Gemini Pro

Vous avez besoin de quatre valeurs pour effectuer une requête :

Paramètre	Valeur
Clé API	Créez-en une dans Google AI Studio
Hôte de base natif	https://generativelanguage.googleapis.com
Chemin API natif	/v1beta/models/{model}:generateContent
URL de base compatible OpenAI	https://generativelanguage.googleapis.com/v1beta/openai/
Exemple d’identifiant de modèle	gemini-3.1-pro-preview

Le guide de démarrage rapide de l’API Gemini de Google documente la création de la clé API et le modèle de requête natif. Son guide de compatibilité OpenAI documente l’URL de base de compatibilité pour les applications qui utilisent déjà le SDK Python ou JavaScript OpenAI.

Utilisez le SDK Gemini natif ou l’API REST lorsque vous souhaitez des fonctionnalités spécifiques à Gemini dès que Google les expose. Utilisez la couche de compatibilité lorsque vous disposez déjà d’un client de style OpenAI et que vous souhaitez réduire le travail de migration. La compatibilité est utile, mais elle ne garantit pas que chaque option spécifique à un fournisseur corresponde parfaitement aux différentes API.

Comment obtenir une clé API Google pour Gemini

Créez la clé dans Google AI Studio, puis stockez-la dans une variable d’environnement au lieu de la placer dans le code source :

export GEMINI_API_KEY="VOTRE_CLE_API_GEMINI"

Traitez-la comme une information d’identification côté serveur. Ne la commettez pas dans Git, ne l’imprimez pas dans les journaux et ne l’incorporez pas dans du JavaScript de navigateur ou une application mobile. Si un frontend a besoin de la sortie de Gemini, envoyez la requête utilisateur à votre propre backend et laissez le backend appeler l’API Google.

Pour un service de production, décidez également qui possède le projet Google Cloud, comment les clés sont pivotées, quels environnements reçoivent des informations d’identification séparées et où les quotas de requêtes sont surveillés. Les conseils sur les clés API de Google expliquent comment les clés API Gemini sont associées aux projets Google Cloud.

Comment appeler le point d’accès natif de l’API Gemini

La route REST native place l’identifiant du modèle dans l’URL. Cet exemple demande au modèle d’aperçu Pro actuel de renvoyer une liste de contrôle de migration concise :

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Créez une liste de contrôle en sept étapes pour migrer une API Python d'une région vers deux régions. Incluez des vérifications de restauration."
          }
        ]
      }
    ]
  }'

La réponse contient des candidats avec le contenu généré. Les applications réelles doivent gérer une liste de candidats vide, un contenu bloqué, des délais d’attente et des réponses non-2xx plutôt que d’indexer directement dans le premier objet de réponse.

L’URL utilise v1beta car c’est la route montrée dans les exemples actuels de l’API Gemini de Google. Conservez la version de l’API dans la configuration afin de pouvoir tester une nouvelle version sans disperser les chaînes de point d’accès dans toute la base de code.

Anatomie du point d’accès natif

Le chemin comporte trois parties :

/v1beta/models/{model}:generateContent

• v1beta est la version de l’API.
• {model} est l’identifiant exact du modèle provenant de la page des modèles Gemini de Google.
• generateContent est la méthode de génération.

Une réponse 404 signifie souvent que l’identifiant du modèle, la version de l’API ou la méthode ne correspondent pas. Avant de modifier le code d’authentification, comparez le chemin complet avec la documentation actuelle du modèle.

Comment utiliser Gemini avec un client compatible OpenAI

Si votre application utilise déjà le package Python OpenAI, installez-le et modifiez la clé API, l’URL de base et l’identifiant du modèle :

pip install openai

import os

from openai import OpenAI


client = OpenAI(
    api_key=os.environ["GEMINI_API_KEY"],
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

response = client.chat.completions.create(
    model="gemini-3.1-pro-preview",
    messages=[
        {
            "role": "system",
            "content": "Vous êtes un réviseur d'architecture logicielle concis.",
        },
        {
            "role": "user",
            "content": "Examinez la conception d'un worker de file d'attente et listez les cinq principaux modes de défaillance.",
        },
    ],
)

print(response.choices[0].message.content)

C’est la route la plus courte pour les équipes disposant d’une abstraction de chat-complétions existante. Cela rend également un harnais d’évaluation plus facile à réutiliser : conservez l’invite et les vérifications de réponse constantes, puis changez la configuration du fournisseur.

Ne supposez pas un comportement identique simplement parce que deux fournisseurs acceptent le même appel SDK. Les instructions système, les schémas d’outils, les entrées multimodales, la gestion de la sécurité, les événements de streaming, la comptabilité des jetons et les charges utiles d’erreur peuvent différer. Exécutez des tests spécifiques au fournisseur avant de modifier le trafic de production.

Comment choisir et gérer les identifiants de modèle Gemini

Évitez de placer un nom marketing tel que gemini-pro directement dans la logique de l’application. Les identifiants de modèle disponibles chez Google changent à mesure que les modèles d’aperçu sont introduits, promus et retirés. Au moment où ce guide a été vérifié, la page officielle des modèles de Google listait gemini-3.1-pro-preview comme un identifiant de modèle de classe Pro.

Utilisez plutôt une couche de configuration :

import os


GEMINI_MODEL = os.getenv("GEMINI_MODEL", "gemini-3.1-pro-preview")

Ce petit choix fait des mises à niveau de modèle un changement de déploiement plutôt qu’une réécriture de code. Pour un service plus important, stockez ces champs ensemble :

{
  "provider": "google",
  "base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
  "model": "gemini-3.1-pro-preview",
  "timeout_seconds": 60
}

Avant de déplacer un nouveau modèle en production :

1. Confirmez que l’identifiant apparaît dans la documentation actuelle du modèle de Google ou dans l’API des modèles.
2. Vérifiez si le modèle est en aperçu, stable ou programmé pour la retraite.
3. Exécutez votre propre ensemble d’évaluation pour la qualité des réponses et l’exactitude des appels d’outils.
4. Mesurez la latence, l’utilisation des jetons et les taux d’échec avec des invites représentatives.
5. Ajoutez un modèle de secours ou un chemin d’échec clair avant de basculer tout le trafic.

Les limites de débit ne sont pas un nombre universel unique. Elles dépendent du modèle et du niveau d’utilisation, alors lisez la documentation sur les limites de débit de l’API Gemini de Google et surveillez les limites appliquées à votre projet.

Comment construire un backend commutable entre fournisseurs

Une interface compatible OpenAI peut réduire les changements de code, mais le changement de fournisseur fonctionne mieux lorsque votre propre application définit le contrat. Gardez la configuration du fournisseur en dehors de la logique métier et normalisez la sortie dont vous avez réellement besoin.

import os

from openai import OpenAI


PROVIDERS = {
    "gemini": {
        "api_key": os.environ["GEMINI_API_KEY"],
        "base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
        "model": os.getenv("GEMINI_MODEL", "gemini-3.1-pro-preview"),
    },
    "novita": {
        "api_key": os.environ["NOVITA_API_KEY"],
        "base_url": "https://api.novita.ai/openai",
        "model": os.getenv("NOVITA_MODEL", "xiaomimimo/mimo-v2.5-pro"),
    },
}


def generate(nom_fournisseur: str, prompt: str) -> str:
    fournisseur = PROVIDERS[nom_fournisseur]
    client = OpenAI(
        api_key=fournisseur["api_key"],
        base_url=fournisseur["base_url"],
    )
    response = client.chat.completions.create(
        model=fournisseur["model"],
        messages=[{"role": "user", "content": prompt}],
    )
    return response.choices[0].message.content or ""

Cet exemple expose délibérément les différences au lieu de les cacher. Chaque fournisseur conserve ses propres informations d’identification, URL de base et identifiant de modèle. L’application reçoit une chaîne normalisée, tandis que des tests spécifiques au fournisseur peuvent couvrir un comportement plus riche tel que les outils ou les entrées multimodales.

La documentation de l’API LLM de Novita AI utilise une forme d’API compatible OpenAI pour les modèles pris en charge. Cela peut être utile lorsqu’une équipe souhaite comparer Gemini avec des modèles open source sans reconstruire toute la couche client.

Comment Gemini s’intègre dans un backend d’agent

Un backend d’agent a au moins deux responsabilités distinctes :

1. Inférence : Le modèle décide quoi dire ou quel outil appeler.
2. Exécution : Un environnement d’exécution contrôlé effectue des actions de fichier, shell, navigateur ou application.

L’API Gemini peut gérer le côté inférence. Elle ne doit pas être traitée comme la limite d’exécution. Si un modèle propose une commande shell, votre application doit toujours valider l’appel d’outil, l’autoriser, l’exécuter dans un environnement isolé, capturer le résultat et décider quel contexte renvoyer au modèle.

Novita Agent Sandbox est conçu pour des flux de travail d’exécution d’agent isolés. Une architecture pratique peut utiliser Gemini pour le raisonnement tandis qu’un bac à sable gère le code ou les tâches de navigateur séparément :

Requête utilisateur
    -> Service agent
        -> API Gemini pour le raisonnement et la sélection d'outils
        -> Vérifications de politique pour l'action proposée
        -> Agent Sandbox pour l'exécution isolée
        -> Résultat de l'outil renvoyé au service agent
        -> API Gemini pour la réponse finale

Cette séparation rend le modèle remplaçable et maintient l’exécution non fiable loin du serveur d’application. Elle donne également au backend un endroit pour appliquer les délais d’attente, la politique réseau, les limites de fichiers, la journalisation d’audit et l’autorisation utilisateur.

Pour une première version, exposez seulement quelques outils restreints, définissez des schémas JSON pour leurs arguments, rejetez les champs inconnus et placez des limites strictes sur le temps d’exécution et la taille de la sortie. Ajoutez des capacités plus larges d’utilisation de l’ordinateur ou du navigateur uniquement après que le modèle d’autorisation est clair.

Quand un modèle open source est un meilleur choix

Les modèles Gemini Pro sont une option solide lorsque votre application a besoin des capacités du modèle Google et de l’API gérée. Un modèle open source peut être un meilleur choix lorsque vous avez besoin d’un deuxième fournisseur, souhaitez évaluer le comportement du modèle par rapport à une version amont visible, ou préférez un modèle disponible via un point d’accès compatible OpenAI aux côtés d’autres infrastructures.

MiMo-V2.5-Pro est une option actuelle sur Novita AI. La fiche technique du modèle amont de Xiaomi le décrit comme un modèle open source Mixture-of-Experts, tandis que Novita AI fournit l’identifiant de modèle hébergé xiaomimimo/mimo-v2.5-pro. Étant donné que le point d’accès de compatibilité Google et Novita AI peuvent être appelés avec un client de style OpenAI, le modèle commutable entre fournisseurs de la section précédente peut les évaluer avec les mêmes invites et vérifications d’acceptation.

Ne choisissez pas uniquement sur l’étiquette. Construisez un petit ensemble d’évaluation à partir de votre charge de travail réelle : commentaires de révision de code, questions de support, réponses basées sur la récupération, appels d’outils ou longs documents. Comparez la qualité de la sortie, la latence, le comportement des erreurs et le coût en utilisant les tableaux de bord actuels des fournisseurs avant de prendre une décision de routage.

Erreurs courantes de l’API Gemini

400 : Requête invalide

Vérifiez la forme JSON, les rôles des messages, les définitions d’outils et les noms de paramètres. Une option acceptée par un autre fournisseur compatible OpenAI peut ne pas être acceptée par la couche de compatibilité de Google.

401 ou 403 : Échec d’authentification ou d’autorisation

Confirmez que GEMINI_API_KEY est présente dans l’environnement du processus et appartient au projet Google Cloud prévu. Vérifiez également si le projet et le modèle sélectionné sont disponibles pour le compte et la région.

404 : Modèle ou méthode non trouvé

Comparez l’identifiant exact du modèle avec la liste actuelle des modèles Gemini. Pour les appels REST natifs, vérifiez la version de l’API et le suffixe :generateContent. Pour les appels compatibles OpenAI, vérifiez que l’URL de base se termine par /v1beta/openai/.

429 : Limite de débit dépassée

Réessayez avec un backoff exponentiel et une gigue, mais ne traitez pas les nouvelles tentatives comme un substitut à la planification de la capacité. Mettez en file d’attente le travail en rafale, limitez les requêtes simultanées et inspectez le niveau d’utilisation actuel du projet et les limites spécifiques au modèle.

Le SDK fonctionne, mais la sortie diffère après avoir changé de fournisseur

La compatibilité couvre l’interface de requête, pas un comportement de modèle identique. Réexécutez les tests d’invite, de sortie structurée et d’appel d’outil pour chaque fournisseur et version de modèle.

Conclusion

Commencez avec l’API Gemini native lorsque vous souhaitez le chemin le plus clair vers les fonctionnalités spécifiques à Gemini. Commencez avec le point d’accès compatible OpenAI lorsque vous avez déjà un backend de style OpenAI ou avez besoin d’une évaluation rapide du fournisseur. Dans les deux cas, conservez la clé API côté serveur, placez l’identifiant du modèle dans la configuration, testez la version exacte du modèle et séparez le raisonnement du modèle de l’exécution de l’agent.

Pour une conception de production résiliente, conservez au moins un modèle alternatif derrière la même interface appartenant à l’application. Cela donne à votre équipe un moyen pratique de tester une option open source sur Novita AI, de gérer les changements de cycle de vie du modèle et de router l’exécution de l’agent dans un bac à sable isolé au lieu de coupler chaque responsabilité à un seul appel API.

FAQ

Existe-t-il encore un identifiant de modèle appelé gemini-pro ?

Ne supposez pas que gemini-pro est l’identifiant actuel. « API Gemini Pro » est couramment utilisé comme expression de recherche pour les modèles Gemini de plus haute capacité de Google, mais les applications doivent utiliser un identifiant exact provenant de la page actuelle des modèles Gemini. Ce guide utilise gemini-3.1-pro-preview comme exemple vérifié.

Où puis-je obtenir une clé API Google pour Gemini ?

Créez une clé API Gemini dans Google AI Studio. Stockez-la dans un secret côté serveur tel que GEMINI_API_KEY, pas dans le code source ou le JavaScript du frontend.

Quel est le point d’accès de l’API Gemini ?

L’hôte natif est https://generativelanguage.googleapis.com. Une requête de génération de contenu utilise /v1beta/models/{model}:generateContent. L’URL de base compatible OpenAI de Google est https://generativelanguage.googleapis.com/v1beta/openai/.

L’API Gemini Studio est-elle différente de l’API Gemini ?

Google AI Studio est l’interface web que les développeurs utilisent pour expérimenter et créer une clé. Les requêtes d’application vont à l’API Gemini. Les recherches pour « API Gemini Studio » font généralement référence à ce flux de travail d’AI Studio à API.

L’API Google Bard est-elle la même que l’API Gemini ?

Gemini est la marque actuelle de l’API et du modèle. Les recherches plus anciennes pour une API Google Bard doivent utiliser la documentation, les points d’accès et les identifiants de modèle actuels de l’API Gemini plutôt que les anciens exemples de Bard.

Puis-je utiliser le SDK OpenAI avec Gemini ?

Oui. Google documente un point d’accès de compatibilité OpenAI. Définissez l’URL de base du client sur l’URL de compatibilité de Google, fournissez votre clé API Gemini et sélectionnez un identifiant de modèle Gemini pris en charge. Testez les fonctionnalités spécifiques au fournisseur avant de vous fier à une parité comportementale complète.

Gemini peut-il exécuter du code pour un agent IA ?

Gemini peut raisonner sur le code et proposer des appels d’outils, mais l’exécution doit avoir lieu dans un environnement d’exécution contrôlé. Gardez l’appel de modèle séparé d’un environnement isolé tel que Agent Sandbox, et validez chaque action demandée avant de l’exécuter.

Articles recommandés

• Meilleure plateforme d’API LLM pour changer de fournisseur
• Que sont les agents de codage ? Architecture, outils et sécurité
• API MiMo 2.5 sur Novita AI : API de chat compatible OpenAI