API compatible avec OpenAI : changer l’URL

Une API compatible avec OpenAI permet à un client existant de conserver ses en-têtes d’authentification, ses objets JSON et son mode de streaming habituels, tout en envoyant le trafic vers une autre passerelle. Il suffit parfois de remplacer l’URL de base et la clé API. Cette compatibilité reste toutefois un contrat de protocole : elle ne garantit pas que chaque modèle accepte tous les endpoints ni tous les champs propres à un fournisseur.

Ce guide présente une migration sûre pour les applications, scripts et outils d’IA qui utilisent déjà une API au format OpenAI.

Ce que couvre réellement la compatibilité OpenAI

Les éléments les plus réutilisables sont les suivants :

• authentification par jeton Bearer dans l’en-tête Authorization ;
• requêtes et réponses JSON sur des endpoints versionnés sous /v1 ;
• endpoints courants tels que /v1/models, /v1/chat/completions et /v1/responses ;
• événements envoyés par le serveur (SSE) pour les requêtes en streaming prises en charge ;
• champs familiers comme model, messages, input, stream et les définitions d’outils prévues par le protocole choisi.

Être compatible ne signifie pas qu’un modèle peut passer librement de Chat Completions à Responses. Un modèle peut n’être exposé que sur l’un des protocoles vérifiés. Les champs de raisonnement, de recherche ou d’entrée multimodale propres à un fournisseur peuvent aussi devoir être transmis tels quels, sans traduction par la passerelle.

Considérez le catalogue Modèles et tarifs comme la référence pour le modèle, le groupe et le format d’API à utiliser.

Préparer la migration

Avant de modifier l’application :

1. 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.
2. Choisissez un groupe principal donnant accès au modèle souhaité.
3. Ajoutez des groupes de repli dans un ordre explicite, uniquement s’ils prennent en charge le même modèle et respectent la politique de coût et de fiabilité.
4. Notez l’endpoint actuel, l’identifiant exact du modèle, le mode de streaming et les outils utilisés afin de comparer le comportement avant et après la bascule.

L’URL de base canonique de l’API OpenAI-compatible de Modelflare est :

https://modelflare.dev/v1

La plupart des SDK attendent une URL qui se termine par /v1, puis ajoutent eux-mêmes /chat/completions ou /responses. Vérifiez la documentation du client avant d’ajouter une seconde fois le suffixe de l’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 cette clé peut lister les modèles disponibles :

curl -sS https://modelflare.dev/v1/models \
  -H "Authorization: Bearer $MODELFLARE_API_KEY"

Une réponse valide confirme le nom d’hôte, la liaison TLS et la clé. Elle ne prouve pas encore que chaque modèle renvoyé accepte n’importe quel format de requête. Le test suivant doit donc employer l’endpoint réellement prévu.

Envoyer une requête avec le protocole prévu

Pour un modèle indiqué comme compatible avec Chat Completions :

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": "Réponds avec le nom du modèle actif."}
    ],
    "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": "Réponds avec le nom du modèle actif.",
    "stream": false
  }'

Utilisez exactement l’identifiant affiché dans le catalogue. Une erreur model_not_found indique généralement que la clé ou le groupe n’a pas accès au modèle ; modifier la casse ne résout pas le problème.

Valider le streaming séparément

Une requête non streamée réussie ne suffit pas si l’application dépend d’un affichage progressif. Recommencez avec "stream": true, vérifiez que les événements arrivent au fil de l’eau et que le client n’attend pas la réponse complète avant de l’afficher.

Pour diagnostiquer un streaming lent, distinguez :

• le temps consacré à l’authentification et au choix de la route ;
• l’attente avant les en-têtes de réponse du fournisseur ;
• le délai avant le premier texte, raisonnement ou événement d’outil utile ;
• le débit de génération après le début de l’affichage.

Les journaux d’utilisation de Modelflare conservent ces mesures par requête sans stocker les prompts, le texte des réponses, les corps bruts, les clés API, les adresses e-mail ni les adresses IP en clair.

Liste de contrôle avant la production

• Conservez la clé API dans un gestionnaire de secrets ou une variable d’environnement.
• Fixez l’URL de base à https://modelflare.dev/v1.
• Choisissez un modèle qui prend explicitement en charge l’endpoint retenu.
• 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 emploie.
• Préservez les valeurs explicites 0 et false lorsqu’elles ont un sens.
• Réglez les délais d’expiration pour la charge réelle, pas pour un simple prompt de contrôle.
• Après la bascule, examinez le statut, la latence, les jetons, le groupe retenu et le coût.

Une fois la frontière du protocole validée, le client peut généralement conserver son cycle de requête. Modelflare gère derrière le même endpoint l’accès aux modèles, les règles de routage et la visibilité par requête.