Model Not Found dans les APIs compatibles OpenAI : causes, solutions et checklist de débogage

Vous avez changé votre base URL vers un fournisseur compatible OpenAI, envoyé une requête, et reçu cette réponse :

{
  "error": {
    "message": "The model `gpt-4o` does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

C'est l'une des erreurs les plus fréquentes lors du passage d'un fournisseur d'API compatible OpenAI à un autre. Le format de requête est compatible, mais le model ID ne l'est pas.

« Compatible OpenAI » signifie que le format de requête fonctionne. Cela ne signifie pas que chaque model ID est identique chez chaque fournisseur.

En bref

• « Model not found » signifie généralement que le model ID envoyé ne correspond pas à ce que le fournisseur attend.
• Compatible OpenAI ≠ mêmes model IDs. Chaque fournisseur a sa propre nomenclature.
• Vérifiez toujours : (1) la base URL, (2) le model ID, (3) la portée de l'API key, (4) la disponibilité du modèle.
• Utilisez la matrice de débogage ci-dessous pour isoler la cause en moins de 5 minutes.

Pourquoi cette erreur se produit

Mais la compatibilité s'arrête au format de requête. Les model IDs sont propres à chaque fournisseur :

Matrice de débogage : isoler la cause en 5 minutes

Parcourez cette checklist dans l'ordre. Arrêtez-vous dès que vous trouvez l'incohérence.

Les incohérences les plus courantes

Incohérence 1 : Oubli de changer le model ID après avoir changé la base URL

C'est la cause la plus fréquente. Vous migrez d'OpenAI vers un autre fournisseur :

# Avant : OpenAI direct
client = OpenAI(api_key="sk-...")

# Après : passage à un autre fournisseur mais conservation du même model ID
client = OpenAI(
    api_key="your-provider-key",
    base_url="https://api.another-provider.com/v1"  # Changé
)

response = client.chat.completions.create(
    model="gpt-4o",  # ← Ce model ID peut ne pas fonctionner chez le nouveau fournisseur
    messages=[{"role": "user", "content": "Hello"}]
)

Incohérence 2 : Le fournisseur utilise des model IDs avec espace de noms

Certains fournisseurs préfixent les model IDs avec le nom du fabricant d'origine :

# OpenAI direct
model = "gpt-4o"

# OpenRouter
model = "openai/gpt-4o"

# Certains fournisseurs utilisent leurs propres alias
model = "gpt-4o-2024-08-06"

Incohérence 3 : Modèle non disponible chez ce fournisseur

Tous les fournisseurs compatibles OpenAI ne prennent pas en charge tous les modèles :

• Un fournisseur peut prendre en charge Claude mais pas les modèles GPT
• Un fournisseur peut prendre en charge les modèles texte mais pas les modèles image ou vidéo
• Un modèle nouvellement lancé peut ne pas être disponible partout dès le premier jour

Incohérence 4 : Modèle retiré ou renommé

Les modèles d'IA sont mis à jour fréquemment. Un model ID qui fonctionnait le mois dernier peut être déprécié :

gpt-4-turbo → peut rediriger ou échouer selon le fournisseur
claude-3-opus-20240229 → version antérieure, peut avoir été remplacée

Comment vérifier le bon model ID

Option A : Appeler le endpoint des modèles

curl https://api.your-provider.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Cela renvoie la liste des modèles disponibles pour votre compte. Recherchez votre modèle cible dans la réponse.

Option B : Consulter la documentation du fournisseur

Tout fournisseur sérieux dispose d'une page listant ses modèles. Avant de changer, vérifiez :

1. La chaîne exacte du model ID
2. Si un préfixe d'espace de noms est requis
3. Si le modèle est disponible dans votre forfait/niveau
4. Si le modèle est disponible dans votre région

Option C : Envoyer une requête de test minimale

curl https://api.your-provider.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [{"role": "user", "content": "test"}],
    "max_tokens": 5
  }'

Si la réponse est valide, votre model ID est correct. Si « model not found » est renvoyé, essayez le model ID recommandé par le fournisseur.

Construire une sélection de modèles résiliente

Dans les systèmes de production, les incohérences de model ID ne devraient pas provoquer de pannes totales. Voici des patterns qui aident :

Pattern 1 : Couche de mappage des model IDs

Maintenez un mappage entre vos noms de modèles internes et les IDs spécifiques à chaque fournisseur :

MODEL_MAP = {
    "fast-chat": {
        "openai": "gpt-4o-mini",
        "openrouter": "openai/gpt-4o-mini",
        "evolink": "gpt-4o-mini",
    },
    "strong-chat": {
        "openai": "gpt-4o",
        "openrouter": "openai/gpt-4o",
        "evolink": "gpt-4o",
    },
    "reasoning": {
        "openai": "o3",
        "openrouter": "openai/o3",
        "evolink": "o3",
    }
}

def get_model_id(capability: str, provider: str) -> str:
    return MODEL_MAP[capability][provider]

Pattern 2 : Utiliser une API unifiée qui normalise les model IDs

Au lieu de maintenir votre propre couche de mappage, vous pouvez utiliser une passerelle qui accepte des model IDs standardisés et gère le routage vers les fournisseurs en interne.

Avec EvoLink, vous pouvez utiliser des model IDs familiers sans vous soucier de la nomenclature spécifique à chaque fournisseur :

from openai import OpenAI

client = OpenAI(
    api_key="your-evolink-key",
    base_url="https://api.evolink.ai/v1"
)

# Utilisez des model IDs standard — EvoLink gère le mappage
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)

Ou laissez le Smart Router choisir le meilleur modèle pour votre charge de travail :

response = client.chat.completions.create(
    model="evolink/auto",
    messages=[{"role": "user", "content": "Hello"}]
)

Pattern 3 : Valider les model IDs au démarrage

N'attendez pas une requête utilisateur pour découvrir qu'un model ID est incorrect :

async def validate_models_on_startup(client, required_models: list[str]):
    """Appelle /v1/models au démarrage et vérifie que tous les modèles requis existent."""
    available = await client.models.list()
    available_ids = {m.id for m in available.data}

    for model in required_models:
        if model not in available_ids:
            raise RuntimeError(
                f"Model '{model}' not found on provider. "
                f"Available: {sorted(available_ids)}"
            )

Référence rapide : compatible OpenAI ne veut pas dire identique

Cette distinction est la cause fondamentale de la plupart des erreurs « model not found » lors d'un changement de fournisseur.

Articles connexes

• Fix OpenRouter 429 "Provider Returned Error" — quand le modèle est trouvé mais le fournisseur renvoie une erreur
• Best OpenRouter Alternatives in 2026 — comparer les fournisseurs et leur couverture de modèles
• How to Reduce 429 Errors in Agent Workloads — gérer les limites de débit après avoir corrigé les model IDs

FAQ

Pourquoi « gpt-4o » fonctionne sur OpenAI mais pas chez mon nouveau fournisseur ?

Comment trouver le bon model ID pour mon fournisseur ?

Puis-je utiliser le même model ID chez tous les fournisseurs compatibles OpenAI ?

Pas de manière fiable. Bien que certains fournisseurs acceptent les mêmes IDs qu'OpenAI, beaucoup utilisent des conventions de nommage différentes. Maintenez soit une couche de mappage, soit utilisez une passerelle comme EvoLink qui normalise les model IDs pour vous.

Que faire si le model ID fonctionnait hier mais plus aujourd'hui ?

Le modèle a peut-être été déprécié, renommé ou retiré de votre niveau. Consultez le changelog et les annonces du fournisseur. Le cycle de vie des modèles en IA est plus rapide que dans les APIs traditionnelles.

« Model not found » est-il toujours un problème de model ID ?

Généralement oui, mais pas toujours. Cela peut aussi signifier : (1) votre API key n'a pas accès à ce modèle, (2) le modèle n'est pas disponible dans votre région, ou (3) le modèle nécessite un niveau d'abonnement supérieur.

Comment prévenir les erreurs model not found en production ?

Trois stratégies : (1) valider les model IDs au démarrage de l'application, (2) maintenir une couche de mappage des model IDs ou utiliser une passerelle normalisante, (3) implémenter une logique de fallback qui essaie un modèle alternatif si le principal renvoie « not found ».