Conventions de l’API - CoreWeave Docs

Cette page décrit les conventions que la Management API de Model Distillation applique à l’ensemble de ses points de terminaison. Elle explique comment les projets apparaissent dans les chemins et les champs de l’API, comment référencer des modèles et comment interpréter le statut asynchrone. Elle précise également le comportement des erreurs, de la pagination et des requêtes de création ou de remplacement. Avant d’écrire des scripts qui utilisent l’API ou de créer un agent qui l’appelle, lisez cette page pour que votre client gère correctement les traitements asynchrones et les nouvelles tentatives.

Projets

L’interface utilisateur et la Management API désignent toutes deux par le terme « projet » l’unité que vous optimisez :

Les chemins de l’API commencent par /projects/{alias}, où alias est le nom de modèle proxy affiché dans l’interface utilisateur.
Certains champs de requête et de réponse conservent l’ancien nom « task » : task_alias, task_id et task_version, qui correspond à la version du projet. Les requêtes sur les datasets filtrent par task_version, et un dataset construit à partir du trafic du proxy définit source sur "task".
Les anciens chemins /tasks/... sont obsolètes. Ils restent fonctionnels jusqu’au 26 octobre 2026 à 00:00 UTC, et leurs réponses comportent les en-têtes Deprecation, Sunset et Link, qui indiquent le chemin de remplacement. Passé ce délai, ils renvoient le code HTTP 410 avec le type d’erreur endpoint_moved et un message indiquant le chemin de remplacement.

Le projet W&B dans lequel sont stockées les traces d’un projet est une ressource distincte. Définissez-le avec project et project_mode lors de la création d’un projet.

Références de modèles

Les champs des requêtes de gestion utilisent le format suivant :

{provider-name}/{provider-model-id}

Le nom du fournisseur est en minuscules et permet d’identifier les identifiants d’authentification stockés. L’ID du modèle est défini par le fournisseur et peut contenir des barres obliques supplémentaires ou un paramètre de requête encodé indiquant le niveau d’effort de raisonnement.

Opérations asynchrones

202 Accepted signifie que l’état souhaité ou le traitement en arrière-plan a été enregistré, et non que la ressource est déjà en service ou que le traitement est terminé. Interrogez la ressource renvoyée :

Le statut de déploiement du fournisseur et de l’acheminement doit passer à applied pour la révision actuelle.
Les datasets passent à l’état ready ou failed.
Les runs de réétiquetage passent à l’état completed, failed ou stale.
Les modèles issus du fine-tuning passent à l’état deployed ou failed.
Les évaluations indiquent en temps réel le nombre de cas et peuvent se terminer avec des cas en échec.
Les suppressions de datasets et de modèles issus du fine-tuning renvoient 202 Accepted avec une opération de suppression. Pour suivre sa progression, renvoyez la requête DELETE ou consultez le point de terminaison deletion-plan.

Erreurs

Les erreurs de la Management API utilisent le format suivant :

{
  "error": {
    "message": "Project 'missing' not found in entity 'your-team'",
    "type": "not_found"
  }
}

En cas d’échec de validation, l’API renvoie 400 Bad Request si le JSON est mal formé, que ce soit dans le corps de la requête ou dans un paramètre de requête encodé en JSON, ou 422 Unprocessable Entity si le corps de la requête ou une valeur de requête n’est pas conforme à son schéma. Les conflits, comme la suppression d’un fournisseur encore référencé, renvoient 409 Conflict. Une requête d’écriture reçue via l’ingress public depuis un pays ou une région non pris en charge renvoie 403 Forbidden avec le type region_restricted.

Pagination

Les entrées de dataset utilisent une pagination par numéro de page :

GET .../entries?page=1&limit=50

La valeur de limit doit être comprise entre 1 et 200. La réponse contient page, limit, total et entries. Les filtres d’entrées et le tri des évaluations sont des paramètres de requête encodés en JSON. Lorsque vous construisez vos requêtes, encodez le JSON sérialisé au format URL.

Comportement de création et de remplacement

Les opérations d’écriture de gestion ne se comportent pas toutes de la même façon lorsqu’une requête est répétée. Pour relancer une requête en toute sécurité, vous devez savoir quels appels remplacent l’état et lesquels créent de nouvelles ressources :

PUT /providers/{name} crée un fournisseur ou le fait pivoter.
PUT /projects/{alias} crée un projet et renvoie un conflit si le projet existe déjà.
Le PUT d’acheminement remplace toutes les cibles de cette version.
Les requêtes POST de dataset, de fine-tuning et d’évaluation créent de nouvelles ressources et peuvent consommer des ressources de calcul.
Les requêtes DELETE de dataset et de fine-tuning mettent en file d’attente une suppression durable en une seule requête. Une requête répétée renvoie l’opération existante, relance le nettoyage ayant échoué ou renvoie 204 No Content si la ressource n’existe plus.

Lorsque vous relancez des appels de création non idempotents après une défaillance réseau à l’issue incertaine, utilisez des ID de requête côté client ainsi que votre propre état d’orchestration.

API : gestion sécurisée des requêtes

Utilisez la spécification OpenAPI de gestion comme source de référence pour les méthodes, les chemins, les schémas et les codes de statut. Lorsqu’un agent appelle l’API, il doit procéder comme suit :

Résoudre chaque espace réservé à partir de valeurs fournies par l’utilisateur ou renvoyées précédemment.
Présenter à l’utilisateur toute requête qui lance des ressources de calcul payantes ou remplace l’acheminement.
Considérer 202 Accepted comme le début du traitement et interroger la ressource documentée.
Conserver les ID de ressource renvoyés au lieu de rechercher à nouveau les ressources par leur nom.
S’arrêter en cas de statut inattendu plutôt que de relancer automatiquement une opération de création.

​Projets

​Références de modèles

​Opérations asynchrones

​Erreurs

​Pagination

​Comportement de création et de remplacement