Utiliser Gemini avec le SDK OpenAI via des endpoints compatibles

Vous pouvez appeler Gemini depuis le SDK OpenAI officiel en définissant base_url sur l'endpoint compatible OpenAI de Google (ou sur une passerelle AI qui front Gemini), en vous authentifiant avec une clé Gemini ou une clé de passerelle, et en sélectionnant un ID de modèle Gemini dans une requête chat.completions normale. Google documente ce chemin dans le guide de compatibilité OpenAI Gemini. Les équipes déjà standardisées sur le client OpenAI peuvent évaluer Gemini sans réécrire chaque intégration.

Google précise aussi que si vous n'utilisez pas déjà les bibliothèques OpenAI, l'appel direct à l'API Gemini reste le choix recommandé pour accéder à toutes les fonctions. La compatibilité est un pont de migration et d'évaluation, pas la promesse que chaque surface OpenAI existe sur Gemini.

Pourquoi la compatibilité OpenAI accélère les essais de Gemini

De nombreuses bases de code dépendent déjà du paquet openai, de modèles de chat LangChain/OpenAI, ou de clients HTTP pour /v1/chat/completions. Forcer chaque expérience vers le SDK Gemini natif multiplie les helpers d'auth, les parseurs de streaming et la gestion d'erreurs. La compatibilité permet de :

• garder un seul constructeur de requête et parseur de réponse
• A/B tester Gemini sur du trafic en forme OpenAI
• déplacer les credentials derrière une passerelle tout en gardant les clients simples
• réutiliser les mêmes schémas d'outils d'agents pendant l'évaluation précoce

La compatibilité reste une couche de traduction. Google décrit la prise en charge des bibliothèques OpenAI comme encore en expansion, avec certaines surfaces en version bêta. Lisez la section actuelle des limitations avant de promettre la parité lors d'une revue de conception.

Configuration client minimale

Endpoint Google direct compatible OpenAI

Le modèle Python documenté par Google utilise le chemin de base compatible OpenAI de Generative Language. Les exemples officiels utilisent actuellement gemini-3.5-flash :

from openai import OpenAI
import os

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.5-flash",
    messages=[
        {"role": "system", "content": "Answer with concrete engineering guidance."},
        {
            "role": "user",
            "content": "When should a team try Gemini through an OpenAI client?",
        },
    ],
)

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

TypeScript :

import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [
    { role: "system", content: "Answer with concrete engineering guidance." },
    {
      role: "user",
      content: "When should a team try Gemini through an OpenAI client?",
    },
  ],
});

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

Les identifiants de modèles évoluent. Préférez la liste des modèles de Google plutôt que de figer d'anciens instantanés Flash ou Pro dans les configurations de production.

Chemin passerelle pour produits multi-fournisseurs

client = OpenAI(
    api_key="GATEWAY_API_KEY",
    base_url="https://your-gateway.example.com/v1",
)

response = client.chat.completions.create(
    model="gemini-flash",  # stable alias mapped to gemini-3.5-flash (or successor)
    messages=[{"role": "user", "content": "Draft a checklist for model A/B tests."}],
)

Enregistrez une fois l'identifiant Gemini amont comme canal, publiez l'alias dans votre catalogue de modèles et limitez les secrets applicatifs aux clés de passerelle. C'est le même modèle opérationnel que celui des passerelles API compatibles OpenAI.

Alias stables et identifiants amont bruts

Les configurations applicatives doivent dépendre d'alias contrôlés par les opérateurs :

1. Publiez des noms comme gemini-flash et gemini-pro, ou des libellés propres au produit.
2. Associez ces alias aux identifiants amont actuels (gemini-3.5-flash, un identifiant de classe Pro, etc.).
3. Ne modifiez que cette association lorsque Google livre un modèle de remplacement.
4. Exécutez une courte suite de régression après chaque changement d'association.

Cela limite les PR côté client et transforme le retour arrière en modification de configuration. Associez cette discipline d'alias au routage des modèles selon la latence et le coût afin que le placement Flash ou Pro reste une décision produit explicite.

Fonctionnalités testées en premier

Chat simple et historique multi-tours

Commencez par un chat sans streaming et une suite d'évaluation fixe. Confirmez :

• le respect des instructions système
• la conservation du contexte multi-tour
• la conformité de la troncature avec max_tokens aux attentes produit
• la gestion des refus et des réponses vides par l'interface

Streaming

La plupart des produits de chat consomment déjà les flux du SDK OpenAI. Lorsque vous activez le streaming pour Gemini :

• mesurez séparément le délai jusqu'au premier token et la durée totale
• décidez ce que l'interface affiche si le flux se termine par un bloc d'erreur
• évitez la bascule silencieuse après l'affichage de tokens

Les règles de fiabilité pour les erreurs en début ou en milieu de flux appartiennent à votre stratégie de bascule des API LLM, pas à des retentatives improvisées dans le client.

Outils et appel de fonctions

La surface compatible OpenAI de Gemini prend en charge les outils pour de nombreux workflows d'agents :

tools = [
    {
        "type": "function",
        "function": {
            "name": "search_docs",
            "description": "Search internal engineering docs",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string"},
                    "limit": {"type": "integer"},
                },
                "required": ["query"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[{"role": "user", "content": "Find runbooks for gateway failover."}],
    tools=tools,
    tool_choice="auto",
)

Validez les noms d'outils contre une liste d'autorisation et les arguments avec JSON Schema ou Pydantic avant tout effet de bord. Les détails de portabilité et la matrice d'incompatibilité figurent dans les appels d'outils portables entre fournisseurs.

Mappage de la réflexion et de l'effort de raisonnement

Les modèles Gemini peuvent exposer la configuration du raisonnement au moyen de champs compatibles OpenAI. Les modèles Gemini ne mappent pas tous l'effort de raisonnement de la même manière ; consultez le tableau actuel de Google lorsque vous réglez l'intensité de réflexion. Une passerelle peut aussi accepter des suffixes d'effort sur les alias pour les clients qui ne peuvent définir qu'une chaîne de modèle. Traitez-les comme des facilités opérateur et documentez l'effort associé à chaque alias.

Embeddings et endpoints adjacents

Les embeddings et les workflows multimédias nécessitent souvent des vérifications d'endpoint séparées. La page de compatibilité OpenAI de Google présente d'abord les exemples orientés chat ; l'envoi ou le téléchargement de fichiers dans certains traitements par lots peut encore exiger le client Google natif. Vérifiez chaque surface adjacente avec son propre curl avant d'affirmer que « tout le SDK OpenAI fonctionne ».

Limitations et décalages à budgéter

Construisez une liste explicite des écarts de votre produit, pas une note vague disant « tout tester » :

• paramètres OpenAI non pris en charge ou supprimés silencieusement
• différences d'encodage des parties multimodales, surtout les images et l'audio
• cas limites de l'appel d'outils : appels parallèles, objets d'arguments vides, dérive des énumérations
• filtres de sécurité renvoyant des formes de refus différentes d'OpenAI
• écarts bêta encore répertoriés par Google dans les limitations actuelles
• différences d'en-têtes de limitation et d'erreur

Lorsqu'une requête renvoie 400 sur Gemini après avoir réussi sur OpenAI, retirez les champs propres à OpenAI un par un et journalisez le corps d'erreur brut. Ne « corrigez » pas l'échec en interceptant toutes les exceptions puis en retentant un autre fournisseur au milieu du flux.

Plan d'évaluation sans fausse confiance

1. Figez une suite de 20 à 50 prompts avec les noms d'appels d'outils attendus lorsque c'est pertinent.
2. Exécutez-la sur votre modèle par défaut actuel et sur gemini-3.5-flash, ou votre alias Pro.
3. Notez séparément la validité des schémas, l'invocation obligatoire des outils et la qualité de la prose.
4. Mesurez les latences p50/p95 et le coût par tâche réussie.
5. Modifiez seulement ensuite la politique de routage. Si Gemini gagne en latence mais perd en validité de schéma, ne lui confiez que les workflows qui tolèrent un texte plus libre.

Contrôles curl avant le code applicatif

curl https://your-gateway.example.com/v1/chat/completions \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-flash",
    "messages": [
      {"role": "user", "content": "Reply with the single word ready."}
    ]
  }'

Pour un test direct sur un poste local, remplacez l'hôte par https://generativelanguage.googleapis.com/v1beta/openai/ et utilisez une clé API Gemini. Préférez le chemin de la passerelle dans les environnements partagés afin de ne pas copier les identifiants sur chaque poste.

Exploiter Gemini comme un canal

Dans une flotte multi-fournisseurs, Gemini doit ressembler à n'importe quel autre canal :

• credentials stockées côté serveur
• alias revus quand Google renomme ou retire des IDs
• rate limits et budgets par équipe ou produit
• santé et taux d'erreur visibles à côté des autres fournisseurs
• contexte tarifaire revu lorsque le routage par défaut change

C'est ainsi que les passerelles LLM multi-fournisseurs restent exploitables : Gemini est une cible de routage, pas une seconde architecture applicative.

Sécurité et hygiène des clés

• N'incorporez jamais de clés Gemini dans navigateurs ou apps mobiles.
• Préférez des clés de passerelle à moindre privilège par service.
• Journalisez les arguments d'outils avec prudence.
• Revoyez les conseils OWASP LLM quand les agents appellent des outils externes automatiquement.

Séquence de migration

1. Activer un canal Gemini et vérifier /v1/chat/completions avec curl.
2. Pointer un service non critique vers l'alias Gemini.
3. Exécuter la suite d'évaluation et comparer les taux de succès schéma/outils.
4. Ajouter les clients streaming.
5. Ajouter des agents tools avec validation serveur des arguments.
6. Décider placement épinglé, canary ou bascule.
7. Documenter l'alias de rollback avant d'élargir le trafic.

Sources officielles

• Compatibilité OpenAI de l'API Gemini
• Modèles de l'API Gemini
• Référence OpenAI Chat Completions
• Guide OpenAI de l'appel de fonctions

Dernière vérification : 2026-07-15. Confirmez les identifiants de modèles, les chemins d'endpoint et les tableaux de limitations dans la documentation Google avant de figer le routage de production.

Questions fréquentes

L'endpoint compatible OpenAI de Gemini est-il un clone OpenAI complet ?

Non. C'est une couche de compatibilité pour les workflows courants des clients OpenAI. Certains endpoints, paramètres et comportements diffèrent. Consultez les limitations Google pour les fonctions dont vous dépendez. Google recommande encore l'API Gemini native si vous n'êtes pas déjà investi dans les bibliothèques OpenAI.

Dois-je utiliser Gemini via la base URL de Google ou une passerelle ?

Utilisez la base URL de Google pour des expériences locales rapides. Utilisez une passerelle lorsque plusieurs services, équipes, fournisseurs, budgets ou exigences d'audit sont concernés.

Par quel modèle Gemini commencer ?

Commencez par l'identifiant de classe Flash actuel dans la documentation Google — au moment de la rédaction, les exemples utilisent gemini-3.5-flash — pour les évaluations sensibles à la latence, et par un modèle de classe Pro pour le raisonnement ou les outils plus exigeants. Associez-les à des alias stables de passerelle plutôt que de disperser les identifiants bruts dans les configurations.

Puis-je garder les mêmes schémas d'outils qu'avec OpenAI ?

Souvent oui pour les ports initiaux, mais validez chaque schéma. Les appels parallèles, le JSON strict et l'encodage des arguments limites demandent des tests explicites sur Gemini.

Premier canari Gemini

Créez ou sélectionnez un canal Gemini, appelez /v1/chat/completions avec le SDK OpenAI via votre passerelle, puis exécutez une évaluation fixe de 20 prompts comprenant au moins un appel d'outil. Comparez le succès des schémas et la latence à votre modèle par défaut actuel, puis décidez si Gemini devient le modèle par défaut, le canari ou la cible de bascule pour ce workflow.