Si votre équipe utilise déjà CC Switch ou un plan de contrôle de type NewAPI, la manière la plus rapide d’activer Gemini n’est pas d’ajouter encore une autre clé de fournisseur partout. Il s’agit de définir une route amont, une règle de nommage des modèles, une vérification d’usage et un point de contrôle de revue de production avant le déploiement.
Google documente désormais l’accès à Gemini via les bibliothèques OpenAI en modifiant la clé API, l’URL de base et le nom du modèle. Pour un accès direct à Gemini, l’URL de base compatible OpenAI est https://generativelanguage.googleapis.com/v1beta/openai/. Pour les équipes qui veulent une couche opérationnelle unique sur Gemini et d’autres fournisseurs, Flatkey expose une route unique compatible OpenAI à https://router.flatkey.ai/v1, et le texte actuel de la page d’accueil met l’accent sur une clé, une URL de base et la conservation de votre SDK existant.
Ce guide est destiné aux applications de production, pas aux démos de loisir. L’objectif est de vous aider à intégrer Gemini d’une manière qui puisse être examinée par les équipes d’ingénierie, d’exploitation et de sécurité avant le basculement du trafic.
Réponse rapide : que doit-on changer en production ?
Pour un déploiement de l’API Gemini en production, verrouillez cinq éléments avant d’enregistrer l’amont :
| Élément | Configuration directe Gemini | Configuration avec une passerelle unique pour les clients de type CC Switch ou NewAPI |
|---|---|---|
| Source d’authentification | Clé API Gemini provenant de Google AI Studio ou d’un projet Google Cloud importé | Une clé de passerelle unique gérée à un seul endroit |
| URL de base | https://generativelanguage.googleapis.com/v1beta/openai/ | https://router.flatkey.ai/v1 |
| Mode de protocole | Compatible OpenAI | Compatible OpenAI |
| Politique de modèle | Liste approuvée de modèles Gemini | Liste approuvée de modèles Gemini plus politique de repli inter-fournisseurs |
| Vérification | Contrôles d’usage et de facturation côté Google | Journal des requêtes de la passerelle, quota, mappage des modèles et revue en aval |
Si votre application prend déjà en charge des upstreams compatibles OpenAI, Gemini relève généralement d’un travail de routage et de politique, et non d’une réécriture complète du SDK.
Pourquoi cette liste de contrôle est importante le vendredi 17 juillet 2026
Trois faits actuels rendent une liste de contrôle de production plus importante qu’un démarrage rapide :
- La documentation Gemini de Google prend désormais explicitement en charge l’accès via les bibliothèques OpenAI, ce qui permet aux équipes de changer de point de terminaison sans renforcer la discipline de revue.
- Google indique également que les nouvelles clés AI Studio sont créées par défaut comme clés d’authentification et que les clés standard seront rejetées en septembre 2026, donc le type de clé et la propriété du projet font partie de la décision de déploiement.
- Le langage de configuration public en direct de Flatkey met l’accent sur une clé, une URL de base et la conservation du SDK existant, ce qui n’est utile que si l’équipe standardise aussi le mappage des champs, la journalisation et le retour arrière.
Avant de commencer
N’ouvrez pas CC Switch ou NewAPI en premier. Commencez par le contrat que vous souhaitez voir respecté par l’amont.
Utilisez cette liste de prévol minimale :
| Vérification | Ce qu’il faut confirmer | Pourquoi c’est important |
|---|---|---|
| Responsable | L’équipe sait qui est responsable de la création, de la rotation et du quota de la clé Gemini | Évite la dérive des comptes partagés |
| Type de route | Vous utilisez un upstream compatible OpenAI, et non un adaptateur personnalisé mixte | Garde le mappage des champs simple |
| Liste des modèles | Vous disposez d’une liste approuvée des ID de modèles Gemini pour cette application | Empêche la dérive silencieuse des alias |
| Journalisation | Vous savez où auront lieu l’examen des journaux de requêtes, de l’utilisation et de la facturation | Nécessaire pour les preuves de bascule |
| Retour arrière | Vous pouvez revenir rapidement à l’upstream ou à la politique de modèle précédente | Requis pour un déploiement progressif |
Si vous n’avez pas ces réponses, vous n’êtes pas prêt à considérer la configuration comme prête pour la production.
Mappage des champs pour les upstreams de type CC Switch ou NewAPI
Différents clients utilisent des libellés de champs différents, mais le mappage de production doit rester cohérent.
| Champ upstream | Valeur pour ce déploiement | Note de revue |
|---|---|---|
| Type de fournisseur | Compatible OpenAI | Utilisez le mode générique compatible OpenAI, sauf si le client dispose d’un mode Gemini natif validé que vous comptez exploiter |
| Clé API | Clé Flatkey ou clé upstream approuvée | Conservez-la dans une seule source de secret, et non dans des copies locales par utilisateur |
| URL de base | https://router.flatkey.ai/v1 | Utilisez une seule route pour un contrôle centralisé |
| Source du modèle | Liste d’autorisation manuelle ou récupération après l’enregistrement de la route | Examinez les ID de modèles retournés avant de les exposer à l’application |
| Modèle par défaut | Modèle Gemini de production approuvé | Ne pointez pas la production vers un modèle de préversion par accident |
| Modèle de secours | Optionnel et délibéré | Activez-le uniquement après le passage des vérifications de nommage des modèles et des journaux |
| En-têtes | Authentification bearer standard, sauf si votre client documente des champs supplémentaires | Évitez les contournements d’en-tête ponctuels qui cassent la portabilité |
| Examen de l’utilisation | Journal des requêtes et tableau de bord des quotas ou de facturation | Doit faire partie de la validation finale |
C’est la principale différence opérationnelle entre une configuration Gemini directe et une configuration via passerelle : l’itinéraire via passerelle réduit la dispersion des identifiants, mais il accroît le besoin d’une porte de revue claire, car davantage d’applications peuvent hériter du même upstream.
Étape 1 : décider si cette application a besoin de Gemini direct ou d’une seule passerelle
Utilisez Gemini direct si l’application est isolée, que le responsable est clairement identifié et que vous n’avez pas besoin pour l’instant de routage inter-fournisseurs.
Utilisez une seule passerelle si l’un des cas suivants est vrai :
- Le même client touche déjà plusieurs fournisseurs.
- Plus d’un ingénieur ou d’une équipe gérera l’intégration.
- Vous voulez un seul endroit pour vérifier l’utilisation, les quotas ou les journaux de requêtes.
- Vous prévoyez une substitution de modèle, un mode de secours ou une extension du fournisseur plus tard.
Pour les équipes de type CC Switch et NewAPI, la deuxième voie est généralement plus simple à maintenir dans le temps, car le client conserve une forme compatible avec OpenAI tandis que la politique de routage reste en amont.
Étape 2 : verrouillez les identifiants exacts des modèles Gemini que vous autoriserez
N’utilisez pas « Gemini » comme exigence vague. Validez des identifiants de modèle exacts pour cette application et cet environnement.
Cette revue doit répondre aux questions suivantes :
- Quel modèle Gemini est la valeur par défaut en production ?
- Quels modèles ne sont autorisés qu’à des fins de test ?
- Les modèles de préversion sont-ils autorisés en production, oui ou non ?
- L’application exposera-t-elle un sélecteur de modèle ou un modèle fixe ?
- Si le fallback est activé, quels modèles non Gemini sont autorisés et dans quelles conditions ?
C’est là que de nombreuses équipes créent des incidents évitables. Elles enregistrent correctement le service en amont, puis laissent les noms de modèles suffisamment flous pour que les comportements de test et de production diffèrent.
Si vous avez besoin d’aide pour aligner les noms de modèles une fois la route en service, consultez le guide existant Migration d’API compatible OpenAI avant d’exposer l’intégration aux utilisateurs.
Étape 3 : enregistrez un seul service en amont et exécutez un test de fumée avant la récupération des modèles
Après avoir saisi la clé API et l’URL de base, effectuez un test de fumée avant d’importer ou d’exposer la liste complète des modèles.
Votre test de fumée doit confirmer :
| Test | Résultat attendu |
|---|---|
| Auth | Le service en amont accepte la clé sans erreur d’identifiants locaux |
| Route | Une simple requête de complétion de chat renvoie une réponse depuis l’URL de base configurée |
| Modèle | L’identifiant exact du modèle Gemini est résolu avec succès |
| Journalisation | Vous pouvez retrouver la requête dans l’interface de revue que vous avez choisie |
| Facturation ou quota | La requête est visible à l’endroit où l’équipe s’attend à voir les preuves d’utilisation |
Pour les équipes qui standardisent sur une seule passerelle, cela compte plus que la récupération de modèles. Récupérer une liste de modèles prouve que le client peut voir des noms. Cela ne prouve pas que le chemin des requêtes de production est révisable.
Étape 4 : examinez le type de clé et la propriété du projet
Cette étape est facile à sauter parce que la requête peut déjà fonctionner.
Les consignes actuelles de Google sur les clés sont la raison de ne pas la sauter. Google AI Studio crée désormais des clés d’authentification par défaut, les clés standards non restreintes sont déjà davantage restreintes, et Google indique que l’API Gemini rejettera les clés standards en septembre 2026. Cela signifie que les équipes de production doivent considérer le type de clé comme faisant partie de la préparation au déploiement, et non comme une tâche de nettoyage ultérieure.
Utilisez cette courte revue :
| Question | Réponse acceptable |
|---|---|
| Qui possède le projet Gemini ? | Propriétaire ou équipe nommés |
| Quel type de clé est utilisé ? | Clé d’authentification préférée pour les nouvelles configurations de production |
| Où la clé est-elle stockée ? | Gestionnaire de secrets centralisé ou secret de plateforme contrôlé |
| Comment sera-t-elle renouvelée ? | Propriétaire et processus documentés |
| Que se passe-t-il si l’utilisation augmente soudainement ? | Une alerte de facturation ou un parcours de revue des quotas existe |
Si vous centralisez via une seule passerelle, effectuez la même vérification pour la clé de la passerelle et le compte du fournisseur en aval.
Étape 5 : décider si l’application doit exposer Gemini directement aux utilisateurs
Ne supposez pas que la réponse est oui.
Dans de nombreuses applications de production, la meilleure approche est la suivante :
- Router d’abord Gemini en amont.
- Valider les journaux, la latence et la revue de l’utilisation.
- Conserver le modèle derrière un indicateur de fonctionnalité ou une allowlist interne.
- Ne l’exposer aux utilisateurs finaux qu’après validation du point de contrôle de revue.
Cela est particulièrement utile dans les environnements de type CC Switch et NewAPI, où un seul changement de configuration peut affecter plusieurs opérateurs ou chemins de l’application.
Étape 6 : ajouter un point de contrôle de revue en production
C’est la partie que la plupart des guides de configuration omettent. Avant que le trafic ne bascule, exigez un bref point de contrôle de revue qu’une personne puisse approuver en une seule fois.
Utilisez exactement cette liste de contrôle :
| Élément du point de contrôle de revue | Condition de validation |
|---|---|
| Mappage des champs | La source de la clé API, l’URL de base, le mode du fournisseur et le modèle par défaut sont documentés |
| Preuve du test de fumée | Une requête réussie est enregistrée avec le routage final |
| Allowlist des modèles | Seuls les identifiants de modèles Gemini approuvés sont disponibles pour l’application |
| Visibilité de l’utilisation | Le chemin de revue des journaux de requêtes ou de la facturation est confirmé |
| Propriété du secret | Le propriétaire de la clé et le chemin de rotation sont nommés |
| Retour arrière | La politique précédente du fournisseur amont ou du modèle peut être restaurée rapidement |
| Périmètre | L’équipe sait si ce changement concerne une application, un espace de travail ou plusieurs clients |
C’est le document de configuration le plus court qui protège malgré tout le déploiement.
Étape 7 : décider comment le repli doit fonctionner avant de l’activer
Si vous utilisez une seule passerelle, la tentation est d’activer immédiatement le repli. Ne le faites pas, à moins de pouvoir répondre à deux questions :
- Quelle condition d’échec doit déclencher le repli ?
- Le comportement du modèle de repli est-il acceptable pour la même tâche côté utilisateur ?
Pour les déploiements de production Gemini, le repli est souvent plus sûr après le premier basculement, pas pendant celui-ci. Prouvez d’abord le chemin principal, puis ajoutez le repli avec sa propre preuve de test.
Étape 8 : valider le routage depuis l’application, pas seulement depuis un script local
Un test curl local est nécessaire. Il n’est pas suffisant.
Exécutez une validation depuis le vrai chemin de l’application et confirmez :
- L’application utilise le fournisseur amont prévu.
- Le modèle renvoyé est le modèle Gemini attendu.
- L’observabilité affiche la même requête.
- Tout comportement de délai d’attente, de nouvelle tentative ou de quota au niveau de l’application fonctionne toujours.
C’est là que les problèmes de production apparaissent lorsque l’application a d’anciennes variables d’environnement, des noms de modèles mis en cache ou une source de secret différente de celle de l’ingénieur qui a exécuté le premier test.
Déploiement recommandé pour les équipes de type CC Switch et NewAPI
Utilisez un déploiement progressif qui garde le plan de contrôle simple :
- Ajoutez un seul upstream compatible OpenAI et capable de gérer Gemini.
- Testez un modèle Gemini approuvé.
- Confirmez les journaux et l’examen de l’utilisation.
- Exposez le modèle aux utilisateurs internes uniquement.
- Ajoutez un mécanisme de secours uniquement après stabilisation du chemin principal.
- Étendez à davantage d’applications uniquement après que la première application a passé le portail de validation.
Le message de routage en direct de Flatkey est utile ici, car la même URL de base peut rester en place tandis que votre politique de modèle devient plus stricte au fil du temps. Si vous comparez l’impact sur les coûts ou les achats avant le déploiement, la page de tarification en direct est la prochaine étape à consulter.
Document de configuration court que vous pouvez approuver en interne
Si vous souhaitez un transfert révisable, copiez cette structure dans votre note de configuration interne :
| Champ | Valeur |
|---|---|
| Nom de l’application | |
| Responsable de l’upstream | |
| Mode du fournisseur | Compatible OpenAI |
| URL de base | https://router.flatkey.ai/v1 |
| Source de la clé API | |
| Identifiants de modèles Gemini approuvés | |
| Secours activé | Oui ou Non |
| Surface d’examen de l’utilisation | |
| Surface d’examen de la facturation ou du quota | |
| Action de retour arrière | |
| Examinateur | |
| Date d’approbation |
Cela suffit à fournir une structure permettant d’approuver un déploiement Gemini sans transformer la configuration en long mémo d’architecture.
Si votre équipe utilise aussi Claude Code dans le même plan de contrôle, l’article en direct CC Switch Claude Code setup with Flatkey and NewAPI est un compagnon utile, car il montre le même schéma opérationnel du côté client.
FAQ
Quel est le schéma d’URL de base le plus sûr pour un déploiement Gemini en production dans un client compatible OpenAI ?
Le schéma le plus sûr est une URL de base examinée par environnement. Pour un accès direct à Gemini, Google documente https://generativelanguage.googleapis.com/v1beta/openai/. Pour un déploiement via une passerelle centralisée, utilisez la route unique de passerelle approuvée et gardez cette valeur sous contrôle de configuration.
Dois-je utiliser un identifiant Gemini distinct pour chaque client CC Switch ou NewAPI ?
En général non. Pour les équipes de production, une source de secret contrôlée est plus sûre que des identifiants locaux dispersés. Le compromis est que vous devez ajouter un portail de validation, car davantage de clients peuvent hériter de la même route.
Dois-je remplacer mon SDK pour utiliser Gemini dans une application compatible OpenAI ?
En général non. La documentation actuelle de Gemini de Google prend explicitement en charge les bibliothèques OpenAI en modifiant la clé, l’URL de base et le nom du modèle. Le vrai travail consiste à valider la politique de routage, la dénomination des modèles, la journalisation et la responsabilité.
Qu’est-ce qui a changé concernant les clés API Gemini en 2026 ?
À compter du vendredi 17 juillet 2026, Google AI Studio crée par défaut de nouvelles clés en tant que clés d’authentification, avertit que les clés standard sans restriction ne sont pas acceptables pour une utilisation à long terme, et indique que l’API Gemini rejettera les clés standard en septembre 2026. Les équipes doivent vérifier le type de clé avant la mise en production.
Quand dois-je activer le fallback pour Gemini ?
Une fois que le trajet principal Gemini est stable. Vérifiez d’abord un modèle Gemini approuvé via le chemin final de l’application. Ajoutez ensuite le fallback uniquement si la condition de déclenchement et le comportement du modèle de secours sont acceptables pour le même flux de travail.
Que dois-je inspecter avant d’approuver le document de configuration ?
Inspectez l’URL de base exacte, la source de la clé, les ID des modèles Gemini approuvés, un journal de requête réussie, l’interface d’examen de l’utilisation et l’action de retour arrière. Si l’un de ces éléments manque, la configuration n’est pas prête pour une approbation en production.
