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

Google le dit très clairement : les modèles Gemini sont accessibles via les SDK Python et TypeScript/JavaScript d’OpenAI ; en pratique, il suffit de modifier trois lignes de code. Le point de terminaison indiqué dans la documentation officielle de compatibilité est https://generativelanguage.googleapis.com/v1beta/openai/, et le modèle d’exemple est gemini-3.5-flash (Compatibilité OpenAI de Google). C’est très pratique pour les projets qui utilisent déjà le SDK OpenAI : pas besoin de démonter d’abord l’abstraction de provider, ni de remplacer toute la pile d’appels ; faites d’abord fonctionner l’intégration.

Commencez par confirmer le modèle que vous voulez appeler

Au 14/06/2026, la page des modèles de Google liste Gemini 3.5 Flash comme Stable et précise que le code du modèle est gemini-3.5-flash ; ce modèle accepte jusqu’à 1 048 576 tokens en entrée et jusqu’à 65 536 tokens en sortie, prend en charge les entrées texte, image, vidéo, audio et PDF, et produit du texte en sortie (Gemini 3.5 Flash). La page du modèle a été mise à jour pour la dernière fois le 19/05/2026 UTC.

Il faut également consulter la documentation tarifaire du jour. La page des prix de Google a été mise à jour pour la dernière fois le 09/06/2026 UTC ; pour le niveau payant Standard de gemini-3.5-flash, le prix indiqué est de $1.50 / 1M tokens en entrée et $9.00 / 1M tokens en sortie, le prix de sortie incluant les thinking tokens ; en Batch, les tarifs sont $0.75 en entrée et $4.50 en sortie (Tarifs de l’API Gemini).

Modèle	Statut	Limite d’entrée	Entrée Standard	Sortie Standard
gemini-3.5-flash	Stable	1,048,576	$1.50 / 1M tokens	$9.00 / 1M tokens
gemini-3-flash-preview	Preview	Voir la page du modèle	$0.50 / 1M tokens	$3.00 / 1M tokens
gemini-3.1-flash-lite	Stable	Voir la page du modèle	$0.25 / 1M tokens	$1.50 / 1M tokens

gemini-3-flash-preview et gemini-3.1-flash-lite proviennent des pages actuelles des modèles et des prix de Google (Modèles, Tarifs). N’utilisez pas directement un modèle Preview comme valeur par défaut en production : la version et les quotas peuvent changer.

Python : pointer le client OpenAI vers Gemini

Installez d’abord le SDK :

pip install openai
export GEMINI_API_KEY="你的 Gemini API Key"

Conservez ensuite le mode d’appel du SDK OpenAI :

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["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": "用三句话解释什么是 API 兼容层。"},
    ],
)

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

Il n’y a en réalité que trois changements : remplacer api_key par la clé Gemini, remplacer base_url par l’endpoint OpenAI-compatible de Google, et remplacer model par le nom du modèle Gemini. Notez que l’URL de l’exemple officiel se termine par / ; ne la supprimez pas par réflexe pour devoir ensuite diagnostiquer un 404.

TypeScript : même principe avec baseURL

Dans un projet Node, c’est la même chose :

npm install openai
export GEMINI_API_KEY="你的 Gemini API Key"

import OpenAI from "openai";

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

const response = await openai.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [
    { role: "user", content: "给我一个 JSON Schema 校验的最小例子。" },
  ],
});

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

Si votre projet a déjà encapsulé le provider dans des variables d’environnement, le changement sera encore plus réduit :

OPENAI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
OPENAI_API_KEY="$GEMINI_API_KEY"
OPENAI_MODEL="gemini-3.5-flash"

C’est ici que beaucoup d’anciens projets se piègent : peu importe que la variable s’appelle encore OPENAI_API_KEY, sa valeur peut être une clé Gemini ; ce qui détermine réellement où part la requête, c’est base_url/baseURL.

Que faire du streaming, des appels d’outils et du thinking

La documentation de compatibilité de Google fournit des exemples pour le streaming, le function calling, les structured outputs, la compréhension d’images, etc. (Compatibilité OpenAI). Pour un projet qui utilise déjà le SDK OpenAI, on valide généralement d’abord trois points : le chat classique, stream=True, puis les tools/function calling. Une fois ces éléments validés, on traite ensuite les capacités propres au modèle.

Les paramètres de thinking doivent être manipulés avec prudence. La documentation de compatibilité indique que le reasoning_effort d’OpenAI est mappé vers la configuration de thinking de Gemini ; mais Gemini 3 et certains modèles 2.5 ne permettent pas de désactiver complètement le thinking. Mon conseil est simple : dans une première version, ne touchez pas au thinking ; établissez d’abord une base de référence de qualité et de coût avec les valeurs par défaut, puis effectuez des tests de charge séparés pour les tâches longues, les agents de code et les chaînes de raisonnement complexes.

Si vous voulez gérer moins de clés

La connexion directe officielle convient à une production sérieuse : facturation, quotas et politiques de données sont clairs. Le problème, c’est qu’une équipe n’utilise souvent pas seulement Gemini, mais aussi Claude, GPT, voire des clés différentes pour différents outils. La voie la plus simple consiste à utiliser onehop : remplacer la base URL du SDK OpenAI par https://api.onehop.ai/v1, puis appeler Claude/GPT/Gemini via la même entrée compatible OpenAI/Anthropic ; les nouveaux comptes reçoivent $10, sans carte bancaire, ce qui est pratique pour lancer d’abord une démo ou des outils internes.

import os
from openai import OpenAI

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

resp = client.chat.completions.create(
    model=os.environ["ONEHOP_MODEL"],
    messages=[{"role": "user", "content": "把这段日志总结成 5 条排障线索。"}],
)

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

Ici, j’ai volontairement placé model dans une variable d’environnement : les noms de modèles du gateway doivent être ceux indiqués dans la console, ne les codez pas en dur. Si vous voulez moins vous battre avec la facturation multi-fournisseurs et les couches de compatibilité, vous pouvez essayer directement : appeler Claude et d’autres modèles sur onehop, ou commencer par récupérer du crédit : 10 $ de crédit d’essai offerts à l’inscription.

Dernières vérifications avant l’intégration

Avant la mise en production, ne vous contentez pas de vérifier que du texte est renvoyé. Faites au minimum quatre contrôles : premièrement, confirmez que le modèle est toujours disponible sur la page actuelle des modèles de Google ; deuxièmement, vérifiez sur la page des prix les coûts d’entrée, de sortie, de Batch et de Search grounding ; troisièmement, journalisez intégralement les erreurs 401, 429 et 5xx ; quatrièmement, rendez base_url, api_key et model configurables à l’exécution, afin de ne pas devoir publier une nouvelle version pour changer de modèle.

L’enjeu de cette intégration n’est pas de « changer de fournisseur de modèles », mais de découpler la couche SDK du fournisseur de modèles. Commencez par faire fonctionner gemini-3.5-flash via la compatibilité OpenAI officielle de Google, puis décidez entre connexion directe, gateway, ou coexistence des deux. Les changements restent ainsi limités, et le rollback est rapide.