Claude SDK OpenAI Anthropic Chat Completions API compatible

Utiliser Claude avec le SDK OpenAI sans réécrire le client

Appelez Claude avec le SDK OpenAI pour l'évaluation, puis utilisez une passerelle qui adapte l'entrée OpenAI aux Messages Claude natifs en production.

AveMujica API 15 juil. 2026 9 min de lecture

Vous pouvez faire appeler Claude au SDK officiel OpenAI pour Python ou TypeScript en ne changeant que base_url, la clé API et l'identifiant du modèle, puis continuer à utiliser chat.completions. Anthropic documente ce chemin dans son guide de compatibilité avec le SDK OpenAI. La même forme de client peut aussi joindre une passerelle API compatible OpenAI, qui conserve les identifiants Anthropic côté serveur et convertit les requêtes au format OpenAI en Messages Claude natifs en amont.

Ces deux chemins ne sont pas équivalents. La compatibilité directe sert à l'évaluation. Une passerelle de production qui parle OpenAI aux clients et Claude Messages à Anthropic présente une autre histoire de fiabilité.

Chemin d'évaluation et chemin de production

Anthropic précise que sa couche de compatibilité OpenAI est principalement destinée aux tests et à la comparaison de modèles et qu'elle n'est pas une solution durable ou prête pour la production dans la plupart des cas. Traitez cette phrase comme une politique produit, pas comme une note marketing.

Chemin	Client	Amont	Idéal pour
Compatibilité Anthropic directe	SDK OpenAI → `https://api.anthropic.com/v1/`	Surface Anthropic au format OpenAI	Évaluation locale, comparaison de prompts, essais courts
Entrée OpenAI de la passerelle	SDK OpenAI → `/v1` de votre passerelle	Conversion en Messages Claude natifs	Clés partagées, quotas, bascule, produits multi-fournisseurs
SDK Anthropic natif / API Messages	Client Anthropic	Ensemble complet des fonctions Claude	Cache de prompts, citations, détails de réflexion étendue, sorties structurées garanties

Utilisez la première ligne pour répondre à « Claude est-il assez bon sur notre suite fixe ? ». Choisissez la deuxième lorsque plusieurs services ont besoin de Claude sans que chacun détienne une clé Anthropic. Prenez la troisième lorsque vous avez besoin de contrôles natifs Claude que la couche de compatibilité omet ou ignore.

Le canal Claude de ce dépôt convertit OpenAI Chat Completions en Claude Messages (RequestOpenAI2ClaudeMessage et adaptateurs associés). Ce n'est pas la même chose que relayer sans modification l'endpoint de compatibilité Anthropic. Les clients parlent toujours JSON OpenAI ; le plan de contrôle gère la conversion, les identifiants et les journaux d'usage.

Limites importantes de la couche de compatibilité OpenAI d'Anthropic

Lorsque vous appelez api.anthropic.com avec le SDK OpenAI, la documentation Anthropic actuelle indique plusieurs écarts précis. Intégrez-les au budget du projet avant de parler de « compatibilité immédiate ».

strict est ignoré sur les outils. Les arguments JSON ne sont pas garantis conformes au schéma fourni. Validez-les dans votre runtime, ou utilisez les sorties structurées natives de Claude lorsque vous avez besoin d'une garantie côté serveur.
Les entrées audio sont supprimées. Les parties audio multimodales sont ignorées au lieu de produire une erreur explicite.
Le cache de prompts n'est pas pris en charge sur le chemin compatible. Il reste disponible via les SDK Anthropic et l'API native.
Les messages système et développeur sont remontés puis concaténés dans un unique message système initial. Anthropic ne prend en charge qu'un message système de tête ; les tours system/developer placés au milieu d'une conversation OpenAI sont fusionnés avec des sauts de ligne.
La plupart des champs non pris en charge sont ignorés silencieusement. La préproduction doit échouer explicitement lorsqu'un champ disparu modifie le comportement produit.
Les corps d'erreur gardent une enveloppe de forme OpenAI, mais leur texte détaillé n'est pas équivalent à celui d'OpenAI. Journalisez-le pour le diagnostic ; ne l'analysez pas comme un contrat stable.

Les fonctions Claude complètes — traitement PDF, citations, réflexion étendue avec accès détaillé aux pensées et cache de prompts — appartiennent à l'API Claude native, ou à un chemin de passerelle qui mappe ces champs natifs. Pour des boucles d'outils d'agent portables entre marques, consultez les appels d'outils portables entre fournisseurs.

Base URL Anthropic directe (évaluation)

Voici le modèle Python documenté par Anthropic :

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    base_url="https://api.anthropic.com/v1/",
)

response = client.chat.completions.create(
    model="claude-sonnet-5",  # or claude-opus-4-8; verify on Anthropic model docs
    messages=[
        {"role": "system", "content": "You are a precise API integration assistant."},
        {"role": "user", "content": "Summarize three risks of hardcoding provider SDKs."},
    ],
    max_tokens=800,
)

print(response.choices[0].message.content)

TypeScript :

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ANTHROPIC_API_KEY,
  baseURL: "https://api.anthropic.com/v1/",
});

const response = await client.chat.completions.create({
  model: "claude-sonnet-5",
  messages: [
    { role: "system", content: "You are a precise API integration assistant." },
    { role: "user", content: "Summarize three risks of hardcoding provider SDKs." },
  ],
  max_tokens: 800,
});

console.log(response.choices[0]?.message?.content);

Les exemples officiels utilisent souvent claude-opus-4-8. La documentation actuelle des modèles Anthropic répertorie aussi Claude Sonnet 5 et Claude Haiku 4.5. Préférez le tableau de modèles en direct à toute capture de blog, y compris celle-ci.

Base URL de passerelle (chemin multi-service de production)

Lorsque Claude n'est qu'un canal parmi d'autres, pointez le même SDK vers la passerelle et conservez l'identifiant Anthropic uniquement côté serveur :

client = OpenAI(
    api_key="GATEWAY_API_KEY",
    base_url="https://your-gateway.example.com/v1",
)

response = client.chat.completions.create(
    model="claude-sonnet",  # stable gateway alias mapped to a current Claude ID
    messages=[
        {
            "role": "user",
            "content": "Draft a migration checklist for SDK consolidation.",
        }
    ],
    max_tokens=800,
)

Les opérateurs associent des alias comme claude-sonnet ou claude-opus aux identifiants amont bruts (claude-sonnet-5, claude-opus-4-8, ou des instantanés datés lorsque nécessaire). Les configurations applicatives doivent dépendre des alias : un renommage amont devient alors une modification de canal, pas un incident dans plusieurs dépôts. C'est le plan de contrôle décrit dans la passerelle LLM multi-fournisseurs.

Ce qui se transpose généralement sur le chemin commun

Messages

L'historique ordinaire system / user / assistant fonctionne pour l'évaluation et la plupart des chats produit.
Les tours system ou developer en milieu de conversation ne restent pas des rôles OpenAI séparés dans la couche de compatibilité Anthropic ; attendez-vous à une fusion.
Gardez le texte de politique explicite. Ne supposez pas que Claude hérite d'instructions cachées réglées uniquement pour les modèles OpenAI.

Outils

Les définitions tools au format OpenAI fonctionnent souvent pour les premières migrations d'agents. Exemple :

tools = [
    {
        "type": "function",
        "function": {
            "name": "lookup_order",
            "description": "Fetch an order by ID from the shop system",
            "parameters": {
                "type": "object",
                "properties": {"order_id": {"type": "string"}},
                "required": ["order_id"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Where is order A-100?"}],
    tools=tools,
    tool_choice="auto",
)

message = response.choices[0].message
if message.tool_calls:
    for call in message.tool_calls:
        print(call.function.name, call.function.arguments)

Comme strict est ignoré sur la surface de compatibilité Anthropic, analysez puis validez arguments contre le schéma avant tout effet de bord. Même sur le chemin de la passerelle, validez dans l'exécuteur d'outils ; ne faites jamais confiance au seul JSON produit par le modèle.

Streaming

Le streaming SSE correspond à ce que la plupart des interfaces de chat OpenAI consomment déjà. Vérifiez la latence jusqu'au premier token, la gestion des erreurs en cours de flux et la normalisation des événements Claude par la passerelle dans une forme client stable. Le changement automatique de fournisseur après l'émission de tokens partiels est plus difficile que la bascule avant le flux ; associez-le à la stratégie de bascule des API LLM.

Écarts de sortie structurée, de sécurité et d'observabilité

Si un pipeline dépend de l'application stricte de JSON Schema, testez le schéma exact sur Claude avant d'affirmer la parité. Lorsque le mode strict est incomplet, validez dans le code applicatif ou utilisez les sorties structurées natives de Claude.

Les fournisseurs diffèrent sur les refus, les en-têtes de limitation et la comptabilité des tokens, même quand les clés JSON semblent identiques. Normalisez les classes d'erreurs à la passerelle si les clients attendent un contrat unique. Ne retentez pas une erreur permanente d'authentification ou de politique comme s'il s'agissait d'un 5xx transitoire.

Les clés Anthropic directes et les clés de passerelle produisent des pistes d'audit différentes. Les équipes veulent généralement l'historique d'usage à côté de l'état des canaux, plutôt que dans une console mono-fournisseur. Les pages publiques de tarifs et de catalogue de modèles aident les parties prenantes ; évitez de parsemer chaque paragraphe d'URL d'exploitation authentifiées.

Séquence de bascule contrôlée

Inventoriez les services qui dépendent déjà du SDK OpenAI ou de /v1/chat/completions brut.
Exécutez une suite d'évaluation fixe contre l'endpoint de compatibilité Anthropic avec un identifiant de modèle Claude.
Enregistrez les identifiants Anthropic comme canal de passerelle et publiez un alias stable.
Pointez une tâche interne peu risquée vers l'alias de la passerelle ; ne commencez pas par le chat client.
Comparez la validité des schémas, le taux de refus, la latence et le coût par tâche réussie.
Ajoutez les outils et le streaming seulement après stabilisation du chat simple.
Documentez le retour arrière : gardez actif l'alias de modèle précédent.

Test HTTP rapide

curl https://your-gateway.example.com/v1/chat/completions \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet",
    "messages": [
      {"role": "user", "content": "Reply with the single word ready."}
    ],
    "max_tokens": 32
  }'

Attendez un corps JSON style Chat Completions avec choices[0].message.content. Si la forme diverge, corrigez le mapping passerelle avant le code produit.

Checklist de production (chemin passerelle)

L'évaluation a prouvé la qualité sur une suite fixe ; le trafic de production ne dépend pas durablement de la couche de compatibilité Anthropic.
L'alias de modèle pointe vers un identifiant Claude actuel issu de la documentation Anthropic ou de votre catalogue maintenu.
Les secrets résident dans la passerelle ou le gestionnaire de secrets, jamais dans les navigateurs ni les applications mobiles.
max_tokens est explicite ; des valeurs implicites peuvent tronquer les longues réponses.
Les arguments d'outil sont validés côté serveur ; ne dépendez pas de strict, qui est ignoré.
Les clients de streaming gèrent les fins incomplètes et les erreurs en cours de flux.
Les tableaux de bord de coûts et d'erreurs séparent Claude des autres fournisseurs.
La politique de bascule précise si Claude est principal, de secours ou épinglé.

Quand la passerelle bat la base URL Anthropic directe

Déclencheur	Pourquoi la passerelle aide
Plusieurs fournisseurs dans un produit	Une configuration client, plusieurs canaux
Identifiants partagés par l'équipe	Des clés de passerelle à portée limitée plutôt que des clés Anthropic partagées
Revues de dépenses	Historique d'usage et contexte tarifaire unifiés
Objectifs de fiabilité	Retentatives et bascule sans réécrire chaque service
Flottes d'agents	Politique centrale pour les outils et le routage des modèles

AveMujica API est construit comme ce plan de contrôle : entrée compatible OpenAI, canaux fournisseurs, catalogue de modèles et historique opérationnel. Il ne dispense pas de lire les notes de compatibilité Anthropic ; il empêche ces notes de devenir cinq variantes divergentes du client.

Sources officielles

Dernière vérification : 2026-07-15. Revérifiez les identifiants de modèles et les limites de compatibilité dans la documentation Anthropic avant tout gel de production.

Questions fréquentes

Le chemin OpenAI SDK d'Anthropic est-il prêt pour la production ?

Anthropic le décrit comme un chemin principalement destiné aux tests et aux comparaisons, pas comme une solution de production durable pour la plupart des usages. Pour une flotte de production, préférez une passerelle qui adapte l'entrée OpenAI aux Messages Claude natifs, ou l'API native Anthropic lorsque vous avez besoin de fonctions propres à Claude.

Tous les champs OpenAI Chat Completions fonctionnent-ils sans modification sur Claude ?

Non. strict est ignoré, l'audio est supprimé, le cache de prompts n'est pas disponible sur la couche de compatibilité et les tours system/developer sont fusionnés. Testez exactement la forme de requête que vous livrez.

Quelle chaîne de modèle doit figurer dans la configuration applicative ?

Préférez un alias de passerelle (claude-sonnet) que les opérateurs associent à un identifiant actuel comme claude-sonnet-5 ou claude-opus-4-8. Évitez de figer l'instantané d'hier dans chaque service.

Ai-je encore besoin du SDK Anthropic ?

Oui lorsque vous avez volontairement besoin de contrôles exclusivement natifs : marqueurs de cache de prompts, accès complet à la réflexion étendue ou sorties structurées natives. Gardez le SDK OpenAI lorsque la surface au format OpenAI suffit et que la passerelle gère la diversité des fournisseurs.

Livrer la première bascule vers Claude

Choisissez un service qui utilise déjà le SDK OpenAI. Prouvez la qualité sur l'endpoint de compatibilité Anthropic, puis déplacez ce service vers un alias de passerelle qui route vers Claude Messages. N'étendez les outils et le streaming qu'après validation du chat simple, puis comparez le trafic du premier jour à votre référence OpenAI précédente.