Référence de l'API REST

La plateforme Ultralytics fournit une API REST complète pour un accès programmatique aux jeux de données, modèles, entraînements et 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] --> B[Datasets]
    A --> C[Projects]
    A --> D[Models]
    A --> E[Deployments]
    B -->|train on| D
    C -->|contains| D
    D -->|deploy to| E
    D -->|export| F[Exports]
    B -->|auto-annotate| B

Authentification

Les API de ressources telles que les jeux de données, projets, modèles, entraînement, exports et prédictions utilisent l'authentification par clé API. Les points de terminaison publics (lister les jeux de données publics, projets et modèles) prennent en charge l'accès en lecture anonyme sans clé. Les itinéraires orientés vers le compte — incluant l'activité, les paramètres, les équipes, la facturation et les flux RGPD — nécessitent actuellement une session de navigateur authentifiée et ne sont pas disponibles via une clé API.

Obtenir une clé API

1. Go to Settings > API Keys
2. Click 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 :

Limites de débit

L'API applique des limites de débit par clé API (fenêtre glissante, basée sur Upstash Redis) pour se protéger contre les abus tout en gardant une utilisation légitime sans restriction. Le trafic anonyme est en outre protégé par les contrôles d'abus au niveau de la plateforme Vercel.

Lorsque tu es limité, 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 débit 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 a 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. Lorsque tu déploies un modèle vers un point de terminaison dédié, les requêtes vers cette URL de point de terminaison (par ex. https://predict-abc123.run.app/predict) vont directement à ton service dédié sans limitation de débit de la part de la plateforme. Tu paies pour le calcul, tu obtiens donc le débit de ta configuration de service dédiée plutôt que les limites de l'API partagée.

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 des jeux de données

Crée, navigue et gère des jeux de données d'images étiquetées pour l'entraînement de modèles YOLO. Consulte la documentation des jeux de données.

Lister les jeux de données

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 complets du dataset, y compris les métadonnées, les noms de classes et les nombres par split.

Créer un dataset

POST /api/datasets

Corps :

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

Mettre à jour un dataset

PATCH /api/datasets/{datasetId}

Corps (mise à jour partielle) :

{
    "name": "Updated Name",
    "description": "New description",
    "visibility": "public"
}

Supprimer un dataset

DELETE /api/datasets/{datasetId}

Suppression logique du dataset (déplacé vers la corbeille, récupérable pendant 30 jours).

Cloner un dataset

POST /api/datasets/{datasetId}/clone

Crée une copie du dataset avec toutes ses images et étiquettes. Seuls les datasets publics peuvent être clonés. Nécessite une session de navigateur active sur la plateforme — non disponible via une clé API.

Corps (tous les champs sont optionnels) :

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

Exporter un 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éer un nouveau snapshot numéroté du dataset. Réservé au propriétaire. La version capture le nombre actuel d'images, de classes, d'annotations et la répartition des splits, puis génère et stocke une exportation NDJSON immuable.

Corps de la requête :

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

Tous les champs sont optionnels. 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

Mettre à jour la description d'une version existante. Réservé au propriétaire.

Corps de la requête :

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

Réponse :

{
    "ok": true
}

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 pendant 5 minutes maximum.

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
}

Obtenir les modèles entraînés sur le dataset

GET /api/datasets/{datasetId}/models

Renvoie les modèles 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
}

Annotation automatique du dataset

POST /api/datasets/{datasetId}/predict

Exécute une 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 des images non annotées.

Corps :

Ingestion de dataset

POST /api/datasets/ingest

Crée un job d'ingestion de dataset pour traiter les fichiers ZIP ou TAR téléchargés, y compris .tar.gz et .tgz, contenant des images et des étiquettes.

graph LR
    A[Upload Archive] --> B[POST /api/datasets/ingest]
    B --> C[Process Archive]
    C --> D[Extract images]
    C --> E[Parse labels]
    C --> F[Generate thumbnails]
    D & E & F --> G[Dataset ready]

Images du dataset

Lister les images

GET /api/datasets/{datasetId}/images

Paramètres de requête :

Obtenir les URLs d'image signées

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

Obtenir des URLs signées pour un lot de hachages d'image (pour l'affichage dans le navigateur).

Supprimer une image

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

Obtenir les étiquettes d'une 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'une 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 groupées sur les images

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

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

Suppression groupée d'images :

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

API Projets

Organise tes modèles en projets. Chaque modèle appartient à un projet. Voir la documentation des 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"}' \
  https://platform.ultralytics.com/api/projects

Mettre à jour un projet

PATCH /api/projects/{projectId}

Supprimer un projet

DELETE /api/projects/{projectId}

Suppression logique du projet (déplacé vers la corbeille).

Cloner un projet

POST /api/projects/{projectId}/clone

Clone un projet public (avec tous ses modèles) dans ton espace de travail. Nécessite une session de navigateur active sur la plateforme — non disponible via une clé API.

Icône du projet

Téléverser une icône de projet (formulaire multipart avec fichier image) :

POST /api/projects/{projectId}/icon

Supprimer l'icône du projet :

DELETE /api/projects/{projectId}/icon

Les deux nécessitent une session de navigateur active sur la plateforme — non disponible via une clé API.

API Modèles

Gère tes modèles YOLO entraînés — consulte les métriques, télécharge les poids, exécute l'inférence et exporte vers d'autres formats. Voir la documentation des 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 les modèles dont l'entraînement est terminé (pour une utilisation dans les sélecteurs de modèles et le déploiement).

Obtenir un modèle

GET /api/models/{modelId}

Créer un modèle

POST /api/models

Corps JSON :

Mettre à jour le modèle

PATCH /api/models/{modelId}

Supprimer le modèle

DELETE /api/models/{modelId}

Télécharger les fichiers modèle

GET /api/models/{modelId}/files

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

Cloner le modèle

POST /api/models/{modelId}/clone

Clone un modèle public vers l'un de tes projets. Nécessite une session de navigateur active sur la plateforme — non disponible via une clé API.

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 de modèle.

Exécuter l'inférence

POST /api/models/{modelId}/predict

Formulaire multipart :

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 :

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

Obtenir un jeton de prédiction

POST /api/models/{modelId}/predict/token

Pré-chauffage du modèle

POST /api/models/{modelId}/predict/warmup

API d'entraînement

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

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

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 le statut de l'entraînement

GET /api/models/{modelId}/training

Renvoie le statut actuel du job d'entraînement, les métriques et la progression d'un modèle. Les projets publics sont accessibles de manière anonyme ; les projets privés nécessitent une session de navigateur active sur la plateforme (cette route n'accepte pas l'authentification par clé API).

Annuler l'entraînement

DELETE /api/models/{modelId}/training

Termine l'instance de calcul en cours et marque le job comme annulé. Nécessite une session de navigateur active sur la plateforme — non disponible via une clé API.

API Déploiements

Déploie des modèles sur des points de terminaison d'inférence dédiés avec des contrôles de santé et une surveillance. Les nouveaux déploiements utilisent par défaut le scale-to-zero, et l'API accepte un objet resources optionnel. Voir la documentation des points de terminaison.

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

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

Suspend un déploiement en cours (arrête la facturation).

Contrôle 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 routé via le point de terminaison dédié pour une latence plus faible.

Formulaire multipart :

Obtenir les métriques

GET /api/deployments/{deploymentId}/metrics

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

Paramètres de requête :

Obtenir les journaux

GET /api/deployments/{deploymentId}/logs

Paramètres de requête :

API de surveillance

Métriques agrégées

GET /api/monitoring

Renvoie les métriques agrégées pour tous les déploiements utilisateur : nombre total de requêtes, déploiements actifs, taux d'erreur et latence moyenne.

API d'exportation

Convertis tes modèles vers des formats optimisés comme ONNX, TensorRT, CoreML et TFLite pour un déploiement en périphérie. Consulte la documentation de 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 :

Obtenir l'état de l'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 flux des actions récentes sur ton compte : entraînements, téléversements et plus. Consulte la documentation d'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"]
}

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
}

API de corbeille

Affiche et restaure les éléments supprimés. Les éléments sont définitivement supprimés après 30 jours. Consulte la documentation de la corbeille.

Lister la corbeille

GET /api/trash

Paramètres de requête :

Restaurer un é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 de la corbeille.

API de facturation

Vérifie ton solde de crédits, achète des crédits, consulte ton historique de transactions et configure le rechargement automatique. Consulte la documentation de facturation.

Obtenir le solde

GET /api/billing/balance

Paramètres de requête :

Réponse :

{
    "creditsCents": 2500,
    "plan": "free",
    "cashBalance": 25,
    "creditBalance": 0,
    "reservedAmount": 0,
    "totalBalance": 25
}

Obtenir le résumé d'utilisation

GET /api/billing/usage-summary

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

Obtenir les transactions

GET /api/billing/transactions

Renvoie l'historique des transactions (le plus récent en premier).

Paramètres de requête :

Créer une session de paiement

POST /api/billing/checkout-session

Corps :

{
    "amount": 25,
    "owner": "team-username"
}

Crée une session de paiement pour l'achat de crédits.

Créer un paiement d'abonnement

POST /api/billing/subscription-checkout

Crée une session de paiement pour la mise à niveau vers l'abonnement Pro.

Corps :

{
    "planId": "pro",
    "billingCycle": "monthly",
    "owner": "team-username"
}

Annuler ou reprendre l'abonnement

DELETE /api/billing/subscription-checkout

Annule par défaut un abonnement Pro à la fin de la période. Envoie {"resume": true} pour reprendre une annulation déjà programmée avant la fin de la période de facturation.

Corps :

{
    "resume": true
}

Recharge automatique

Ajoute automatiquement des crédits lorsque le solde tombe en dessous d'un seuil.

Obtenir la configuration du rechargement automatique

GET /api/billing/auto-topup

Paramètres de requête :

Mettre à jour la configuration du rechargement automatique

PATCH /api/billing/auto-topup

Corps :

{
    "enabled": true,
    "thresholdCents": 500,
    "amountCents": 2500
}

Méthodes de paiement

Lister les méthodes de paiement

GET /api/billing/payment-methods

Créer une intention de configuration

POST /api/billing/payment-methods/setup

Renvoie un secret client pour ajouter une nouvelle méthode de paiement.

Définir la méthode de paiement par défaut

POST /api/billing/payment-methods/default

Corps :

{
    "paymentMethodId": "pm_123"
}

Mettre à jour les informations de facturation

PATCH /api/billing/payment-methods

Corps :

{
    "name": "Jane Doe",
    "address": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
    }
}

Supprimer une méthode de paiement

DELETE /api/billing/payment-methods/{id}

API de stockage

Vérifie le détail de ton utilisation du stockage par catégorie (jeux de données, modèles, exportations) et vois tes éléments les plus volumineux.

Obtenir les informations de stockage

GET /api/storage

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"
            }
        ]
    }
}

API de téléchargement

Télécharge des fichiers directement vers le stockage cloud en utilisant des URL signées pour des transferts rapides et fiables. Utilise un flux en deux étapes : obtenir une URL signée, puis télécharger le fichier. 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 gros fichiers.

Corps :

{
    "assetType": "images",
    "assetId": "abc123",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "totalBytes": 5242880
}

Réponse :

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "objectPath": "images/abc123/my-image.jpg",
    "downloadUrl": "https://cdn.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é afin qu'elle puisse commencer le traitement.

Corps :

{
    "datasetId": "abc123",
    "objectPath": "datasets/abc123/images/my-image.jpg",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "size": 5242880
}

API des clés API

Gère tes clés API pour un accès par programme. Consulte la documentation des clés API.

Lister les clés API

GET /api/api-keys

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 membres

Crée des espaces de travail d'équipe, invite des membres et gère les rôles pour la collaboration. Consulte la documentation des é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

Invitations

Accepter l'invitation

POST /api/invites/accept

Obtenir les informations de l'invitation

GET /api/invites/info

Paramètres de requête :

Révoquer l'invitation

DELETE /api/invites/{inviteId}

Renvoyer l'invitation

POST /api/invites/{inviteId}/resend

API d'exploration

Recherche et consultation des jeux de données et projets publics partagés par la communauté. Consulte la documentation d'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 d'exploration.

API utilisateur et paramètres

Gère ton profil, tes clés API, ton utilisation du stockage et tes paramètres de confidentialité des données. Consulte la documentation des paramètres.

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é d'un 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 affiché, biographie, liens sociaux, etc.).

Icône de profil

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

Télécharger ou supprimer l'avatar du profil.

Intégration

POST /api/onboarding

Terminer le processus d'intégration (définir la région des données, le nom d'utilisateur).

API RGPD

Demande une exportation de toutes tes données ou supprime définitivement ton compte. Consulte la documentation des paramètres.

Obtenir le statut d'une tâche RGPD

GET /api/gdpr

Paramètres de requête :

Renvoie le statut de la tâche. Pour les tâches d'exportation terminées, la réponse inclut une downloadUrl.

Démarrer le flux d'exportation ou de suppression

POST /api/gdpr

Corps :

{
    "action": "export"
}

{
    "action": "delete",
    "confirmationWord": "DELETE"
}

Optionnel pour les espaces de travail d'équipe :

{
    "action": "delete",
    "confirmationWord": "DELETE",
    "teamUsername": "my-team"
}

Codes d'erreur

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 le streaming de métriques en temps réel.

Installation et configuration

pip install ultralytics

Vérifie l'installation :

yolo check

Authentification

yolo settings api_key=YOUR_API_KEY

Utilisation des jeux de données de la plateforme

Référence les datasets avec des 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 de l'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
• Sortie console
• Métriques système

Exemples d'API

Charger 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écuter l'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

Exporter le modèle :

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

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

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

Validation :

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

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

Webhooks

La plateforme utilise des webhooks internes pour diffuser les métriques d'entraînement en temps réel depuis le SDK Python ultralytics (s'exécutant sur des GPU cloud ou des machines distantes/locales) vers la plateforme — perte par époque, mAP, statistiques système et statut d'achèvement. Ces webhooks sont authentifiés via le webhookSecret HMAC fourni pour chaque travail d'entraînement et ne sont pas destinés à être consommés par des applications utilisateur.

FAQ

Comment paginer les grands résultats ?

La plupart des endpoints utilisent un paramètre limit pour contrôler combien de résultats sont renvoyés par requête :

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

Les endpoints Activité et Corbeille prennent également en charge un paramètre page pour une 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 de recherche Explore 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 ?

Oui, toutes les fonctionnalités sont disponibles via REST. Le SDK Python est un wrapper pratique qui ajoute des fonctionnalités comme le streaming de métriques en temps réel et les téléchargements automatiques de modèles. Tu peux également explorer tous les endpoints de manière interactive sur platform.ultralytics.com/api/docs.

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

Actuellement, utilise le package Python Ultralytics ou effectue des requêtes HTTP directes. Des bibliothèques clientes officielles pour d'autres langages sont prévues.

Comment gérer les limites de débit (rate limits) ?

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 Exception("Rate limit exceeded")

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

Les ID de ressources sont renvoyés lorsque tu crées des ressources via l'API. Tu peux aussi les trouver dans l'URL de la plateforme :

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

Utilise les endpoints de liste pour rechercher par nom ou filtrer par projet.