Si votre application utilise déjà une API compatible avec OpenAI, le passage à Flatkey ne devrait pas commencer par une réécriture. La voie contrôlée est plus simple : obtenez une clé Flatkey, pointez votre SDK compatible OpenAI vers https://router.flatkey.ai/v1, choisissez un identifiant de modèle dans le catalogue Flatkey, puis vérifiez la première requête dans les journaux, les quotas et la facturation avant d’envoyer du trafic réel.
C’est la valeur pratique d’une API compatible avec OpenAI. Elle permet à une équipe de conserver le même modèle mental pour les requêtes courantes tout en plaçant l’accès au fournisseur derrière une passerelle unique. Le texte produit public de Flatkey est conçu autour de ce fonctionnement : une clé API, une URL de base, une tarification claire, une facturation unifiée et un tableau de bord unique pour les clés, l’utilisation et le routage.
Ce guide présente le plan de migration. Il couvre le changement d’URL de base, des exemples de SDK, le mappage des identifiants de modèle, les tests de fumée, les vérifications d’endpoint, l’examen des journaux d’utilisation, la configuration des quotas, la vérification de la facturation et le retour arrière. Utilisez-le lorsque vous déplacez un flux de travail Chat Completions existant vers Flatkey ou que vous standardisez une pile multi-modèles derrière un seul endpoint API compatible avec OpenAI.
Réponse rapide : qu’est-ce qui change lors d’une migration vers une API compatible OpenAI ?
Pour la plupart des clients de chat existants compatibles OpenAI, la première migration est un changement de configuration, pas une réécriture de l’application.
| Paramètre | Avant | Avec Flatkey |
|---|---|---|
| Clé API | Clé spécifique au fournisseur OpenAI, Gemini, DeepSeek ou proxy | Clé API Flatkey |
| URL de base | Valeur par défaut du fournisseur ou autre URL de base compatible OpenAI | https://router.flatkey.ai/v1 |
| Point de terminaison du chat | /v1/chat/completions |
/v1/chat/completions via Flatkey |
| Modèle | ID de modèle du fournisseur existant | ID de modèle Flatkey sélectionné à partir de la tarification/du tableau de bord |
| Validation | Uniquement une réponse réussie | Réponse + journal d’utilisation + coût + quota + retour arrière |
Le mot important est « compatible ». Une API compatible OpenAI ne garantit pas que chaque fournisseur, modèle, point de terminaison et paramètre se comporte exactement comme OpenAI. Cela signifie que l’API suit suffisamment le schéma de requête et de réponse d’OpenAI pour que les appels clients courants fonctionnent lorsque l’URL de base, la clé et le modèle sont corrects. Votre checklist de migration doit prouver les fonctionnalités exactes que votre application utilise.
Pourquoi les points de terminaison compatibles OpenAI deviennent la couche de migration
Les résultats de recherche pour API compatible OpenAI sont principalement des références officielles, des documentations de fournisseurs, des plugins, des documentations de serveurs locaux et des questions de la communauté. Cela a du sens. Les développeurs ne demandent pas seulement « qu’est-ce qui est compatible ? » Ils cherchent à déplacer du code entre des fournisseurs de modèles sans modifier chaque point d’appel.
La documentation de Gemini de Google montre des exemples de bibliothèque OpenAI qui définissent une URL de base OpenAI compatible Gemini et appellent les complétions de chat. La documentation officielle de l’API de DeepSeek montre des exemples du SDK OpenAI avec l’URL de base de DeepSeek et des identifiants de modèle tels que deepseek-chat et deepseek-reasoner. Le schéma est clair : de nombreux fournisseurs vont à la rencontre des développeurs là où se trouvent déjà leurs SDK existants.
Flatkey utilise la même idée de migration pour un objectif différent. Au lieu de pointer l’API compatible OpenAI d’un fournisseur vers le compte d’un seul fournisseur, Flatkey offre aux équipes une seule URL de base compatible OpenAI pour un accès à plusieurs modèles, une facturation unifiée et une visibilité via le tableau de bord.
Étape 1 : Inventoriez le client que vous avez déjà
Avant de modifier l’URL de base, notez ce que votre application actuelle utilise réellement. Une migration propre vers une API compatible OpenAI commence par la forme de l’appel en production, pas par une nouvelle application d’exemple.
| Vérification | Ce qu’il faut consigner |
|---|---|
| SDK | Python, Node, HTTP direct, LangChain, LiteLLM, Vercel AI SDK, ou un autre wrapper. |
| Point de terminaison | Chat Completions, Responses, embeddings, images, vidéo, ou point de terminaison natif du fournisseur. |
| ID du modèle | Chaîne exacte utilisée en production et tout modèle de secours. |
| Forme des messages | Prompts système, messages développeur, messages d’outil, contenu multimodal, ou texte brut uniquement. |
| Paramètres | Streaming, température, nombre maximal de tokens, appels d’outils, sortie JSON, format de réponse, seed, délai d’attente, retries. |
| Observabilité | Où vous voyez aujourd’hui la latence, l’utilisation des tokens, les IDs de requête, les erreurs et le coût. |
| Retour arrière | À quelle vitesse vous pouvez rétablir l’ancienne clé API/l’URL de base/le modèle. |
Cet inventaire permet de garder la migration réaliste. Si votre application n’envoie que de simples messages de chat, le premier test Flatkey peut rester léger. Si votre application dépend du streaming, des appels d’outils, du mode JSON, des images, de la vidéo ou de l’API Responses, traitez chaque fonctionnalité comme un test de fumée distinct.
Étape 2 : placez l’URL de base derrière une couche de configuration
Ne dispersez pas la nouvelle URL de base compatible OpenAI dans toute la base de code. Placez-la dans une seule variable d’environnement ou une seule fabrique SDK.
Variables d’environnement recommandées :
FLATKEY_API_KEY="sk-fk-your-key"
OPENAI_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_MODEL="replace-with-publish-day-model-id"
ROLLBACK_OPENAI_BASE_URL="https://api.openai.com/v1"
ROLLBACK_MODEL="your-previous-model-id"Utiliser OPENAI_BASE_URL est souvent pratique, car de nombreux wrappers SDK prennent déjà en charge cette convention. Utiliser FLATKEY_API_KEY et FLATKEY_MODEL permet de garder explicites le nouveau identifiant de connexion et le choix du modèle.
C’est ici que Flatkey répond à l’intention de recherche openai compatible base url. La migration doit pouvoir être relue dans un seul diff : URL de base, clé, modèle et étapes de vérification.
Étape 3 : Exécuter un test de validation curl
Commencez par une requête HTTP directe avant de modifier votre application. Cela permet d’isoler les problèmes de clé, d’URL de base, d’endpoint et d’ID de modèle.
Modèle uniquement : le relecteur doit exécuter avec une clé Flatkey valide et un ID de modèle confirmé pour le jour de publication.
curl -sS "https://router.flatkey.ai/v1/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"messages": [
{
"role": "user",
"content": "Répondez par une seule phrase confirmant que ce test de validation Flatkey a fonctionné."
}
]
}'Un test de validation utile prouve plus qu’un simple 200 OK. Pour une migration vers une API compatible OpenAI, vérifiez :
- La réponse contient un message d’assistant exploitable.
- Le nom du modèle est bien celui que vous vouliez tester.
- L’utilisation apparaît dans le tableau de bord Flatkey ou dans les journaux d’utilisation.
- Le nombre de jetons et le coût sont suffisamment visibles pour la revue de facturation.
- Les messages d’erreur sont compréhensibles si l’ID du modèle ou la clé est incorrect.
- L’ancienne URL de base et l’ancien modèle peuvent toujours être restaurés rapidement.
Étape 4 : modifier la configuration du SDK OpenAI pour Python
Si votre application Python utilise déjà le SDK OpenAI, conservez la création du client centralisée.
Modèle uniquement : le réviseur doit l’exécuter avant publication.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.environ.get("OPENAI_BASE_URL", "https://router.flatkey.ai/v1"),
)
response = client.chat.completions.create(
model=os.environ["FLATKEY_MODEL"],
messages=[
{
"role": "user",
"content": "Confirm this OpenAI compatible API request is routed through Flatkey.",
}
],
)
print(response.choices[0].message.content)
print(response.usage)Le détail Python qui compte est base_url. Dans une migration propre vers une OpenAI compatible API, le code de l’application ne devrait pas savoir si l’URL de base pointe directement vers OpenAI, vers un point de terminaison compatible d’un fournisseur ou vers Flatkey. Il doit appeler le client partagé et laisser la configuration choisir l’itinéraire.
Étape 5 : modifier la configuration du SDK Node OpenAI
Pour les applications Node, la configuration équivalente utilise baseURL.
Modèle uniquement : le relecteur doit l’exécuter avant publication.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: process.env.OPENAI_BASE_URL || "https://router.flatkey.ai/v1",
});
const response = await client.chat.completions.create({
model: process.env.FLATKEY_MODEL,
messages: [
{
role: "user",
content: "Confirmez que cette requête API compatible OpenAI est acheminée via Flatkey.",
},
],
});
console.log(response.choices[0].message.content);
console.log(response.usage);C’est le même schéma de migration observé dans la documentation des fournisseurs : conserver le SDK, définir une autre URL de base, fournir une clé API compatible et choisir un identifiant de modèle qui existe sur la plateforme cible.
Étape 6 : mapper délibérément les ID de modèle
La chaîne de modèle est l’endroit où de nombreuses migrations vers une API compatible OpenAI échouent. Une URL de base peut être compatible tandis que les ID de modèle restent spécifiques au fournisseur.
Ne supposez pas :
- Que le nom de votre ancien modèle existe dans Flatkey.
- Qu’un alias de modèle d’un fournisseur pointe vers la même version derrière une passerelle.
- Que chaque modèle compatible prend en charge la même famille de points de terminaison.
- Qu’un modèle qui fonctionne pour le chat fonctionne aussi pour la vision, les outils, les images, la vidéo ou Responses.
À la place, utilisez ce tableau de correspondance avant le premier test au niveau de l’application :
| Utilisation actuelle de l’application | Vérification Flatkey |
|---|---|
| Chat textuel | Choisissez un modèle Flatkey qui prend en charge le point de terminaison de chat OpenAI. |
| Chat en streaming | Testez le streaming séparément avec la même invite et la même marge de délai d’attente. |
| Appel d’outil/de fonction | Vérifiez que le modèle et le point de terminaison sélectionnés prennent en charge la forme d’appel d’outil envoyée par votre application. |
| Sortie JSON | Testez votre response_format exact ou votre schéma de sortie structurée. |
| Entrée vision/image | Confirmez que le modèle sélectionné accepte le format d’entrée image envoyé par votre SDK. |
| API Responses | Confirmez que le point de terminaison/le modèle Flatkey prend en charge /v1/responses pour votre cas d’usage. |
| Génération d’images ou de vidéos | Traitez cela comme une migration de point de terminaison distincte, et non comme une migration de chat completions. |
Le relevé tarifaire de Flatkey du 11 juin 2026 montrait des familles de points de terminaison pour OpenAI chat completions, OpenAI Responses, les messages Anthropic, Gemini, la génération d’images et la vidéo OpenAI. C’est une preuve utile pour les relecteurs, mais l’article devrait quand même inciter les lecteurs à confirmer le modèle exact et la fonctionnalité qu’ils prévoient d’utiliser le jour de publication.
Étape 7 : Vérifier les journaux, les quotas et la facturation
Une réponse réussie de OpenAI compatible API n’est que le premier jalon. La raison de migrer via Flatkey n’est pas seulement la forme de la requête ; c’est la surface d’exploitation autour de l’accès aux modèles.
Après le test de fumée, vérifiez :
| Zone | À inspecter |
|---|---|
| Journal d’utilisation | La requête apparaît avec l’horodatage, le modèle, l’utilisation des jetons, le statut et les détails d’erreur le cas échéant. |
| Facturation | Le coût est visible et correspond au modèle/unité de tarification attendu. |
| Quota | Un petit quota peut être défini pour la nouvelle clé ou la route de test avant un déploiement plus large. |
| Routage | La requête est acheminée via le chemin Flatkey prévu, et non via une ancienne configuration directe du fournisseur. |
| Comportement des erreurs | Les erreurs de mauvaise clé, de mauvais modèle et de paramètre non pris en charge sont suffisamment claires pour le support. |
| Retour arrière | La restauration de l’ancienne URL de base ou du modèle fonctionne sans modification du code. |
C’est là qu’une passerelle OpenAI compatible API devient plus utile qu’un simple point de terminaison de fournisseur brut. Le changement d’URL de base doit apporter une meilleure visibilité, pas seulement un upstream différent.
Étape 8 : Déployez par étapes
Ne déplacez pas tous les workflows d’un coup. Utilisez un déploiement progressif :
- Exécutez un test de fumée curl direct.
- Exécutez un test de fumée SDK dans un environnement local ou de préproduction.
- Rejouez un petit ensemble d’invites connues et comparez la forme de la sortie.
- N’activez le streaming ou les paramètres avancés qu’après la réussite de l’appel de base.
- Appliquez un quota faible à la clé de test.
- Envoyez un petit pourcentage du trafic non critique.
- Comparez les erreurs, la latence, l’utilisation des jetons et le coût.
- N’augmentez le trafic qu’une fois que les journaux et la facturation correspondent aux attentes.
Ce processus maintient la promesse de l’API compatible OpenAI liée à la réalité de production. La compatibilité n’est pas un slogan ; c’est un résultat de test pour les appels que votre application envoie réellement.
Liste de contrôle de migration
Utilisez ceci comme l’asset de la page de publication.
| Étape | Terminé ? | Notes |
|---|---|---|
| Le SDK et le point de terminaison actuels sont documentés | Python, Node, HTTP, wrapper, chat, responses, image, vidéo, etc. | |
| La clé Flatkey est créée | Utilisez une clé de test séparée lorsque c’est possible. | |
| L’URL de base est centralisée | https://router.flatkey.ai/v1 doit se trouver dans la configuration, et non dispersée dans le code. |
|
| L’ID du modèle est sélectionné depuis Flatkey | Confirmez l’ID du modèle du jour de publication depuis la tarification ou le tableau de bord. | |
| Le test rapide curl passe | Le modèle doit être testé par un relecteur avant la publication. | |
| Le test rapide du SDK Python ou Node passe | Utilisez le SDK que votre application exécute réellement. | |
| Les fonctionnalités de streaming/outils/JSON/vision sont testées | Ne testez que les fonctionnalités que vous utilisez. | |
| Le journal d’utilisation est visible | Confirmez le modèle, le statut, les jetons et les erreurs dans le tableau de bord. | |
| La facturation et l’unité de tarification sont examinées | Ne supposez pas que les unités de tarification du fournisseur sont identiques. | |
| La limite de quota est définie | Gardez le trafic de migration borné. | |
| Les variables d’environnement de retour arrière sont prêtes | L’ancienne URL de base et l’ancien modèle peuvent être restaurés sans changement de code. |
Erreurs courantes
L’erreur de migration la plus courante d’une API compatible avec OpenAI consiste à modifier l’URL de base en supposant que tous les autres détails sont identiques. Évitez ces pièges :
- Coder en dur l’URL de base de Flatkey dans plusieurs fichiers.
- Conserver un ancien ID de modèle de fournisseur que Flatkey ne route pas.
- Ne tester que le non-streaming alors que la production utilise le streaming.
- Omettre les tests d’appel d’outil ou de sortie JSON.
- Déplacer des endpoints d’image/vidéo comme s’ils étaient des endpoints de chat-completions.
- Oublier de mettre à jour les tentatives, les budgets de délai d’attente et l’analyse des erreurs.
- Déclarer la migration terminée avant que l’utilisation et la facturation soient visibles.
Flatkey réduit la dispersion des comptes fournisseurs et du routage, mais il ne supprime pas la nécessité d’un test de migration rigoureux.
Quand Flatkey est un bon choix
Flatkey est un excellent choix lorsque votre équipe souhaite une seule URL de base d’API compatible avec OpenAI pour un accès multi-modèles, au lieu de comptes fournisseurs distincts, de clés, de facturation et de vérifications de routage séparés.
Utilisez Flatkey lorsque :
- Votre application utilise déjà un SDK compatible avec OpenAI.
- Vous souhaitez une seule clé pour des modèles provenant de fournisseurs tels que GPT, Claude, Gemini, DeepSeek, Qwen, Seedance 2.0 et GPT Image.
- Vous voulez voir l’utilisation, la facturation, les clés et le routage dans un seul tableau de bord.
- Vous souhaitez des limites de quota avant que le trafic n’augmente.
- Vous voulez que le changement de modèle et le comportement d’équilibrage de charge soient gérés par la couche de passerelle.
- Vous souhaitez que le chemin de migration soit « changer l’URL de base, vérifier le modèle, surveiller l’utilisation » plutôt que « réécrire l’intégration du modèle ».
Utilisez un compte fournisseur direct ou un proxy auto-hébergé lorsque vous avez besoin de contrats spécifiques au fournisseur, d’une logique de routage entièrement personnalisée ou d’un contrôle de passerelle local à l’infrastructure.
FAQ
Une API compatible OpenAI est-elle la même chose qu’OpenAI ?
Non. Une API compatible OpenAI suit le schéma de requête et de réponse de type OpenAI pour les points de terminaison pris en charge, mais le fournisseur, les identifiants de modèle, l’authentification, la prise en charge des fonctionnalités, la tarification et le comportement des erreurs peuvent différer.
Dois-je remplacer mon SDK pour utiliser Flatkey ?
En général non pour les migrations courantes de chat completions. Si votre SDK prend en charge une URL de base personnalisée, vous pouvez souvent conserver le SDK et modifier la configuration. C’est tout l’intérêt d’une migration vers une API compatible OpenAI.
Quelle est l’URL de base compatible OpenAI de Flatkey ?
Utilisez https://router.flatkey.ai/v1 comme URL de base compatible OpenAI. Pour les chat completions, le point de terminaison complet est https://router.flatkey.ai/v1/chat/completions.
Puis-je conserver le nom de mon modèle existant ?
Seulement si cet identifiant de modèle est disponible et pris en charge via Flatkey. Consultez la tarification ou le tableau de bord, puis testez l’identifiant de modèle exact avant le déploiement.
Dois-je migrer d’abord Chat Completions ou Responses ?
Migrez le point de terminaison utilisé par votre application existante. Les applications existantes basées sur Chat Completions peuvent commencer avec /v1/chat/completions. Si votre application utilise l’API Responses, testez séparément /v1/responses et confirmez que le modèle sélectionné prend en charge les fonctionnalités dont vous avez besoin.
Comment revenir en arrière ?
Conservez l’ancienne URL de base, la clé API et le modèle dans la configuration jusqu’à ce que les journaux Flatkey, les coûts, le quota et le comportement de l’application soient vérifiés. Le retour en arrière doit être un changement de variable d’environnement, pas une réécriture du code.
Obtenir une clé
Si vous avez déjà une application construite autour d’une API compatible OpenAI, Flatkey réduit au minimum la migration : obtenez une clé, modifiez l’URL de base, choisissez un modèle, exécutez le test de vérification, et surveillez l’utilisation dans un seul tableau de bord.
Obtenez une clé, puis utilisez https://router.flatkey.ai/v1 comme URL de base pour votre premier test de migration Flatkey.
