La « compatibilité OpenAI » est devenue un argument de vente courant chez les fournisseurs de grands modèles : changez l'URL de base et votre SDK OpenAI existant peut appeler un autre modèle. Cela semble se limiter à une ligne de configuration, mais la migration réserve souvent des 404, des erreurs de paramètres, des interruptions de streaming et des formats d'appel d'outils incompatibles. La raison est simple : la compatibilité ne couvre généralement que les interfaces les plus courantes, pas toutes les capacités.
Cet article clarifie le périmètre de la compatibilité, l'écriture de l'URL de base, la configuration des SDK, les différences de paramètres et les étapes de migration, afin de changer de modèle ou de fournisseur sans réécrire le code métier.
Remarque : OpenAI est une marque de son détenteur ; cet article n'a aucun lien d'affiliation avec les fournisseurs cités. Le périmètre de compatibilité de chaque service est celui de sa documentation, et les modèles et prix sont ceux de la page Tarifs des modèles.
1. Quel niveau la « compatibilité » couvre-t-elle
Une API compatible OpenAI reprend généralement les mêmes chemins HTTP, champs de corps de requête et structures de réponse. Le degré de compatibilité varie fortement selon l'interface :
| Interface | Usage | Compatibilité courante |
|---|---|---|
/v1/chat/completions |
Conversation et génération de texte | La plus répandue ; les champs de base sont généralement pris en charge |
/v1/embeddings |
Vecteurs de texte | Courante, mais vérifier la dimension des vecteurs |
/v1/models |
Liste des modèles | Certains services ne renvoient qu'une partie des modèles, ou rien |
/v1/images/generations |
Génération d'images | Selon le fournisseur |
/v1/audio/transcriptions |
Transcription audio | Selon le fournisseur |
/v1/responses |
Interface Responses plus récente | Prise en charge variable ; à vérifier avant migration |
« Compatible » ne signifie donc pas « strictement équivalent ». Le critère minimal pour intégrer un service est que /v1/chat/completions réponde correctement. Si l'activité dépend des appels d'outils, de la sortie structurée ou du multimodal, vérifiez chaque point ; ne vous fiez pas à la page marketing.
2. Écrire correctement l'URL de base
Le SDK ajoute automatiquement /chat/completions et d'autres chemins après l'URL de base. Celle-ci s'écrit donc généralement jusqu'à /v1, sans inclure l'interface précise. Formes courantes :
| Forme | Fréquence | Explication |
|---|---|---|
https://api.example.com/v1 |
La plus courante | Le SDK ajoute /chat/completions |
https://api.example.com/openai/v1 |
Certaines passerelles | Le préfixe de chemin est défini par le fournisseur |
https://api.example.com/v1/chat/completions |
Incorrecte | Produit un chemin dupliqué et un 404 |
https://api.example.com |
Selon l'implémentation | Certains services ajoutent /v1, mais ne le supposez pas |
Trois détails :
- N'ajoutez pas plusieurs barres obliques à la fin, pour éviter
//chat/completions. - Distinguez l'« adresse de console » de l'« adresse d'API » : la première ne sert généralement pas d'URL de base.
- Si l'exemple du fournisseur fonctionne tel quel, recopiez-le plutôt que de réécrire le chemin.
3. Intégration SDK : trois écritures équivalentes
Avec le SDK Python officiel :
from openai import OpenAI
client = OpenAI(
api_key="sk-votre-clé",
base_url="https://api.example.com/v1",
)
resp = client.chat.completions.create(
model="votre-nom-de-modele",
messages=[{"role": "user", "content": "Répondez seulement OK"}],
)
print(resp.choices[0].message.content)
Avec le SDK Node :
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.OPENAI_API_KEY,
baseURL: "https://api.example.com/v1",
});
const resp = await client.chat.completions.create({
model: "votre-nom-de-modele",
messages: [{ role: "user", content: "Répondez seulement OK" }],
});
console.log(resp.choices[0].message.content);
Vous pouvez aussi utiliser des variables d'environnement pour éviter d'inscrire l'adresse et la clé dans le code :
export OPENAI_API_KEY="sk-votre-clé"
export OPENAI_BASE_URL="https://api.example.com/v1"
Le SDK officiel lit généralement OPENAI_BASE_URL, mais le nom peut varier selon le langage et la version ; suivez la documentation du SDK utilisé. En production, placez l'URL de base dans un centre de configuration et la clé dans un coffre-fort de secrets.
4. Compatibilité des paramètres : les pièges les plus fréquents
Un dialogue de base qui fonctionne ne signifie pas que tous les paramètres sont acceptés. Avant la migration, vérifiez en priorité :
| Paramètre | Différence courante |
|---|---|
model |
Utiliser le nom publié par le fournisseur, pas le nom officiel |
max_tokens |
Certains nouveaux modèles utilisent max_completion_tokens ; l'ancien champ peut être refusé ou ignoré |
temperature / top_p |
Les modèles de raisonnement peuvent figer ou ignorer ce paramètre |
stream |
Généralement pris en charge, mais la structure des événements peut différer |
tools / tool_choice |
Prise en charge très variable ; parallel_tool_calls peut être indisponible |
response_format |
json_object est courant ; la prise en charge de json_schema varie |
seed / logprobs / n |
Souvent absents des services compatibles ; l'envoi peut provoquer une erreur |
reasoning_effort |
Seulement sur certains modèles de raisonnement, avec une sémantique parfois différente |
Une approche sûre consiste à maintenir un « jeu minimal de paramètres » contenant uniquement les champs réellement nécessaires, et à désactiver par configuration les paramètres non pris en charge plutôt qu'à les coder en dur dans la requête.
5. Étapes de migration depuis l'API officielle
En suivant cet ordre, vous limitez le risque :
- Inventorier les points d'appel : lister tous les services, scripts et tâches planifiées qui utilisent le SDK OpenAI.
- Documenter les capacités utilisées : noter où sont employés dialogue, streaming, appels d'outils, sortie structurée, embeddings et multimodal.
- Créer une nouvelle clé avec budget : une clé dédiée à la migration, avec plafond et alertes.
- Basculer l'URL de base : privilégier une variable d'environnement ou un élément de configuration, sans toucher au code métier.
- Exécuter un test de fumée : une requête en curl et une avec le SDK, pour valider adresse, clé et nom de modèle.
- Exécuter un échantillon de régression : préparer 30 à 100 requêtes réelles et comparer qualité, latence, codes d'erreur et consommation de jetons.
- Déployer progressivement : commencer par une activité non critique, observer une semaine avant d'élargir, avec un retour arrière en une opération.
La migration ne s'arrête pas au changement d'adresse. Avec un autre modèle, le style de sortie, la longueur de contexte et le taux de réussite des appels d'outils peuvent évoluer ; un jeu d'évaluation est plus fiable que l'impression subjective.
6. Erreurs courantes et diagnostic
| Erreur | Cause fréquente | Traitement |
|---|---|---|
| 401 Unauthorized | Clé erronée, expirée ou absente | Vérifier l'en-tête et les caractères superflus dans la clé |
| 403 Forbidden | Clé sans permission sur le modèle ou contrôle de risque déclenché | Vérifier les permissions du modèle et l'état du compte |
| 404 Not Found | Chemin de l'URL de base incorrect | Retirer /chat/completions, vérifier la présence de /v1 |
| 400 Bad Request | Paramètre non pris en charge ou format incorrect | Éliminer les paramètres un par un, revenir au corps minimal |
| 429 Too Many Requests | Concurrence ou quota dépassé | Réduire la concurrence, délai exponentiel |
| 500 / 502 / 503 | Panne amont ou de la passerelle | Réessayer, consigner l'identifiant, basculer en secours si l'échec persiste |
| Streaming interrompu | Tampon du proxy, délai dépassé ou réseau instable | Désactiver le tampon du proxy, régler délais et battements de cœur |
Conservez toujours la requête d'origine : URL, en-têtes (clé masquée), corps, code et corps de réponse. Un simple « l'appel a échoué » ne permet pas de diagnostiquer.
7. Streaming, appels d'outils et multimodal : les vraies différences
- Streaming : l'interface compatible renvoie généralement des Server-Sent Events commençant par
data:et se terminant par[DONE]. Mais les champs incrémentaux des appels d'outils et la présence des statistiques d'usage dans le flux varient selon les fournisseurs. Vérifiez la prise en charge avant d'activer le comptage. - Appels d'outils : les noms de fonctions et la structure JSON des paramètres sont globalement identiques, mais les appels parallèles, le mode strict et les champs de raisonnement peuvent manquer. Pour un agent complexe, exécutez d'abord une campagne de tests sur la chaîne d'outils réelle.
- Sortie structurée :
json_objectest généralement disponible, les contraintes JSON Schema ne le sont pas toujours. Le système en aval doit continuer à parser et valider, sans supposer que le modèle produit toujours un JSON valide. - Multimodal : l'usage d'URL ou de Base64 pour les images, les formats et tailles acceptés varient nettement. Validez taille et format avant l'envoi.
- Responses API : la couverture de cette interface récente est moindre que celle de Chat Completions sur les services compatibles ; une application qui en dépend doit vérifier spécifiquement avant migration.
8. Coûts et facturation
La base de facturation d'une API compatible peut aussi différer :
- Vérifier si l'unité facture séparément l'entrée et la sortie, ou de façon combinée.
- Vérifier si le cache et les jetons de raisonnement ont un prix distinct.
- Une réponse en streaming ne renvoie pas toujours
usage; au besoin, estimer localement les jetons. - Séparer les clés par projet ou ligne d'activité pour permettre le rapprochement en fin de mois.
- Fixer un budget journalier et des alertes d'anomalie pour éviter qu'une boucle de tentatives amplifie les frais.
Les prix exacts sont ceux de la page Tarifs des modèles. N'extrapolez pas le coût total à partir du prix d'un seul modèle : modèles, longueurs de contexte et règles de facturation évoluent.
Questions fréquentes
Une API compatible OpenAI et l'API OpenAI officielle, est-ce la même chose ?
Non. La compatibilité concerne le format de l'interface ; le fournisseur, les modèles, la facturation et les clauses de données peuvent différer. Une même méthode d'appel n'assure pas les mêmes capacités ni la même conformité.
L'URL de base doit-elle inclure /v1 ?
Cela dépend de la documentation du fournisseur. La plupart exigent /v1, le SDK ajoutant ensuite /chat/completions ; quelques passerelles ont leur propre préfixe. Le critère : URL de base + /chat/completions doit atteindre la bonne interface.
Pourquoi curl fonctionne-t-il alors que le SDK renvoie un 404 ?
Souvent parce que le SDK ajoute automatiquement le chemin alors que l'URL de base contient déjà /chat/completions, ou parce qu'une variable d'environnement écrase la configuration du code. Affichez l'adresse réellement appelée avant de comparer.
L'interface compatible prend-elle en charge les appels d'outils et la sortie structurée ?
En partie, selon le fournisseur et le modèle. Avant la migration, testez la chaîne d'outils réelle et un JSON Schema, pas seulement une conversation ordinaire.
Que faire si la qualité des réponses baisse après migration ?
Vérifiez d'abord que le nom du modèle, la température et les prompts n'ont pas changé, puis comparez sur le même lot d'échantillons. Au besoin, ajustez les prompts, changez de modèle ou conservez deux fournisseurs avec répartition du trafic ; ne jugez pas sur une ou deux impressions subjectives.
Et ensuite
La valeur d'une API compatible OpenAI est de réduire le coût de bascule, mais c'est le protocole qui est compatible, pas les capacités. Commencez par valider un corps de requête minimal, puis activez un à un le streaming, les appels d'outils et la sortie structurée. Si vous avez besoin d'une entrée compatible OpenAI unifiée, d'une gestion des clés et de statistiques d'usage, vous pouvez créer un compte ZSQH AI Gateway ; les modèles et prix sont indiqués sur la page Tarifs des modèles.
À lire également :
