Guide de l’API compatible OpenAI : changer l’URL de base
Découvrez ce que couvre la compatibilité OpenAI, comment migrer un client existant vers Modelflare et quelles limites vérifier avant la mise en production.

Une API compatible OpenAI permet à un client existant de conserver son en-tête d’authentification, la structure JSON de ses requêtes et son mode de streaming habituels tout en envoyant le trafic vers une autre passerelle. Le changement peut se limiter au remplacement de l’URL de base et de la clé API, mais la compatibilité reste un contrat de protocole : elle ne garantit pas que chaque modèle prend en charge chaque endpoint ou chaque champ propre à un fournisseur.
Ce guide présente une migration sûre pour les applications, les scripts et les outils d’IA qui utilisent déjà une API au format OpenAI.
Ce que couvre réellement la compatibilité OpenAI
Les parties les plus réutilisables du contrat sont les suivantes :
- l’authentification par jeton Bearer via l’en-tête Authorization ;
- des requêtes et des réponses JSON sur des endpoints versionnés /v1 ;
- des endpoints courants tels que /v1/models, /v1/chat/completions et /v1/responses ;
- les événements envoyés par le serveur (SSE) pour les requêtes en streaming prises en charge ;
- des champs de requête familiers tels que model, messages, input, stream et les définitions d’outils, lorsque le protocole choisi les prend en charge.
La compatibilité ne signifie pas qu’un modèle peut passer librement de Chat Completions à Responses. Un modèle peut n’être exposé que via un seul protocole vérifié. Les champs de raisonnement, de recherche ou multimodaux propres à un fournisseur peuvent aussi nécessiter une transmission directe plutôt qu’une traduction par la passerelle.
Considérez le catalogue Modèles et tarifs, mis à jour en continu, comme la référence pour le modèle, le groupe et le format d’API que vous comptez utiliser.
Préparer la migration
Avant de modifier le code de l’application :
- Créez une clé dédiée dans Clés API au lieu de réutiliser une clé personnelle ou destinée à une autre intégration.
- Sélectionnez un groupe de modèles principal qui donne accès au modèle visé.
- Ajoutez des groupes de repli ordonnés uniquement s’ils prennent eux aussi en charge ce modèle et respectent la même politique de coût et de fiabilité.
- Notez l’endpoint actuel, l’ID du modèle, le réglage du streaming et l’utilisation des outils afin de pouvoir comparer le comportement avant et après la bascule.
L’URL de base canonique de Modelflare compatible OpenAI est la suivante :
https://modelflare.dev/v1
La plupart des SDK attendent une URL de base qui se termine par /v1 et ajoutent eux-mêmes /chat/completions ou /responses. Consultez la documentation du client avant d’ajouter un second suffixe d’endpoint.
Vérifier d’abord l’authentification et l’accès au modèle
Stockez la clé dans une variable d’environnement plutôt que dans le code source :
export MODELFLARE_API_KEY='YOUR_MODELFLARE_API_KEY'
Vérifiez ensuite que la clé peut lister les modèles qui lui sont accessibles :
curl -sS https://modelflare.dev/v1/models \
-H "Authorization: Bearer $MODELFLARE_API_KEY"
Une réponse réussie prouve que le nom d’hôte, la connexion TLS et la clé sont valides. Elle ne prouve pas encore qu’un format de requête donné est valide pour chaque modèle renvoyé ; le test suivant doit donc utiliser l’endpoint visé.
Envoyer une requête avec le protocole visé
Pour un modèle Chat Completions indiqué comme compatible avec ce format :
curl -sS https://modelflare.dev/v1/chat/completions \
-H "Authorization: Bearer $MODELFLARE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_CHAT_MODEL",
"messages": [
{"role": "user", "content": "Reply with the active model name."}
],
"stream": false
}'
Pour un modèle de code compatible avec Responses :
curl -sS https://modelflare.dev/v1/responses \
-H "Authorization: Bearer $MODELFLARE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-sol",
"input": "Reply with the active model name.",
"stream": false
}'
Utilisez l’ID de modèle exact affiché dans le catalogue. Un résultat model_not_found signifie généralement que la clé ou le groupe sélectionné n’a pas accès à ce modèle ; changer la casse ne corrigera pas la requête.
Valider le streaming séparément
Une requête réussie sans streaming ne suffit pas pour une application qui dépend du streaming. Répétez la requête avec "stream": true, vérifiez que les événements arrivent au fur et à mesure et assurez-vous que le client ne met pas toute la réponse en mémoire tampon avant de l’afficher.
Pour diagnostiquer un flux lent, distinguez :
- le temps consacré à l’authentification et à la sélection de la route ;
- le délai avant les en-têtes de réponse du fournisseur amont ;
- le délai avant le premier contenu effectif ou le premier delta d’outil ;
- le débit de génération une fois la sortie visible commencée.
Les journaux d’utilisation de Modelflare conservent à cet effet des métadonnées temporelles par requête, sans stocker les prompts, le texte des réponses, les corps de requête bruts, les clés API, les adresses e-mail ni les adresses IP en clair.
Liste de contrôle pour la migration en production
- Conservez la clé API dans un gestionnaire de secrets ou une variable d’environnement.
- Fixez l’URL de base à https://modelflare.dev/v1.
- Utilisez un modèle qui prend explicitement en charge l’endpoint choisi.
- Testez séparément les modes avec et sans streaming.
- Testez les outils, la sortie structurée, les réglages de raisonnement et les entrées multimodales si l’application les utilise.
- Conservez les valeurs explicites égales à zéro ou à false lorsqu’elles ont un sens dans la requête du client.
- Réglez les délais d’expiration du client pour la charge de travail réelle, et non pour un court prompt de vérification d’état.
- Après la bascule, examinez dans les journaux d’utilisation le statut, la latence, l’utilisation des tokens, le groupe sélectionné et le coût.
Une fois la frontière du protocole vérifiée, le client peut généralement conserver le cycle de vie de ses requêtes, tandis que Modelflare fournit l’accès aux modèles, la politique de routage et la visibilité par requête derrière l’endpoint compatible.
Pour comprendre la couche opérationnelle derrière cet endpoint, lisez Qu’est-ce qu’une passerelle API d’IA ?. Si le client peut utiliser plusieurs formats OpenAI, comparez Responses API ou Chat Completions avant de changer de chemin.