Le chemin le plus court pour intégrer l'API Gemini est le suivant : ouvrir AI Studio avec un compte Google, créer une clé API, installer le SDK et envoyer une première requête generateContent. Dans le meilleur des cas, l'ensemble prend moins de vingt minutes. Les véritables points de blocage ne sont pas la « capacité à appeler l'API », mais le choix du mauvais point d'entrée, un identifiant de modèle mal orthographié, la confusion entre quota gratuit et offre payante, et une clé stockée au mauvais endroit.

Cet article suit l'ordre réel de l'intégration : distinguer d'abord AI Studio et Vertex AI, puis créer la clé, installer le SDK, envoyer des requêtes curl et Python, traiter ensuite la nomenclature des modèles, les instructions système, le streaming et les paramètres de sécurité, et enfin lister les causes fréquentes des erreurs 400, 403 et 429 ainsi qu'une checklist de sécurité des clés.

Note : Google et Gemini sont des marques de Google LLC. Les noms de modèles, les quotas gratuits et les règles de facturation peuvent évoluer. Cet article décrit le flux courant d'octobre 2026 ; la documentation officielle de Google et les prix des modèles font foi.

1. Distinguer AI Studio et Vertex AI

L'API Gemini possède deux points d'entrée courants, avec des systèmes de comptes et des modes d'administration différents. Un mauvais choix entraîne des reprises sur les permissions ou la facturation.

Critère Google AI Studio Vertex AI
Point d'entrée Console web destinée aux essais rapides des développeurs Console Google Cloud, orientée usage par projet
Compte requis Un compte Google suffit pour commencer Projet Cloud, compte de facturation et permissions IAM
Identifiants Clé API générée dans AI Studio Compte de service ou clé contrôlée, avec IAM
Facturation Offre gratuite et offre payante coexistantes Facturation par projet Cloud
Région et données Selon les conditions d'AI Studio Régions sélectionnables, selon les conditions Cloud et la configuration du projet
Cas adaptés Prototypes, apprentissage, validation à petite échelle Systèmes de production, équipes avec exigences d'audit et de permissions

Les développeurs individuels et les petites équipes passent généralement d'abord par AI Studio pour valider le flux ; dès qu'interviennent des contrats, des régions de données ou un audit unifié, il faut évaluer Vertex AI. Ne mélangez pas les clés, quotas et factures des deux côtés, et n'utilisez pas une clé AI Studio pour appeler une interface Vertex AI.

2. Créer sa première clé API

  1. Connectez-vous à Google AI Studio avec un compte Google.
  2. Ouvrez la page de gestion des clés API et choisissez de créer une clé.
  3. Sélectionnez un projet Google Cloud ; s'il n'en existe pas, créez-en un en suivant les indications de la page.
  4. Copiez la clé générée et stockez-la immédiatement dans une variable d'environnement côté serveur ou un gestionnaire de mots de passe.
  5. Envoyez un message de test dans le Playground pour vérifier que la clé et le modèle fonctionnent.
  6. Donnez à la clé un nom qui indique son usage, pour faciliter les rotations et révocations ultérieures.

AI Studio propose une offre gratuite pour les essais ; les modèles disponibles, la fréquence des requêtes et les quotas varient selon le compte et la période. Une fois la facturation activée sur le projet Cloud associé, vous accédez à l'offre payante. Ne considérez pas les chiffres de quotas trouvés dans d'anciens articles comme un engagement actuel : la console et la documentation officielle font foi.

Après la création, vérifiez à quel projet Cloud la clé appartient. Les quotas sont généralement calculés par projet ; mélanger test et production peut épuiser le quota d'autres personnes. Pour obtenir davantage, activez la facturation sur le projet Cloud, configurez une alerte budgétaire et observez l'usage réel pendant une semaine.

3. Installer le SDK et envoyer la première requête

Utilisez de préférence Python 3.10 ou supérieur et installez le SDK officiel dans un environnement virtuel.

python3 -m venv .venv
source .venv/bin/activate
pip install -U google-genai
export GEMINI_API_KEY="votre-cle"

Commencez par curl pour écarter les facteurs liés au SDK. L'identifiant du modèle est représenté par un espace réservé ; le nom réel se récupère dans la liste des modèles ou sur la page des prix.

curl "https://generativelanguage.googleapis.com/v1beta/models/<ID_MODELE>:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Explique en une phrase ce qu'\''est une passerelle API"}]}
    ],
    "generationConfig": {"maxOutputTokens": 256, "temperature": 0.7}
  }'

Une fois le code 200 obtenu avec curl, passez au SDK Python :

import os
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

resp = client.models.generate_content(
    model="<ID_MODELE>",
    contents="Explique en une phrase ce qu'est une passerelle API",
)
print(resp.text)

Le champ model doit contenir l'identifiant complet du modèle, pas seulement le nom de la série. Les types d'entrée et les paramètres pris en charge varient selon le modèle ; une erreur se traduit par un 400 ou un 404.

4. Nomenclature des modèles, instructions système et paramètres de génération

Les identifiants de modèles Gemini combinent généralement une série et une version. La méthode la plus sûre consiste à interroger d'abord la liste des modèles disponibles pour le compte :

curl "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

Ne devinez pas les modèles absents de la liste. Pour le choix, répartissez selon la tâche : gamme à faible latence pour les tâches légères, gamme supérieure pour le raisonnement complexe et les documents longs. Les gammes et les prix exacts figurent sur la page des prix.

Les identifiants de modèles évoluent avec les versions ; les anciens peuvent être marqués comme obsolètes ou retirés. Placez le nom du modèle dans un fichier de configuration plutôt que dispersé dans le code : une mise à jour ne touche qu'un seul endroit, et des échantillons de régression confirment que la sortie ne change pas sensiblement.

Les instructions système fixent le rôle et les règles de sortie ; elles conviennent à la traduction, à l'extraction et au support :

resp = client.models.generate_content(
    model="<ID_MODELE>",
    contents="Traduis cette phrase en anglais : intégration terminée",
    config={"system_instruction": "Tu es un traducteur de documentation technique ; produis uniquement la traduction."},
)

Les paramètres de génération courants sont temperature, maxOutputTokens et topP. Pour un résultat structuré, demandez du JSON au modèle et validez-le dans le code ; ne supposez pas que le modèle respectera toujours le format. Prévoyez dès le départ les nouvelles tentatives en cas d'échec et une logique de repli.

5. Streaming et paramètres de sécurité

Le streaming convient aux interfaces de chat et aux réponses longues. Avec l'API REST, ajoutez :streamGenerateContent après la méthode et alt=sse ; avec le SDK Python, utilisez generate_content_stream :

for chunk in client.models.generate_content_stream(
    model="<ID_MODELE>",
    contents="Explique en trois points ce qu'est la limitation de débit",
):
    print(chunk.text, end="")

Les paramètres de sécurité permettent d'ajuster les seuils de blocage par catégorie ; les catégories courantes incluent le harcèlement, la haine, le contenu sexuel et le contenu dangereux. Les seuils par défaut conviennent à la plupart des usages ; les abaisser élargit le contenu accepté et doit être évalué au regard de la politique produit et de la réglementation locale. Ne désactivez pas entièrement les paramètres de sécurité pour « passer les tests », surtout pour un produit grand public.

6. Diagnostiquer les erreurs 400, 403 et 429

Code Causes fréquentes Piste de traitement
400 Structure JSON incorrecte, paramètre non pris en charge, identifiant de modèle incompatible avec l'interface Vérifier chaque champ du corps de requête ; commencer par une requête minimale
403 Clé invalide ou restreinte, API non activée, restriction de projet ou de région Tester une autre clé ; vérifier les permissions du projet et l'état du compte
404 Identifiant de modèle mal orthographié, version ou chemin d'interface incorrect Consulter la liste des modèles et vérifier v1beta ainsi que le nom de la méthode
429 Quota gratuit épuisé, trop de requêtes par minute, concurrence excessive Temporisation exponentielle, réduction de la concurrence, évaluation de l'offre payante
500/503 Panne temporaire du service Nouvelles tentatives limitées, puis repli ou changement de canal si l'échec persiste

Ne renvoyez pas immédiatement une requête après un 429. La bonne pratique est une temporisation avec gigue aléatoire, un nombre maximal de tentatives et l'enregistrement des échecs dans les journaux. Les limites de l'offre gratuite sont généralement plus strictes ; planifiez séparément les tests de charge et les traitements par lots.

7. Checklist de sécurité des clés

  • Stocker la clé uniquement dans des variables d'environnement côté serveur ou un gestionnaire de secrets, jamais dans le frontend, un dépôt ou un historique de discussion.
  • Utiliser une clé distincte pour la production, les tests et le développement, avec isolation des quotas et permissions par environnement.
  • Effectuer une rotation régulière et révoquer immédiatement la clé au départ d'une personne ou à la fin d'un projet.
  • Restreindre dans la console cloud les API que la clé peut appeler, afin de réduire l'impact d'une fuite.
  • Activer les alertes d'usage : en cas d'appels anormaux, désactiver d'abord la clé, puis enquêter.
  • Ne jamais exposer une clé complète dans une capture d'écran, un enregistrement ou un ticket de support.

8. Accéder à Gemini via une entrée compatible OpenAI

Si l'équipe dispose déjà du SDK OpenAI et d'un ensemble de code d'appel, elle peut passer par l'entrée compatible OpenAI de ZSQH AI Gateway, dont la Base URL est https://ai.zhongshangqihang.com/v1. Il suffit de modifier trois éléments : base_url, api_key et model.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.chat.completions.create(
    model="<nom du modèle Gemini sur la page des prix>",
    messages=[{"role": "user", "content": "Réponds seulement OK"}],
)
print(resp.choices[0].message.content)

Cette approche convient aux équipes qui veulent une facturation multi-modèles unifiée, un règlement en yuans et un réseau local stable. Les paramètres natifs de Gemini et les champs multimodaux ne sont pas nécessairement compatibles ; validez point par point avec de vraies requêtes avant la migration. L'inscription se fait ici ; les modèles et les prix sont régis par la page des prix.

Questions fréquentes

L'API Gemini propose-t-elle un quota gratuit ?

AI Studio propose une offre gratuite, mais les modèles disponibles, les débits et les quotas changent, et les conditions de données peuvent différer de l'offre payante. L'offre gratuite convient à la validation de prototypes ; pour une activité réelle, réévaluez quotas et coûts sur l'offre payante.

Que faire si une clé API est divulguée ?

Révoquez ou renouvelez d'abord la clé dans la console, puis consultez les journaux d'usage pour délimiter les appels anormaux, et enfin recherchez le canal de fuite. Supprimer la clé du code ne suffit pas : un identifiant divulgué doit être considéré comme invalide.

Peut-on appeler l'API Gemini directement depuis un réseau local ?

La qualité de la liaison dépend de la région et de l'opérateur ; des délais dépassés ou des échecs de connexion sont possibles. La pratique courante consiste à placer les requêtes sur un serveur à l'accès stable, ou à utiliser une passerelle prenant en charge l'interface compatible OpenAI. Les restrictions exactes dépendent de la liaison réelle et de la documentation officielle.

Pourquoi curl fonctionne-t-il alors que le SDK Python renvoie une erreur ?

Vérifiez d'abord la version du SDK et l'actualité des dépendances, puis la syntaxe de model, les réglages de proxy et la cohérence des variables d'environnement. En cas de 404 côté SDK, contrôlez surtout l'identifiant du modèle et le chemin de l'interface, sans modifier plusieurs variables à la fois.

Peut-on appeler l'API Gemini avec le SDK OpenAI ?

Google propose une entrée compatible OpenAI, et les passerelles locales offrent souvent une couche de compatibilité, mais l'éventail des paramètres pris en charge diffère. Le multimodal, l'appel d'outils et les sorties structurées doivent être validés avec de vraies requêtes ; ne supposez pas une équivalence totale.

Étape suivante

Faites d'abord fonctionner la requête minimale selon le flux ci-dessus, puis ajoutez les journaux métier, les nouvelles tentatives et la surveillance de l'usage. Pour gérer dans une seule console les appels à Gemini et à d'autres modèles, la facturation en yuans et les permissions des clés, vous pouvez commencer par vous inscrire à ZSQH AI Gateway ; les prix figurent dans les prix des modèles.

Lectures associées :