Modèles et routage

Lister ce que votre clé peut appeler

curl https://app.netaix.fr/v1/models \
  -H "Authorization: Bearer $NETAIX_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "netaix-auto",
      "object": "model",
      "created": 0,
      "owned_by": "netaix",
      "description": "Netaix smart router: picks the tier and the model from the request itself."
    },
    {
      "id": "netaix-fast", "object": "model", "created": 0,
      "owned_by": "netaix", "description": "Fastest, cheapest tier. ..."
    },
    {
      "id": "claude-sonnet-4-5", "object": "model",
      "created": 1793664000, "owned_by": "anthropic"
    }
  ]
}

La réponse commence par les cinq identifiants de niveau, puis liste les modèles du catalogue. Deux choses à savoir :

• Le champ description est un ajout Netaix, présent sur les niveaux seulement. Un client écrit pour l'API d'OpenAI l'ignore sans broncher.
• Cette liste est propre à votre clé. Elle tient compte de ce que votre organisation a ouvert, de ce qui est ouvert à votre compte, et de la liste de modèles éventuellement attachée à la clé. C'est la même source que celle qui autorise l'exécution : ce que cette route affiche est ce que la clé peut appeler.

Les cinq niveaux

Appeler un niveau plutôt qu'un modèle, c'est ce qui permet à votre code de ne pas changer quand le catalogue change. Vous dites ce dont la tâche a besoin, la passerelle choisit le modèle dans ce niveau.

Avec un niveau, le choix est borné à ce niveau : il n'est ni abaissé, ni relevé. Le reste des règles continue de s'appliquer, notamment l'exigence d'un modèle capable de lire une image quand une image est jointe.

Le modèle retenu est rendu dans le champ model de la réponse, aussi bien en bloc qu'en flux. C'est la seule façon de le lire, et elle est fiable.

Appeler un modèle par son nom

Rien ne vous y oblige, mais c'est possible : passez dans model un identifiant rendu par GET /v1/models.

{
  "model": "claude-sonnet-4-5",
  "messages": [{"role": "user", "content": "Bonjour"}]
}

Ce qui se passe quand un modèle est retiré

Un modèle retiré du catalogue, ou fermé par votre organisation, disparaît d'abord de GET /v1/models. Si votre code continue de le demander, la passerelle répond :

{
  "detail": {
    "error": {
      "message": "Model 'xxx' is not enabled for this workspace. Use GET /v1/models to list available models.",
      "type": "permission_error",
      "code": "model_not_allowed"
    }
  }
}

Il n'y a pas de remplacement automatique d'un modèle retiré par un autre : la passerelle préfère un refus lisible à une réponse rendue par un modèle que vous n'avez pas demandé. Deux façons de ne pas être surpris :

• appeler un niveau, et non un nom, partout où le format de sortie n'est pas critique ;
• si vous tenez à un nom, relire GET /v1/models au démarrage de votre application et prévoir un repli.

Les images

Les images s'envoient dans le contenu d'un message, sur POST /v1/chat/completions comme sur POST /v1/messages. La grammaire d'OpenAI (image_url) et celle d'Anthropic (image avec une source en base64) sont toutes deux acceptées et traduites, sur les deux routes. Quand une image est présente, seul un modèle capable de la lire est retenu.

{
  "model": "netaix-balanced",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Que montre ce schéma ?"},
      {"type": "image_url",
       "image_url": {"url": "https://exemple.test/schema.png"}}
    ]
  }]
}

Tous ces refus sont des 422. Ils arrivent avant tout appel au modèle, donc sans consommation.