Appeler l’API Gemini avec le SDK OpenAI : guide d’intégration en ne modifiant que base_url, la clé et le nom du modèle

Google l’a dit très clairement : l’API Gemini prend en charge l’OpenAI compatibility et peut être appelée avec le SDK Python OpenAI, le SDK JavaScript OpenAI et REST ; dans l’exemple officiel, le base_url est https://generativelanguage.googleapis.com/v1beta/openai/, et le nom du modèle est gemini-3.5-flash (Google AI for Developers).
C’est très pratique pour les équipes qui ont déjà du code basé sur le SDK OpenAI. Vous n’avez pas besoin de réécrire un client, ni de modifier la structure des messages : commencez par remplacer trois paramètres, faites tourner le tout, puis décidez ensuite si vous voulez utiliser les capacités natives de Gemini.

Commençons par les trois éléments à modifier

La documentation Google l’indique très clairement après l’exemple : les changements concernent uniquement api_key, base_url et model. Le SDK Python OpenAI lui-même prend aussi en charge la configuration de base_url ou OPENAI_BASE_URL (openai-python), et le champ correspondant dans le SDK Node est baseURL (openai-node).

Exemple Python minimal :

from openai import OpenAI

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

resp = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[
        {"role": "system", "content": "你是一个简洁的技术助手。"},
        {"role": "user", "content": "用一句话解释什么是向量数据库。"},
    ],
)

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

Si votre ancien code utilise déjà client.chat.completions.create(), il suffit très probablement d’extraire l’initialisation du client dans des paramètres de configuration. Ne codez pas le nom du modèle en dur dans les fonctions métier : plus tard, lorsque vous voudrez passer à Batch, Flex ou changer de modèle, ce sera beaucoup plus pénible.

Node.js suit exactement la même logique

Dans la version JavaScript, seul le nom du champ passe de base_url à baseURL :

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.GEMINI_API_KEY,
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

const resp = await client.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [{ role: "user", content: "给我一个 Redis 限流方案。" }],
});

console.log(resp.choices[0].message.content);

REST peut aussi être appelé directement : POST https://generativelanguage.googleapis.com/v1beta/openai/chat/completions, avec l’en-tête Authorization: Bearer $GEMINI_API_KEY. C’est utile pour commencer par écarter les problèmes liés au SDK, au proxy ou aux variables d’environnement avec curl.

Ne raisonnez pas le prix à l’intuition : calculez selon la sortie

Au 2026-06-14, la page officielle de tarification Gemini indique pour gemini-3.5-flash un prix standard de $1.50 / 1M tokens en entrée et $9.00 / 1M tokens en sortie ; Batch et Flex sont tous deux à $0.75 / 1M tokens en entrée et $4.50 / 1M tokens en sortie (tarification de l’API Gemini). La documentation officielle précise également que le prix de sortie inclut les thinking tokens : pour les tâches de raisonnement, ne regardez donc pas uniquement le prix d’entrée.

Mode	Entrée / 1M tokens	Sortie / 1M tokens	Cas d’usage adaptés
Standard	$1.50	$9.00	Requêtes en ligne, faible latence
Batch	$0.75	$4.50	Traitement par lots hors ligne
Flex	$0.75	$4.50	Planification élastique acceptable

Ma recommandation est simple : pour le chat, les agents et les extensions d’éditeur, commencez par Standard ; pour les résumés de logs, le nettoyage de données et les évaluations hors ligne, privilégiez autant que possible Batch/Flex. Pour les tâches avec de longues sorties, l’écart de coût devient encore plus marqué.

Les pièges les plus fréquents lors de la migration

Premièrement, n’oubliez pas le /openai/ final dans base_url. Beaucoup de 404 ou d’erreurs indiquant que le modèle n’existe pas viennent en réalité du fait que la requête part vers le chemin natif Gemini, et non vers le chemin compatible.
Deuxièmement, distinguez bien les variables d’environnement. OPENAI_API_KEY peut continuer à servir pour OpenAI ; pour Gemini, il est préférable d’utiliser séparément GEMINI_API_KEY, afin d’éviter que deux providers se disputent la même variable dans la CI.
Troisièmement, exécutez d’abord models.list(). La documentation Google fournit des exemples pour lister les modèles et récupérer un modèle ; utilisez-les avant la production pour vérifier que la région du compte, les permissions et l’ID du modèle sont corrects.
Quatrièmement, le streaming, les appels de fonctions et les entrées image ont des exemples dans la couche de compatibilité, mais ne partez pas du principe que tous les paramètres OpenAI sont pris en charge à l’identique. Faites d’abord une régression avec une requête métier réelle.

Si vous voulez maintenir moins de clés

Si votre équipe utilise à la fois Claude, GPT et Gemini, demander les accès un par un, associer des cartes bancaires et configurer les quotas devient vite pénible. La solution la plus simple consiste à utiliser onehop : remplacez le base_url du SDK OpenAI par https://api.onehop.ai/v1, utilisez la clé onehop, et vous pourrez appeler Claude, GPT et Gemini via des interfaces compatibles OpenAI/Anthropic. Son positionnement est de vous éviter les tracas d’intégration ; les prix sont inférieurs aux tarifs officiels, les nouveaux comptes reçoivent $10, sans carte bancaire requise.

from openai import OpenAI

client = OpenAI(
    api_key="ONEHOP_API_KEY",
    base_url="https://api.onehop.ai/v1",
)

resp = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[{"role": "user", "content": "把这段报错日志总结成三条原因。"}],
)

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

Si vous voulez essayer Claude ou le routage multi-modèles, consultez directement : appeler Claude et d’autres modèles sur onehop. Si vous voulez d’abord lancer un petit exemple sans renseigner de carte bancaire, passez par cette entrée : inscription avec $10 de crédit d’essai offerts.

Conclusion : commencez par en faire une configuration, ne codez pas le fournisseur en dur

Le principal intérêt de l’OpenAI compatibility de Gemini n’est pas simplement « un modèle de plus », mais le fait que le coût de migration soit suffisamment faible. Placez base_url, api_key et model dans la configuration, et laissez le code métier continuer à utiliser les chat completions du SDK OpenAI.
Une fois que tout fonctionne, ajoutez trois choses : journaliser les tokens d’entrée/sortie, choisir Standard ou Batch/Flex selon la tâche, et faire de l’ID du modèle un interrupteur de déploiement progressif. Ainsi, que vous intégriez Gemini aujourd’hui, puis Claude ou un autre service compatible demain, vous n’aurez plus à toucher au cœur du code métier.