AI Endpoints - API Catalog

Introduction

https://oai.endpoints.kepler.ai.cloud.ovh.net/v1 est l'endpoint de base utilisé pour appeler les modèles AI Endpoints (voir les guides AI Endpoints - Premiers pas et AI Endpoints - API Responses). Cet article ne traite pas de cet endpoint ; il porte sur une API distincte, la Catalog API, un service de découverte permettant de parcourir les modèles disponibles et leurs métadonnées.

L'URL du catalogue https://catalog.endpoints.ai.ovh.net/rest/v1/models_v2 fournit les informations et les métadonnées relatives aux modèles AI Endpoints. Cette API vous permet de lister les modèles, les fonctionnalités prises en charge, la tarification et les métadonnées propres à chaque modèle.

Objectif

Cette documentation montre comment interroger la Catalog API, lire les métadonnées des modèles et filtrer la réponse côté client, avec des exemples en Python, JavaScript et cURL.

Prérequis

Les exemples de ce guide peuvent être utilisés avec l'un des environnements suivants :

pip install requests

npm install node-fetch

Authentification

Contrairement aux routes v1/responses et v1/chat/completions, l'endpoint du catalogue est public et ne nécessite pas de clé API. Vous pouvez l'interroger directement, sans en-tête Authorization.

Si vous prévoyez également d'appeler les modèles qui y sont listés, suivez le guide AI Endpoints - Premiers pas pour obtenir une clé API pour ces appels.

Lister tous les modèles

Une seule requête GET renvoie le catalogue complet sous forme de tableau JSON. L'endpoint n'accepte aucun paramètre de requête.

import requests

url = "https://catalog.endpoints.ai.ovh.net/rest/v1/models_v2"

response = requests.get(url)
response.raise_for_status()

catalog = response.json()
print(catalog)

import fetch from "node-fetch";

const url = "https://catalog.endpoints.ai.ovh.net/rest/v1/models_v2";

const response = await fetch(url);

const catalog = await response.json();
console.log(catalog);

curl "https://catalog.endpoints.ai.ovh.net/rest/v1/models_v2"

Métadonnées des modèles

Chaque entrée du tableau expose les champs suivants :

• id, name, description
• available : indique si le modèle peut actuellement être appelé. Certaines entrées sont listées avec available: false ; vérifiez donc ce champ avant de router du trafic vers un modèle.
• category : la famille du modèle, l'une des valeurs Large Language Models (LLM), Visual LLM, Reasoning LLM, Code LLM, Embeddings, Image Generation, LLM Guard, Speech To Text ou Text To Speech
• tags : des libellés courts tels que Reasoning, Multimodal, Code Assistant ou Moderation
• metadata.model_specs.capabilities : input_modality et output_modality, des tableaux tels que ["text", "image"], ainsi que les booléens reasoning, function_calling et streaming
• metadata.publishing_information : publisher, series, licence_name, model_publication_date
• metadata.usage_information.pricing : prix et unité pour l'usage des prompts et des complétions
• metadata.usage_information.rate_limit : limites de débit des requêtes, réparties entre rate_limit_api (avec une clé API), rate_limit_api_anonymous (sans clé) et rate_limit_playground

Utilisez les champs de capacités pour choisir un modèle avant d'appeler la route v1/responses : un input_modality contenant image pour les cas d'usage de vision, function_calling pour l'appel d'outils, et reasoning pour les modes de raisonnement.

Filtrer le catalogue

Chaque appel renvoie le catalogue complet ; le filtrage, la recherche et le tri s'effectuent donc sur le tableau renvoyé. Les exemples ci-dessous ne conservent que les modèles compatibles avec la vision, puis recherchent une entrée unique par id.

import requests

url = "https://catalog.endpoints.ai.ovh.net/rest/v1/models_v2"

response = requests.get(url)
response.raise_for_status()
catalog = response.json()

vision_models = [
    model for model in catalog
    if "image" in model["metadata"]["model_specs"]["capabilities"]["input_modality"]
]
print(vision_models)

model = next((m for m in catalog if m["id"] == "gpt-oss-20b"), None)
print(model)

import fetch from "node-fetch";

const url = "https://catalog.endpoints.ai.ovh.net/rest/v1/models_v2";

const response = await fetch(url);
const catalog = await response.json();

const visionModels = catalog.filter((model) =>
  model.metadata.model_specs.capabilities.input_modality.includes("image")
);
console.log(visionModels);

const model = catalog.find((m) => m.id === "gpt-oss-20b");
console.log(model);

curl -s "https://catalog.endpoints.ai.ovh.net/rest/v1/models_v2" | \
  jq '[.[] | select(.metadata.model_specs.capabilities.input_modality | index("image"))]'

curl -s "https://catalog.endpoints.ai.ovh.net/rest/v1/models_v2" | \
  jq '.[] | select(.id == "gpt-oss-20b")'

Conclusion

Utilisez la Catalog API pour découvrir les modèles disponibles et vérifier leurs capacités, fonctionnalités, tarifs et limites de débit avant d'appeler l'API d'exécution.

Aller plus loin

L'utilisation de la Catalog API est nécessaire dans l'article Deploy Langfuse on OVHcloud MKS for LLM observability and AI cost tracking. Cet article récupère le bloc metadata.usage_information.pricing du catalogue pour enregistrer le prix de chaque modèle dans Langfuse, qui calcule ensuite automatiquement le coût de vos appels AI Endpoints.

Pour une formation ou une assistance technique dans la mise en oeuvre de nos solutions, contactez votre commercial ou consultez notre page Professional Services afin de demander un devis et de faire analyser votre projet par nos experts.

Votre avis nous intéresse !

N’hésitez pas à nous faire part de vos questions, retours et suggestions pour améliorer le service :

• Sur le serveur Discord OVHcloud.