Models

Le point de terminaison de liste des modèles répond à une seule question : quels modèles ce token peut-il appeler. Il renvoie un résultat filtré selon les droits du token, le groupe et l’état de publication, et non le catalogue complet des modèles de la plateforme. Le model de la requête doit provenir de cette liste.

Lister les modèles disponibles

GET /v1/models

curl https://api.routeapi.ai/v1/models \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

Réponse :

{
  "success": true,
  "object": "list",
  "data": [
    {
      "id": "gpt-5.5",
      "object": "model",
      "created": 1626777600,
      "owned_by": "openai",
      "supported_endpoint_types": ["openai", "openai-response"]
    },
    {
      "id": "claude-sonnet-4-5",
      "object": "model",
      "created": 1626777600,
      "owned_by": "anthropic",
      "supported_endpoint_types": ["openai", "anthropic"]
    },
    {
      "id": "text-embedding-3-large",
      "object": "model",
      "created": 1626777600,
      "owned_by": "openai",
      "supported_endpoint_types": ["embeddings"]
    }
  ]
}

Champ	Description
id	La valeur à renseigner dans model lors de l’appel, le seul identifiant de modèle fiable
object	Toujours "model"
created	Valeur de remplissage fixe 1626777600, ce n’est pas la date réelle de publication ; ne l’utilisez pas pour trier ni pour juger de l’ancienneté
owned_by	Type de canal auquel appartient le modèle (par exemple openai, anthropic) ; les modèles personnalisés de la plateforme valent custom
supported_endpoint_types	Liste des types de point de terminaison utilisables pour ce modèle, voir Types de point de terminaison ci-dessous

Le niveau racine de la réponse contient à la fois success et les champs object/data de style OpenAI. Le SDK OpenAI ne lit que data ; le champ success supplémentaire n’affecte pas l’analyse.

L’ordre de data n’est pas garanti stable et peut différer entre deux requêtes. Si vous avez besoin d’un ordre fixe, triez côté client.

Types de point de terminaison

supported_endpoint_types est un champ d’extension de RouteAPI, et c’est le seul signal de capacité dans la liste des modèles. Il indique par quelles entrées de protocole ce modèle peut être appelé :

Valeur	Point de terminaison correspondant
openai	POST /v1/chat/completions
openai-response	POST /v1/responses
anthropic	POST /v1/messages
gemini	POST /v1beta/models/{model}:generateContent
embeddings	POST /v1/embeddings
image-generation	POST /v1/images/generations
jina-rerank	POST /v1/rerank
openai-video	Point de terminaison de génération vidéo OpenAI
suno-*	Points de terminaison de la série Suno, voir Suno API

Si embeddings n’apparaît pas dans les supported_endpoint_types d’un modèle, ne transmettez pas ce modèle à /v1/embeddings : ce type d’incompatibilité échoue à l’étape du transfert.

La liste ne contient aucun champ de capacité fin. La prise en charge des appels d’outils, des entrées image ou des sorties structurées n’est pas renvoyée par le point de terminaison de liste des modèles, et il n’existe pas de champs du type supports_tools / supports_vision. Ces capacités sont déterminées par le modèle en amont lui-même ; pour les vérifier, consultez la documentation du fournisseur du modèle ou envoyez directement une vraie requête au modèle visé. Les métadonnées comme la longueur de contexte, les modalités et les prix ne figurent pas non plus dans ce point de terminaison : elles sont affichées sur la page de la place des modèles de la console.

Consulter un modèle unique

GET /v1/models/{model}

curl https://api.routeapi.ai/v1/models/gpt-5.5 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

S’il existe, l’objet modèle est renvoyé directement (sans enveloppe data) :

{
  "id": "gpt-5.5",
  "object": "model",
  "created": 1626777600,
  "owned_by": "openai"
}

S’il n’existe pas ou n’est pas visible pour le compte actuel, la réponse est :

{
  "error": {
    "message": "The model 'foo' does not exist",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

Notez que le code de statut HTTP reste 200. Ce point de terminaison place l’erreur dans le champ error du corps de la réponse et n’exprime pas « le modèle n’existe pas » par le code de statut. Le client doit vérifier la présence d’un champ error dans le corps de la réponse ; se fier au seul code de statut HTTP fait passer un échec pour une réussite.

Un modèle non visible pour le compte actuel et un modèle réellement inexistant renvoient exactement la même erreur : ce point de terminaison ne permet pas de les distinguer.

Liste des modèles dans les autres protocoles

Le même ensemble de modèles disponibles peut être récupéré dans trois formats de protocole ; choisissez selon votre SDK.

Format Claude Messages

En envoyant à la fois les en-têtes x-api-key et anthropic-version sur GET /v1/models, la réponse suit le style Anthropic :

curl https://api.routeapi.ai/v1/models \
  -H "x-api-key: $ROUTEAPI_KEY" \
  -H "anthropic-version: 2023-06-01"

{
  "data": [
    {
      "id": "claude-sonnet-4-5",
      "created_at": "2021-07-20T12:00:00Z",
      "display_name": "claude-sonnet-4-5",
      "type": "model"
    }
  ],
  "first_id": "claude-sonnet-4-5",
  "has_more": false,
  "last_id": "claude-sonnet-4-5"
}

Les deux en-têtes doivent être présents simultanément pour basculer vers ce format ; avec x-api-key seul, la réponse reste au format OpenAI. display_name est égal à id, ce n’est pas le nom d’affichage de la console. has_more vaut toujours false : la liste est renvoyée en une seule fois, il n’y a pas de pagination. Lorsque la liste est vide, first_id et last_id sont des chaînes vides.

Format Gemini

curl "https://api.routeapi.ai/v1beta/models" \
  -H "x-goog-api-key: $ROUTEAPI_KEY"

{
  "models": [
    { "name": "gemini-2.5-pro", "displayName": "gemini-2.5-pro" }
  ],
  "nextPageToken": null
}

L’objet modèle au format Gemini contient aussi des champs comme inputTokenLimit et supportedGenerationMethods, mais RouteAPI ne remplit que name et displayName ; les autres champs renvoient null. Ne vous appuyez pas sur ces champs vides pour juger des capacités d’un modèle.

Pour la liste des modèles du protocole Gemini, utilisez le chemin /v1beta/models ; n’envoyez pas les en-têtes Gemini sur /v1/models.

Sans le préfixe /v1

Lorsque le client configure la Base URL sans /v1 (par exemple https://api.routeapi.ai), GET /models fonctionne également : la requête est réécrite en interne vers /v1/models.

Les quatre filtres qui déterminent le contenu de la liste

Pour apparaître dans votre liste, un modèle doit passer quatre filtres simultanément. Pour diagnostiquer un « modèle absent de la liste », suivez cet ordre :

1. Liste blanche de modèles du token — si ce token a activé la restriction de modèles, la liste est l’intersection de la liste blanche avec les autres conditions. Si elle n’est pas activée, passez au point suivant.
2. Modèles activés dans le groupe — on prend l’union des modèles activés dans votre groupe d’utilisateurs (et dans le groupe spécifié par le token). Un modèle sans aucun canal disponible n’apparaîtra pas.
3. État de publication au catalogue — lorsque la plateforme active le mode métadonnées strict, un modèle non publié équivaut, vu de l’extérieur, à un modèle inexistant.
4. Prix configuré ou non — les modèles sans prix configuré sont filtrés par défaut, sauf si la plateforme a activé le mode usage interne, ou si l’option « accepter les modèles sans prix » est activée dans les paramètres de votre compte.

Après ces quatre filtres, une liste vide est un résultat normal, pas une erreur. C’est ce qui arrive lorsque aucun modèle du groupe n’est publié.

Sur une même plateforme, les listes de modèles de deux tokens peuvent être totalement différentes. Consulter la liste avec le token A et envoyer la requête avec le token B est un piège courant : lors du diagnostic, utilisez impérativement le même token pour ces deux opérations.

Diagnostiquer un modèle indisponible

Lorsqu’une requête renvoie une erreur liée au modèle, commencez par situer l’étape concernée à partir du texte de l’erreur :

Texte de l’erreur	HTTP	Signification	Traitement
Model name not specified...	400	Le model est vide dans la requête	Ajouter le champ model
This token has no access to model {model}	403	Le modèle n’est pas dans la liste blanche de ce token	Ajouter ce modèle au token dans la console, ou utiliser un token sans restriction de modèles
This token has no access to any models	403	Le token a activé la restriction de modèles mais sa liste blanche est vide	Compléter la liste blanche
No valid upstream service	503	Aucun canal disponible pour le modèle (non configuré, tous désactivés ou en coupe-circuit)	Vérifier l’orthographe de l’ID de modèle ; utiliser un autre modèle de la liste ; contacter l’administrateur de la plateforme
The model '{model}' does not exist	200 (error dans le corps)	GET /v1/models/{model} ne le trouve pas ou il n’est pas visible	Confirmer l’ID exact avec GET /v1/models

Ordre de diagnostic :

1. Appelez GET /v1/models avec le même token pour confirmer que le modèle est bien dans la liste.
2. Vérifiez l’orthographe de model caractère par caractère, casse et traits d’union compris. Les ID de modèle sont en correspondance stricte.
3. Confirmez que le point de terminaison appelé figure dans les supported_endpoint_types de ce modèle.
4. Si tout ce qui précède est correct mais que l’appel échoue encore, le problème est du côté du canal (aucun service en amont disponible ou erreur en amont) : consultez les journaux de la console par request ID pour voir la réponse exacte de l’amont. Voir Erreurs et débogage.

Bonnes pratiques

• Figez les ID de modèle, n’utilisez pas les noms d’affichage de la console ni des alias temporaires. La requête ne reconnaît que id.
• Récupérez la liste une fois au démarrage et mettez-la en cache, n’interrogez pas le point de terminaison à chaque requête métier. L’ensemble des modèles disponibles change très rarement.
• N’utilisez pas created pour trier, c’est une valeur de remplissage fixe partagée par tous les modèles.
• Prévoyez un modèle de secours sur les chemins critiques, à activer lorsque le modèle principal renvoie 503.
• Faites un test réel avec un token de production avant la mise en service, en exécutant à la fois la liste des modèles et un appel réel, de façon à couvrir les appels d’outils, les entrées image et les autres capacités que vous utilisez réellement : ces capacités ne sont pas garanties par le point de terminaison de liste.

Pour aller plus loin

• Authentification — droits des tokens, liste blanche de modèles et configuration des quotas.
• Chat Completions — lancer une conversation avec un modèle de la liste.
• Erreurs et débogage — codes de statut complets et ordre de diagnostic.
• Facturation et quotas — prix des modèles et base de calcul de la consommation.