Référence de l'API REST#

Ultralytics Platform fournit une API REST complète pour l'accès programmatique aux jeux de données, aux modèles, à l'entraînement et aux déploiements.

# List your datasets
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/datasets

Aperçu de l'API#

L'API est organisée autour des ressources principales de la plateforme :

graph LR
    A[API Key]:::start --> B[Datasets]:::proc
    A --> C[Projects]:::proc
    A --> D[Models]:::proc
    A --> E[Deployments]:::proc
    B -->|train on| D
    C -->|contains| D
    D -->|deploy to| E
    D -->|export| F[Exports]:::proc
    B -->|auto-annotate| B

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff

Authentification#

Les API de ressources utilisent l'authentification par clé API, incluant la gestion des classes et des divisions de jeux de données, le clonage, l'entraînement, les exportations, les déploiements et la lecture des comptes pris en charge. Les points de terminaison publics prennent en charge l'accès anonyme là où cela est indiqué. Les routes d'application accessibles uniquement par navigateur sont exclues.

Obtenir une clé API#

1. Va sur Settings > API Keys
2. Clique sur Create Key
3. Copie la clé générée

Consulte les clés API pour des instructions détaillées.

En-tête d'autorisation#

Inclus ta clé API dans toutes les requêtes :

Authorization: Bearer YOUR_API_KEY

Exemple#

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/datasets

URL de base#

Tous les points de terminaison de l'API utilisent :

https://platform.ultralytics.com/api

Limites de taux#

L'API applique des limites par clé API basées sur une fenêtre glissante et soutenues par Upstash Redis. Chaque route utilise la catégorie correspondante ci-dessous.

En cas de limitation du débit, l'API renvoie 429 avec des métadonnées de nouvelle tentative :

Retry-After: 12
X-RateLimit-Reset: 2026-02-21T12:34:56.000Z

Limites par clé API#

Les limites de taux sont appliquées automatiquement en fonction du point de terminaison appelé. Les opérations coûteuses ont des limites plus strictes pour éviter les abus, tandis que les opérations CRUD standard partagent une valeur par défaut généreuse :

Chaque catégorie dispose d'un compteur indépendant par clé API. Par exemple, effectuer 20 requêtes de prédiction n'affecte pas ton allocation par défaut de 100 requêtes/min.

Points de terminaison dédiés (illimité)#

Les points de terminaison dédiés ne sont pas soumis aux limites de débit de la clé API de la plateforme lorsque tu appelles directement l'URL du point de terminaison (par exemple, https://predict-abc123.run.app/predict). Le débit dépend alors de la configuration du service déployé.

Format de réponse#

Réponses de succès#

Les réponses renvoient du JSON avec des champs spécifiques aux ressources :

{
    "datasets": [...],
    "total": 100
}

Réponses d'erreur#

{
    "error": "Dataset not found"
}

API Datasets#

Crée, parcours et gère des jeux de données d'images annotées pour entraîner des modèles YOLO. Consulte la documentation sur les jeux de données.

Lister les Datasets#

GET /api/datasets

Param'tres de requ'te :

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/datasets?limit=10"

R'ponse :

{
    "datasets": [
        {
            "_id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "classNames": ["person", "car"],
            "visibility": "private",
            "username": "johndoe",
            "starCount": 3,
            "isStarred": false,
            "sampleImages": [
                {
                    "url": "https://storage.example.com/...",
                    "width": 1920,
                    "height": 1080,
                    "labels": [{ "classId": 0, "bbox": [0.5, 0.4, 0.3, 0.6] }]
                }
            ],
            "createdAt": "2024-01-15T10:00:00Z",
            "updatedAt": "2024-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

Obtenir un Dataset#

GET /api/datasets/{datasetId}

Renvoie les détails du dataset, y compris les noms de classes, les nombres de splits et d'autres propriétés gérées par la plateforme. Les métadonnées personnalisées sont chargées séparément à partir de l'endpoint de métadonnées ci-dessous.

Passe username lorsque {datasetId} est un identifiant (slug) de jeu de données plutôt qu'un ID.

Cr'er un Dataset#

POST /api/datasets

Corps :

{
    "slug": "my-dataset",
    "name": "My Dataset",
    "task": "detect",
    "description": "A custom detection dataset",
    "metadata": { "location": "factory-1", "reviewed": true },
    "visibility": "private",
    "classNames": ["person", "car"]
}

R'ponse :

{
    "datasetId": "dataset_abc123",
    "slug": "my-dataset",
    "region": "us"
}

Mettre ' jour le Dataset#

PATCH /api/datasets/{datasetId}

Corps (mise ' jour partielle) :

{
    "name": "Updated Name",
    "description": "New description",
    "metadata": { "location": "factory-2", "reviewed": true },
    "visibility": "public"
}

Envoie un objet metadata vide ({}) pour effacer les métadonnées personnalisées. L'objet de métadonnées sérialisé est limité à 500 000 caractères et chaque clé de niveau supérieur est limitée à 128 caractères.

Obtenir les métadonnées du dataset#

GET /api/datasets/{datasetId}/metadata

Renvoie l'objet de métadonnées personnalisées ainsi qu'un ensemble sélectionné de paires champ/valeur gérées par Ultralytics en lecture seule. Les métadonnées personnalisées sont intentionnellement omises des charges utiles normales du dataset. L'authentification et l'accès à l'espace de travail du dataset sont requis.

Icône du jeu de données#

POST /api/datasets/{datasetId}/icon
DELETE /api/datasets/{datasetId}/icon

Télécharge une icône WebP allant jusqu'à 5 Mo en tant que champ de formulaire multipart image, ou supprime l'icône actuelle.

Supprimer le Dataset#

DELETE /api/datasets/{datasetId}

Supprime logiquement le jeu de données (déplacé vers la corbeille, récupérable pendant 30 jours).

Cloner un dataset#

POST /api/datasets/{datasetId}/clone

Crée une copie d'un jeu de données public, appartenant à l'utilisateur ou modifiable, avec toutes les images et étiquettes.

Corps optionnel (tous les champs sont facultatifs) :

{
    "name": "cloned-dataset",
    "slug": "cloned-dataset",
    "description": "My cloned dataset",
    "visibility": "private",
    "license": "AGPL-3.0",
    "owner": "team-username"
}

Exporter le Dataset#

GET /api/datasets/{datasetId}/export

Renvoie une r'ponse JSON avec une URL de t'l'chargement sign'e pour la derni're exportation du dataset.

Param'tres de requ'te :

R'ponse :

{
    "downloadUrl": "https://storage.example.com/export.ndjson?signed=...",
    "cached": true
}

Cr'er une version de Dataset#

POST /api/datasets/{datasetId}/export

Crée un nouvel instantané de version numérotée du jeu de données. Cela nécessite un accès Éditeur ou supérieur. La version capture le nombre actuel d'images, le nombre de classes, le nombre d'annotations et la distribution des répartitions, puis génère et stocke une exportation NDJSON immuable.

Corps de la requ'te :

{
    "description": "Added 500 training images"
}

Tous les champs sont facultatifs. Le champ description est une étiquette fournie par l'utilisateur pour la version.

R'ponse :

{
    "version": 3,
    "downloadUrl": "https://storage.example.com/v3.ndjson?signed=..."
}

Mettre ' jour la description de la version#

PATCH /api/datasets/{datasetId}/export

Met à jour la description d'une version existante. Cela nécessite un accès Éditeur ou supérieur.

Corps de la requ'te :

{
    "version": 2,
    "description": "Fixed mislabeled classes"
}

R'ponse :

{
    "ok": true
}

Restaurer la version du jeu de données#

POST /api/datasets/{datasetId}/restore

Reconstruit les images, annotations et classes du jeu de données à partir d'une version sauvegardée sans copier les octets d'image.

{
    "version": 2
}

Obtenir les statistiques de classe#

GET /api/datasets/{datasetId}/class-stats

Renvoie la distribution des classes, la carte thermique de localisation et les statistiques de dimension. Les r'sultats sont mis en cache jusqu' ' 5 minutes.

R'ponse :

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120 }],
        "heightHistogram": [{ "bin": 480, "count": 95 }],
        "pointsHistogram": [{ "bin": 4, "count": 200 }]
    },
    "locationHeatmap": {
        "bins": [
            [5, 10],
            [8, 3]
        ],
        "maxCount": 50
    },
    "dimensionHeatmap": {
        "bins": [
            [2, 5],
            [3, 1]
        ],
        "maxCount": 12,
        "minWidth": 10,
        "maxWidth": 1920,
        "minHeight": 10,
        "maxHeight": 1080
    },
    "classNames": ["person", "car", "dog"],
    "cached": true,
    "sampled": false,
    "sampleSize": 1000
}

Gérer les classes#

Fusionner les classes (réattribuer les annotations des classes sources à une cible, puis supprimer les sources) :

POST /api/datasets/{datasetId}/classes/merge

{
    "sourceClassIds": [2, 4],
    "targetClassId": 1
}

Les ID de classe sont positionnels, donc la fusion n'est pas idempotente. Récupère à nouveau le jeu de données avant de réessayer.

Supprimer des classes :

POST /api/datasets/{datasetId}/classes/delete

{
    "classIds": [2, 4]
}

Redistribuer les splits#

POST /api/datasets/{datasetId}/splits/redistribute

Réaffecte aléatoirement les images entre les divisions d'entraînement, de validation et de test. Les pourcentages doivent totaliser 100.

{
    "train": 80,
    "val": 20,
    "test": 0
}

Plongements de jeu de données#

GET /api/datasets/{datasetId}/embeddings
POST /api/datasets/{datasetId}/embeddings
DELETE /api/datasets/{datasetId}/embeddings

GET renvoie le résumé actuel de l'analyse UMAP et le statut du travail actif ; POST met en file d'attente un travail d'analyse de plongements ; DELETE annule le travail actif.

Clustering d'images#

GET /api/datasets/{datasetId}/images/clustering

Renvoie la disposition 2D UMAP et les métadonnées par image pour la vue en nuage de points de clustering (paginé et limité en débit).

Obtenir les mod'les entra'n's sur le dataset#

GET /api/datasets/{datasetId}/models

Renvoie les mod'les qui ont 't' entra'n's en utilisant ce dataset.

R'ponse :

{
    "models": [
        {
            "_id": "model_abc123",
            "name": "experiment-1",
            "slug": "experiment-1",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "projectId": "project_xyz",
            "projectSlug": "my-project",
            "projectIconColor": "#3b82f6",
            "projectIconLetter": "M",
            "username": "johndoe",
            "startedAt": "2024-01-14T22:00:00Z",
            "completedAt": "2024-01-15T10:00:00Z",
            "createdAt": "2024-01-14T21:55:00Z",
            "metrics": {
                "mAP50": 0.85,
                "mAP50-95": 0.72,
                "precision": 0.88,
                "recall": 0.81
            }
        }
    ],
    "count": 1
}

Auto-annotation du Dataset#

POST /api/datasets/{datasetId}/predict

Ex'cute l'inf'rence YOLO sur les images du dataset pour g'n'rer automatiquement des annotations. Utilise un mod'le s'lectionn' pour pr'dire les 'tiquettes pour les images non annot'es.

Corps :

Ingestion de Dataset#

POST /api/datasets/ingest

Crée un travail d'ingestion de jeu de données pour un jeu de données existant. Le jeu de données cible est toujours transmis sous la forme datasetId dans le corps JSON, et non dans le chemin de l'URL.

Le corps de la requête nécessite datasetId ainsi qu'exactement l'un des éléments suivants : sessionId (une session de téléchargement d'une archive téléversée) ou sourceUrl (une URL ZIP, TAR, TAR.GZ, TGZ ou NDJSON distante). Ajoute targetSplit (train, val ou test) en option pour remplacer la structure de division de l'archive. Pour joindre des métadonnées personnalisées, utilise imageMetadata, indexé par le chemin exact relatif à l'archive de chaque image ou par la valeur NDJSON file.

Pour les archives téléversées, la session de téléchargement est déjà liée au jeu de données par le paramètre assetId passé à POST /api/upload/signed-url ; l'ingestion valide que assetId correspond au corps datasetId. Des entrées classMapping optionnelles associent chaque nom de classe entrant à un index de classe existant commençant à zéro, à un nom de classe à réutiliser ou à créer, ou à null pour ignorer la classe. Pour les importations distantes sourceUrl, crée d'abord le jeu de données, puis passe son datasetId à l'ingestion.

Corps (archive téléchargée) :

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "targetSplit": "train"
}

Corps (une ou plusieurs images avec métadonnées) :

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "imageMetadata": {
        "airbus-wing.jpg": { "aircraft": { "family": "A350" }, "inspectionStatus": "reviewed" },
        "images/tail.jpg": { "aircraft": { "family": "A320" }, "inspectionSeverity": 2 }
    }
}

Les images locales utilisent le flux de téléchargement d'archive existant, que l'archive contienne une ou plusieurs images. La clé doit correspondre au chemin normalisé à l'intérieur de l'archive, y compris les dossiers. Pour les importations NDJSON, chaque enregistrement d'image peut à la place contenir son propre objet metadata. L'élément local à l'enregistrement metadata a la priorité sur une entrée correspondante imageMetadata.

Les métadonnées sont au format JSON et prennent en charge les valeurs imbriquées. Les chemins d'archive sont limités à 1 024 caractères, les clés de métadonnées de niveau supérieur à 128 caractères et chaque objet de métadonnées à 500 000 caractères sérialisés. La table complète imageMetadata, ou les métadonnées effectives combinées d'une importation NDJSON, est également limitée à 500 000 caractères sérialisés. Ces contraintes sont incluses dans le schéma OpenAPI interactif.

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
dataset_id = "dataset_abc123"
image_path = Path("airbus-wing.jpg")

archive = io.BytesIO()
with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as zf:
    zf.write(image_path, image_path.name)
data = archive.getvalue()

signed = requests.post(
    f"{api}/upload/signed-url",
    headers=headers,
    json={
        "assetType": "datasets",
        "assetId": dataset_id,
        "filename": "images.zip",
        "contentType": "application/zip",
        "totalBytes": len(data),
    },
)
signed.raise_for_status()
upload = signed.json()

requests.put(upload["uploadUrl"], headers={"Content-Type": "application/zip"}, data=data).raise_for_status()
requests.post(
    f"{api}/upload/complete",
    headers=headers,
    json={"sessionId": upload["sessionId"]},
).raise_for_status()

ingest = requests.post(
    f"{api}/datasets/ingest",
    headers=headers,
    json={
        "datasetId": dataset_id,
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

Corps (archive distante ou NDJSON) :

{
    "datasetId": "dataset_abc123",
    "sourceUrl": "https://example.com/my-dataset.zip"
}

Corps (ingestion ultérieure, importation d'étiquettes) :

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "car", "background": null }
}

R'ponse :

{
    "jobId": "job_abc123",
    "datasetId": "dataset_abc123",
    "status": "queued"
}

graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[Upload archive to signed URL]:::proc
    C --> D[POST /api/upload/complete]:::proc
    D --> E[POST /api/datasets/ingest]:::proc
    E --> F[Process archive]:::proc
    F --> G[Dataset ready]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff

Images du Dataset#

Lister les images#

GET /api/datasets/{datasetId}/images

Param'tres de requ'te :

Obtenir les images sélectionnées#

POST /api/datasets/{datasetId}/images

Renvoie la même forme d'image pour un maximum de 1 000 ID d'images fournis. Elle accepte les mêmes contrôles de requête d'URL et d'étiquettes que l'opération de liste.

{
    "imageIds": ["IMAGE_OBJECT_ID"]
}

Obtenir les URLs d'images sign'es#

POST /api/datasets/{datasetId}/images/urls

Obtenir des URLs sign'es pour un lot de hashes d'images (pour l'affichage dans le navigateur).

Supprimer l'image#

DELETE /api/datasets/{datasetId}/images/{hash}

Obtenir les 'tiquettes d'image#

GET /api/datasets/{datasetId}/images/{hash}/labels

Renvoie les annotations et les noms de classes pour une image sp'cifique.

Mettre ' jour les 'tiquettes d'image#

PUT /api/datasets/{datasetId}/images/{hash}/labels

Corps :

{
    "labels": [
        { "classId": 0, "bbox": [0.5, 0.5, 0.2, 0.3] },
        { "classId": 1, "segments": [0.1, 0.2, 0.3, 0.2, 0.2, 0.4] }
    ]
}

Op'rations en masse sur les images#

D'placer des images entre les divisions (train/val/test) au sein d'un dataset :

PATCH /api/datasets/{datasetId}/images/bulk

Suppression en masse d'images :

DELETE /api/datasets/{datasetId}/images/bulk

API Projets#

Organise tes modèles en projets. Chaque modèle appartient à un seul projet. Consulte la documentation sur les projets.

Lister les projets#

GET /api/projects

Param'tres de requ'te :

Obtenir un projet#

GET /api/projects/{projectId}

Cr'er un projet#

POST /api/projects

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-project",
    "slug": "my-project",
    "description": "Detection experiments",
    "metadata": {"department": "manufacturing", "cost_center": "cv-01"}
  }' \
  https://platform.ultralytics.com/api/projects

Mettre ' jour un projet#

PATCH /api/projects/{projectId}

Corps (mise ' jour partielle) :

{
    "metadata": { "department": "research", "program": "inspection" }
}

Envoie un objet metadata vide ({}) pour l'effacer. Les métadonnées du projet utilisent les mêmes limites de clé de niveau supérieur de 128 caractères et d'objet sérialisé de 500 000 caractères que les métadonnées du dataset.

Obtenir les métadonnées du projet#

GET /api/projects/{projectId}/metadata

Renvoie l'objet de métadonnées personnalisées et les paires champ/valeur gérées par Ultralytics en lecture seule. L'authentification et l'accès à l'espace de travail du projet sont requis.

Supprimer un projet#

DELETE /api/projects/{projectId}

Supprime logiquement le projet (déplacé vers la corbeille).

Cloner un projet#

POST /api/projects/{projectId}/clone

Clone un projet d'espace de travail public, possédé ou modifiable ainsi que ses modèles dans ton compte ou ton espace de travail. Un corps JSON optionnel accepte les remplacements de name, slug, description, visibility, license et de la destination owner.

Ic'ne du projet#

POST /api/projects/{projectId}/icon
DELETE /api/projects/{projectId}/icon

Télécharge une icône WebP allant jusqu'à 5 Mo en tant que champ de formulaire multipart image, ou supprime l'icône actuelle.

API Modèles#

Gère les modèles YOLO entraînés — affiche les métriques, télécharge les poids, exécute des inférences et exporte vers d'autres formats. Consulte la documentation sur les modèles.

Lister les modèles#

GET /api/models

Param'tres de requ'te :

Lister les modèles terminés#

GET /api/models/completed

Renvoie jusqu'à 1 000 modèles dotés de poids utilisables dans tous les projets pour l'entraînement et le déploiement. Passe owner pour un espace de travail.

Obtenir un modèle#

GET /api/models/{modelId}

Créer un modèle#

POST /api/models

Corps JSON :

Mettre à jour un modèle#

PATCH /api/models/{modelId}

Corps (mise ' jour partielle) :

{
    "metadata": { "release": "candidate-3", "reviewed": true }
}

Envoie un objet metadata vide ({}) pour l'effacer. Les métadonnées personnalisées du modèle sont distinctes des informations du modèle gérées par l'entraînement, des détails de l'environnement et des arguments d'entraînement, et utilisent les mêmes limites d'objet sérialisé et de clé de niveau supérieur que les métadonnées du dataset.

Obtenir les métadonnées du modèle#

GET /api/models/{modelId}/metadata

Renvoie l'objet de métadonnées personnalisées et les paires champ/valeur gérées par Ultralytics en lecture seule. L'authentification et l'accès à l'espace de travail du modèle sont requis.

Supprimer un modèle#

DELETE /api/models/{modelId}

Télécharger les fichiers du modèle#

GET /api/models/{modelId}/files

Renvoie des URLs de téléchargement signées pour les fichiers du modèle.

Cloner un modèle#

POST /api/models/{modelId}/clone

Clone un modèle public, appartenant à l'utilisateur ou modifiable, vers l'un de tes projets.

Corps :

{
    "targetProjectSlug": "my-project",
    "modelName": "cloned-model",
    "description": "Cloned from public model",
    "owner": "team-username"
}

Suivre le téléchargement#

POST /api/models/{modelId}/track-download

Suis les analyses de téléchargement du modèle.

Exécute l'inférence#

POST /api/models/{modelId}/predict

Les modèles publics peuvent être prédits sans authentification. Les modèles privés et partagés nécessitent une clé API avec accès au projet parent.

Formulaire Multipart :

Fournis soit file, soit source. La taille de téléchargement maximale est de 100 Mo.

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.jpg" \
  -F "conf=0.5" \
  https://platform.ultralytics.com/api/models/MODEL_ID/predict

R'ponse :

Les réponses contiennent, pour chaque image, shape, speed, results et des données de carte de pixels denses optionnelles (une carte de classes sémantiques ou une carte de profondeur où depth = pixel × max / divisor — diviseur 255 pour la carte 8 bits par défaut, 65535 avec bits=12|16), ainsi que metadata avec le nombre d'images, le temps d'exécution de la fonction, la tâche et les versions du service. Les chemins de modèles internes ne sont jamais renvoyés.

{
    "images": [
        {
            "shape": [1080, 1920],
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1
    }
}

API d'entraînement#

Lance l'entraînement YOLO sur des GPU cloud (26 types de GPU allant du RTX 2000 Ada au B300) et surveille la progression en temps réel. Consulte la documentation sur l'entraînement dans le cloud.

graph LR
    A[POST /training/start]:::start --> B[Job Created]:::proc
    B --> C{Training}:::decide
    C -->|progress| D[GET /models/id/training]:::proc
    C -->|cancel| E[DELETE /models/id/training]:::error
    C -->|complete| F[Model Ready]:::out
    F --> G[Deploy or Export]:::proc

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef decide fill:#FF9800,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff

Démarrer l'entraînement#

POST /api/training/start

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "MODEL_ID",
    "projectId": "PROJECT_ID",
    "gpuType": "rtx-4090",
    "trainArgs": {
      "model": "yolo26n.pt",
      "data": "ul://username/datasets/my-dataset",
      "epochs": 100,
      "imgsz": 640,
      "batch": 16
    }
  }' \
  https://platform.ultralytics.com/api/training/start

Obtenir la disponibilité GPU#

GET /api/training/gpu-availability

Renvoie l'état actuel du stock de GPU (High, Medium, Low ou null) indexé par ID de type de GPU. Public, aucune authentification requise ; mis en cache pendant 5 minutes.

Obtenir le statut de l'entraînement#

GET /api/models/{modelId}/training

Renvoie le statut actuel du travail d'entraînement, les métriques, la progression, le timing, les détails du GPU et les erreurs. Les projets publics sont accessibles sans authentification ; les projets privés et partagés nécessitent une clé API avec accès.

Annuler l'entraînement#

DELETE /api/models/{modelId}/training

Termine l'instance de calcul en cours d'exécution et marque le travail comme annulé.

API de déploiements#

Déploie des modèles sur des points de terminaison d'inférence dédiés avec des vérifications d'état et de la surveillance. Par défaut, les nouveaux déploiements utilisent la mise à l'échelle automatique jusqu'à zéro, et l'API accepte un objet resources optionnel. Consulte la documentation sur les points de terminaison.

graph LR
    A[Create]:::start --> B[Deploying]:::proc
    B --> C[Ready]:::out
    C -->|stop| D[Stopped]:::extern
    D -->|start| C
    C -->|delete| E[Deleted]:::error
    D -->|delete| E
    C -->|predict| F[Inference Results]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff
    classDef extern fill:#607D8B,color:#fff

Lister les déploiements#

GET /api/deployments

Param'tres de requ'te :

Créer un déploiement#

POST /api/deployments

Corps :

{
    "modelId": "model_abc123",
    "name": "my-deployment",
    "region": "us-central1",
    "resources": {
        "cpu": 1,
        "memoryGi": 2,
        "minInstances": 0,
        "maxInstances": 1
    }
}

Crée un point de terminaison d'inférence dédié dans la région spécifiée. Le point de terminaison est accessible mondialement via une URL unique.

Obtenir un déploiement#

GET /api/deployments/{deploymentId}

Supprimer un déploiement#

DELETE /api/deployments/{deploymentId}

Démarrer un déploiement#

POST /api/deployments/{deploymentId}/start

Reprend un déploiement arrêté.

Arrêter un déploiement#

POST /api/deployments/{deploymentId}/stop

Arrête de traiter les requêtes en définissant les instances minimales et maximales du service à zéro.

Vérification de santé#

GET /api/deployments/{deploymentId}/health

Renvoie le statut de santé du point de terminaison de déploiement.

Exécuter l'inférence sur le déploiement#

POST /api/deployments/{deploymentId}/predict

Envoie une image directement à un point de terminaison de déploiement pour inférence. Fonctionnellement équivalent à la prédiction de modèle, mais acheminé via le point de terminaison dédié pour une latence plus faible.

Formulaire Multipart :

Fournis soit file, soit source. La réponse utilise le même contrat d'image et de métadonnées que la prédiction de modèle et ne renvoie jamais le chemin du modèle interne.

Obtenir les métriques#

GET /api/deployments/{deploymentId}/metrics

Renvoie les nombres de requêtes, la latence et les métriques de taux d'erreur avec des données de sparkline.

Param'tres de requ'te :

Obtenir les logs#

GET /api/deployments/{deploymentId}/logs

Param'tres de requ'te :

API d'exportation#

Convertis des modèles vers des formats optimisés tels que ONNX, TensorRT, CoreML et LiteRT pour le déploiement en périphérie (edge). Consulte la documentation sur le déploiement.

Lister les exportations#

GET /api/exports

Param'tres de requ'te :

Créer une exportation#

POST /api/exports

Corps :

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"modelId": "MODEL_ID", "format": "onnx"}' \
  https://platform.ultralytics.com/api/exports

Formats pris en charge :

Utilise l'argument format du tableau d'exportation partagé ci-dessous. PyTorch est le format source et ne constitue pas une cible d'exportation de l'API.

Obtenir le statut d'exportation#

GET /api/exports/{exportId}

Annuler l'exportation#

DELETE /api/exports/{exportId}

Suivre le téléchargement de l'exportation#

POST /api/exports/{exportId}/track-download

API d'activité#

Consulte le fil d'actualité des actions récentes sur ton compte — exécutions d'entraînement, téléversements, etc. Consulte la documentation sur l'activité.

Lister l'activité#

GET /api/activity

Param'tres de requ'te :

Marquer les événements comme vus#

POST /api/activity/mark-seen

Corps :

{
    "all": true
}

Ou passe des IDs spécifiques :

{
    "eventIds": ["EVENT_ID_1", "EVENT_ID_2"]
}

Passe le paramètre de requête optionnel owner pour marquer des événements dans un espace de travail.

Archiver les événements#

POST /api/activity/archive

Corps :

{
    "all": true,
    "archive": true
}

Ou passe des IDs spécifiques :

{
    "eventIds": ["EVENT_ID_1", "EVENT_ID_2"],
    "archive": false
}

Passe le paramètre de requête optionnel owner pour archiver ou restaurer des événements de l'espace de travail.

API de corbeille#

Affichez et restaurez les éléments supprimés. Les éléments sont définitivement supprimés après 30 jours. Consulte la documentation sur la corbeille.

Lister la corbeille#

GET /api/trash

Param'tres de requ'te :

Restaurer l'élément#

POST /api/trash

Corps :

{
    "id": "item_abc123",
    "type": "dataset"
}

Supprimer définitivement l'élément#

DELETE /api/trash

Corps :

{
    "id": "item_abc123",
    "type": "dataset"
}

Vider la corbeille#

DELETE /api/trash/empty

Supprime définitivement tous les éléments dans la corbeille.

API de facturation#

Vérifie ton solde de crédits, l'utilisation de ton forfait et ton historique des transactions. Consulte la documentation sur la facturation.

Les points de terminaison du solde et des transactions acceptent un paramètre de requête optionnel owner contenant le nom d'utilisateur du propriétaire de l'espace de travail.

Obtenir le solde#

GET /api/billing/balance

R'ponse :

{
    "creditsCents": 2500,
    "plan": "free"
}

Obtenir le résumé de l'utilisation#

GET /api/billing/usage-summary

Renvoie les détails du plan, les limites et les métriques d'utilisation.

Obtenir les transactions#

GET /api/billing/transactions

Renvoie l'historique des transactions (les plus récentes en premier).

Les transactions incluent des champs de grand livre destinés au client tels que le montant, le solde résultant, la date, le contexte de modèle optionnel et l'URL du reçu. Les notes internes, les ID de paiement/remboursement Stripe et les clés d'idempotence ne sont pas renvoyés.

API de stockage#

Vérifie la répartition de ton utilisation du stockage par catégorie (datasets, modèles, exports) et identifie tes éléments les plus volumineux.

Obtenir les informations de stockage#

GET /api/storage

Param'tres de requ'te :

R'ponse :

{
    "tier": "free",
    "usage": {
        "storage": {
            "current": 1073741824,
            "limit": 107374182400,
            "percent": 1.0
        }
    },
    "region": "us",
    "username": "johndoe",
    "updatedAt": "2024-01-15T10:00:00Z",
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "dataset_abc123",
                "name": "my-dataset",
                "slug": "my-dataset",
                "sizeBytes": 536870912,
                "type": "dataset"
            },
            {
                "_id": "model_def456",
                "name": "experiment-1",
                "slug": "experiment-1",
                "sizeBytes": 134217728,
                "type": "model",
                "parentName": "My Project",
                "parentSlug": "my-project"
            }
        ]
    }
}

Intégrations de stockage cloud#

Connecte et parcours les intégrations de stockage GCS, S3 ou Azure Blob en lecture seule :

GET /api/integrations/buckets
POST /api/integrations/buckets
POST /api/integrations/buckets/discover
GET /api/integrations/buckets/{id}/objects

Les quatre opérations acceptent le paramètre de requête optionnel owner pour un espace de travail. La navigation dans les objets accepte également le paramètre requis target ainsi que les paramètres optionnels prefix et fournisseur cursor. Les corps de requêtes de connexion et de découverte utilisent les schémas d'identifiants du fournisseur dans la référence OpenAPI interactive ; les identifiants ne sont jamais renvoyés.

API de téléchargement#

Télécharge des fichiers directement vers le stockage cloud à l'aide d'URL signées pour des transferts rapides et fiables. La fin du téléchargement d'un modèle y associe ses poids. La fin du téléchargement d'une archive de jeu de données enregistre la session ; passe ce sessionId à POST /api/datasets/ingest pour lancer le traitement. Consulte la documentation sur les données.

Obtenir une URL de téléchargement signée#

POST /api/upload/signed-url

Demande une URL signée pour télécharger un fichier directement vers le stockage cloud. L'URL signée contourne le serveur API pour les transferts de fichiers volumineux.

Corps :

{
    "assetType": "datasets",
    "assetId": "dataset_abc123",
    "filename": "my-dataset.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

R'ponse :

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

Terminer le téléchargement#

POST /api/upload/complete

Notifie la plateforme qu'un téléchargement de fichier est terminé. Pour les modèles, cela associe les poids téléchargés. Pour les archives de jeux de données, cela vérifie et enregistre la session de téléchargement ; appelle POST /api/datasets/ingest ensuite pour lancer le traitement du jeu de données.

Corps :

{
    "sessionId": "session_abc123",
    "checksum": "<optional sha-256 hex>"
}

API d'intégrations#

Importe des jeux de données depuis des services tiers. Consulte la documentation sur les intégrations.

Prévisualiser l'importation Roboflow#

POST /api/integrations/roboflow/preview

Résout une clé API Roboflow en un plan d'importation en masse : informations sur l'espace de travail, quels projets seraient nouvellement importés, nombre de versions déjà importées (ignorées) et types de projets non pris en charge. La clé API Roboflow est transmise dans le corps et n'est pas persistée.

Importer depuis Roboflow#

POST /api/integrations/roboflow/import

Mettre en file d'attente des travaux d'ingestion de jeu de données pour importer les projets Roboflow sélectionnés dans ton espace de travail. Nécessite de l'espace de stockage disponible, et chaque jeu de données doit respecter la limite de taille par importation de ton plan.

API des clés API#

Gère tes clés API pour l'accès programmatique. Consulte la documentation sur les clés API.

Lister les clés API#

GET /api/api-keys

Les clients authentifiés par clé API reçoivent les métadonnées de la clé, mais jamais les valeurs des clés existantes déchiffrées. Une clé nouvellement créée est renvoyée une seule fois par POST /api/api-keys.

Passe le paramètre de requête optionnel owner pour gérer les clés d'un espace de travail où tu possèdes un accès d'éditeur.

Créer une clé API#

POST /api/api-keys

Corps :

{
    "name": "training-server"
}

Supprimer une clé API#

DELETE /api/api-keys

Param'tres de requ'te :

Exemple :

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/api-keys?keyId=KEY_ID"

API des équipes et des membres#

Crée des espaces de travail d'équipe, invite des membres et gère les rôles pour la collaboration. Consulte la documentation sur les équipes.

Lister les équipes#

GET /api/teams

Créer une équipe#

POST /api/teams/create

Corps :

{
    "username": "my-team",
    "fullName": "My Team"
}

Lister les membres#

GET /api/members

Renvoie les membres de l'espace de travail actuel.

Inviter un membre#

POST /api/members

Corps :

{
    "email": "user@example.com",
    "role": "editor"
}

Mettre à jour le rôle d'un membre#

PATCH /api/members/{userId}

Supprimer un membre#

DELETE /api/members/{userId}

Transférer la propriété#

POST /api/members/transfer-ownership

Explorer l'API#

Recherche et parcours des jeux de données et des projets publics partagés par la communauté. Consulte la documentation sur l'exploration.

Rechercher du contenu public#

GET /api/explore/search

Param'tres de requ'te :

Données de la barre latérale#

GET /api/explore/sidebar

Renvoie du contenu sélectionné pour la barre latérale Explore.

API utilisateur et paramètres#

Gère ton profil, tes clés API, ton utilisation du stockage et tes espaces de travail d'équipe. Consulte la documentation sur les paramètres.

Résumé du compte#

GET /api/account/summary

Renvoie le forfait du compte authentifié, le solde de crédits, le nombre de ressources et les espaces de travail d'équipe.

Obtenir l'utilisateur par nom d'utilisateur#

GET /api/users

Param'tres de requ'te :

Suivre ou ne plus suivre un utilisateur#

PATCH /api/users

Corps :

{
    "username": "target-user",
    "followed": true
}

Vérifier la disponibilité du nom d'utilisateur#

GET /api/username/check

Param'tres de requ'te :

Paramètres#

GET /api/settings
POST /api/settings

Obtenir ou mettre à jour les paramètres du profil utilisateur (nom d'affichage, bio, liens sociaux, etc.).

Icône de l'espace de travail#

POST /api/settings/icon
DELETE /api/settings/icon

Télécharge une icône de profil/d'espace de travail WebP allant jusqu'à 5 Mo en tant que champ de formulaire multipart image, ou supprime-la. Passe owner en option pour un espace de travail d'équipe.

Intégration Python#

Pour une intégration plus simple, utilise le package Python Ultralytics qui gère automatiquement l'authentification, les téléchargements et la diffusion de métriques en temps réel.

Installation et configuration#

pip install "ultralytics>=8.4.104"

Vérifie l'installation :

yolo check

Authentification#

yolo login YOUR_API_KEY

Utilisation des datasets de la plateforme#

Référence les jeux de données avec les URI ul:// :

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Train on your Platform dataset
model.train(
    data="ul://your-username/datasets/your-dataset",
    epochs=100,
    imgsz=640,
)

Format d'URI :

Envoi vers la plateforme#

Envoie les résultats vers un projet de la plateforme :

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Results automatically sync to Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="your-username/my-project",
    name="experiment-1",
)

Ce qui est synchronisé :

• Métriques d'entraînement (temps réel)
• Poids finaux du modèle
• Graphiques de validation
• La sortie console
• Métriques système

Exemples d'API#

Charge un modèle depuis la plateforme :

# Your own model
model = YOLO("ul://username/project/model-name")

# Official model
model = YOLO("ul://ultralytics/yolo26/yolo26n")

Exécute une inférence :

results = model("image.jpg")

# Access results
for r in results:
    boxes = r.boxes  # Detection boxes
    masks = r.masks  # Segmentation masks
    keypoints = r.keypoints  # Pose keypoints
    probs = r.probs  # Classification probabilities

Exporte un modèle :

# Export to ONNX
model.export(format="onnx", imgsz=640, quantize=16)

# Export to TensorRT
model.export(format="engine", imgsz=640, quantize=16)

# Export to CoreML
model.export(format="coreml", imgsz=640)  # use imgsz=224 for classification

Validation :

metrics = model.val(data="ul://username/datasets/my-dataset")

print(f"mAP50: {metrics.box.map50}")
print(f"mAP50-95: {metrics.box.map}")

FAQ#

Comment paginer de grands résultats ?#

La plupart des points de terminaison utilisent un paramètre limit pour contrôler le nombre de résultats renvoyés par requête :

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/datasets?limit=50"

Les points de terminaison Activité et Corbeille prennent également en charge un paramètre page pour la pagination basée sur les pages :

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/activity?page=2&limit=20"

L'endpoint Explore Search utilise offset au lieu de page, avec une taille de page fixe de 20 :

curl "https://platform.ultralytics.com/api/explore/search?type=datasets&offset=20&sort=stars"

Puis-je utiliser l'API sans SDK ?#

Les opérations REST publiques documentées ci-dessus sont disponibles sans le SDK Python. Le SDK est un wrapper de commodité qui ajoute des fonctionnalités telles que la diffusion de métriques en temps réel et les téléchargements automatiques de modèles. Tu peux explorer le contrat lisible par machine de manière interactive sur platform.ultralytics.com/api/docs ; les flux de compte réservés à la session de navigateur restent dans l'UI de la Platform.

Existe-t-il des bibliothèques clientes API ?#

Utilise le paquet Python Ultralytics ou effectue des requêtes HTTP directes depuis n'importe quel langage.

Comment gérer les limites de débit ?#

Utilise l'en-tête Retry-After de la réponse 429 pour attendre la durée appropriée :

import time

import requests

def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code != 429:
            return response
        wait = int(response.headers.get("Retry-After", 2**attempt))
        time.sleep(wait)
    raise RuntimeError("Rate limit exceeded")

Comment trouver l'ID de mon modèle ou de mon dataset ?#

Les identifiants de ressources sont renvoyés par les réponses API de création, de liste et de récupération. Les URL des pages de la plateforme utilisent des slugs lisibles par l'homme, et non des identifiants de base de données :

https://platform.ultralytics.com/username/project/model-name
                                  ^^^^^^^^ ^^^^^^^ ^^^^^^^^^^
                                  username project   model

Utilise les endpoints de liste pour trouver le _id correspondant pour un modèle, un jeu de données, un projet, un déploiement ou une autre ressource.