API compatible avec OpenAI ou Anthropic : laquelle choisir ?

Ce que signifie réellement « API compatible »

Une API compatible accepte une structure de requête familière et renvoie une réponse qu’un SDK ou client existant sait analyser. Dans une intégration classique, le développeur modifie la Base URL, la clé API et le Model ID tout en conservant l’essentiel du code applicatif.

Ce terme possède une limite nette. Un fournisseur peut prendre en charge la génération de texte simple sans accepter un paramètre précis, un outil hébergé, l’audio, un endpoint d’image ou la sémantique exacte des erreurs. Même deux endpoints exposant un champ model peuvent différer dans la liste des modèles et les règles d’accès.

Vous souhaitez tester le protocole choisi avec une vraie requête ? Vous pouvez créer votre propre compte BetterToken et une clé API, ouvrir le guide de démarrage rapide et envoyer un test minimal. BetterToken fournit des interfaces distinctes compatibles avec OpenAI et Anthropic ; protocole, Base URL, type de clé API et Model ID actuel doivent correspondre à la référence API en vigueur.

Différences entre requêtes et authentification

Dans un flux compatible avec OpenAI, le client construit généralement messages pour Chat Completions ou input pour Responses. L’authentification utilise souvent un jeton Bearer :

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Anthropic Messages possède sa propre structure de messages, un champ system séparé, une limite de sortie obligatoire et une version de protocole. L’API officielle Anthropic utilise notamment les en-têtes x-api-key et anthropic-version :

x-api-key: YOUR_API_KEY
anthropic-version: CURRENT_SUPPORTED_VERSION
Content-Type: application/json

Une passerelle compatible peut accepter un autre mode d’authentification. Prenez les en-têtes dans la documentation de l’endpoint appelé. Un exemple d’API officielle explique le format du protocole, mais ne remplace pas le guide d’intégration du fournisseur.

L’instruction système n’occupe pas non plus la même place dans chaque contrat. Un protocole peut la conserver parmi les messages, tandis qu’un autre l’envoie dans un champ distinct. Une conversion mécanique peut modifier l’ordre du contexte, un préfixe de cache ou le comportement du client.

Chat Completions, Responses et Messages sont des contrats distincts

L’expression compatible avec OpenAI n’indique pas quelle interface est mise en œuvre. Avant une migration, consignez le contrat exact :

• Chat Completions : un tableau messages, une réponse sous choices et des fragments diffusés sous delta.
• Responses API : des éléments d’entrée, des éléments de sortie typés et des événements distincts pour le cycle de vie de la réponse.
• Anthropic Messages : messages, un champ system distinct, des blocs de contenu et ses propres événements de streaming.

Si une bibliothèque attend Responses, un endpoint limité à /chat/completions ne suffit pas. Si Claude Code attend Anthropic Messages, un endpoint compatible avec OpenAI ne fonctionne pas sans adaptateur. Remplacer la Base URL suffit uniquement lorsque le client et le serveur implémentent le même contrat.

Différences de streaming et de terminaison

Les trois interfaces peuvent diffuser des données en continu, mais les noms et l’ordre des événements diffèrent.

Responses API émet des Server-Sent Events typés pour la création de la réponse, les fragments de texte et les états terminaux. Le client doit attendre un événement de fin ou traiter une réponse échouée ou incomplète.

Anthropic Messages émet message_start, des événements de blocs de contenu, message_delta et message_stop. Une erreur peut survenir dans un stream déjà ouvert après la réussite de la première réponse HTTP.

Avec Chat Completions, le client accumule généralement choices[0].delta et détecte la fin selon le contrat de l’endpoint. Un code qui n’attend qu’un seul marqueur ne peut pas être repris dans Responses ou Messages sans vérification.

Un gestionnaire minimal conserve quatre états :

created -> receiving -> completed
                   \-> failed
                   \-> disconnected

disconnected n’est pas completed. Si la connexion se termine après une réponse partielle, conservez les événements déjà reçus et déterminez si une nouvelle tentative est sûre.

Utilisation des outils et sortie structurée

Des noms de champs proches, comme tools et tool_calls, peuvent suggérer davantage de compatibilité qu’il n’en existe réellement. Testez au minimum :

• JSON Schema et les restrictions sur les types pris en charge ;
• les appels d’outils parallèles ;
• la manière dont le résultat d’un outil revient au modèle ;
• l’assemblage des arguments diffusés ;
• le comportement avec du JSON invalide ;
• la sortie structurée stricte et les refus de schéma.

Un adaptateur doit préserver le sens de l’appel, pas seulement renommer les champs. C’est essentiel pour les outils à effets secondaires : répéter le même appel peut envoyer un second message, créer un autre enregistrement ou exécuter deux fois une opération.

Ne pas convertir les erreurs à partir du seul statut HTTP

401, 403, 404, 429 et 5xx offrent une première classification utile, mais le corps et les en-têtes des erreurs varient selon le fournisseur. Conservez :

• le statut HTTP ;
• le type et le code d’erreur du fournisseur ;
• un message court sans secret ;
• le request ID ;
• les en-têtes liés aux nouvelles tentatives ;
• l’endpoint, le protocole et le Model ID.

Ne consignez pas la clé API, le prompt complet ni une réponse sensible. Si une passerelle normalise les erreurs, conservez le code d’origine du fournisseur dans un champ interne sûr. Sinon, model not found, l’absence d’accès et un endpoint incompatible peuvent tous devenir un 400 peu exploitable.

Comment choisir le protocole

Un outil d’IA prêt à l’emploi

Lisez d’abord sa documentation. S’il demande une OpenAI Base URL et utilise Chat Completions ou Responses, choisissez l’endpoint compatible avec OpenAI correspondant. S’il lit ANTHROPIC_BASE_URL et attend Messages, utilisez un endpoint compatible avec Anthropic.

Ne choisissez pas le protocole à partir du nom du modèle. Un modèle peut être disponible via une passerelle alors que le client exige toujours un format de requête précis.

Votre propre application

La décision dépend du SDK et des fonctions déjà utilisés. Pour une nouvelle application, listez les capacités nécessaires : streaming, outils, sortie structurée, vision, consommation de tokens, opérations batch ou autres endpoints. Vérifiez chacune dans la documentation officielle du fournisseur.

Une migration de fournisseur

Évaluez la surface du contrat, pas le nombre de lignes modifiées. Un chat simple peut demander seulement trois nouvelles valeurs de configuration. Une application agentique avec outils, historique long, cache et streaming nécessite généralement un adaptateur et des tests d’intégration.

Tester avant de déplacer le trafic de production

1. Notez le SDK, l’endpoint et la version de l’API.
2. Copiez le Model ID exact depuis le catalogue actuel.
3. Envoyez une requête courte sans outil ni streaming.
4. Diffusez une réponse simple jusqu’à son événement terminal.
5. Exécutez un appel d’outil sûr, sans effet secondaire externe.
6. Déclenchez une erreur contrôlée avec un Model ID volontairement invalide.
7. Faites correspondre usage, le statut et le request ID avec le Dashboard.
8. Testez la gestion du timeout et une nouvelle tentative limitée.

Déplacez le trafic réel seulement après ces vérifications. Avec BetterToken, partez de la référence API, choisissez un protocole et validez une requête minimale avant d’activer les outils agentiques.

FAQ

Une API compatible avec OpenAI reproduit-elle toute l’API OpenAI ?

Non. Le terme désigne la compatibilité avec une interface précise. Les modèles, paramètres, outils, le streaming, les erreurs et les endpoints supplémentaires doivent toujours être vérifiés séparément.

Puis-je appeler un endpoint compatible avec Anthropic au moyen du SDK OpenAI ?

Pas directement si le SDK envoie le contrat OpenAI. Utilisez un client prenant en charge Anthropic Messages ou un adaptateur qui convertit correctement les messages, le streaming et l’utilisation des outils.

Remplacer la Base URL suffit-il ?

Parfois, pour une courte requête textuelle dans un client déjà compatible. Pour une migration de production, vérifiez tout de même le Model ID, l’authentification, le streaming, les outils, les erreurs et l’utilisation.

De quel protocole Claude Code a-t-il besoin ?

Claude Code utilise normalement une interface compatible avec Anthropic. Prenez les variables exactes, la Base URL et les paramètres du modèle dans le guide BetterToken actuel.