Référence de l'API REST

La plateforme Ultralytics 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

Présentation 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 ensembles de données, les projets, les modèles, l'entraînement, les exportations et les prédictions utilisent l'authentification par clé API. Les points de terminaison publics (qui répertorient les ensembles de données, les projets et les modèles publics) prennent en charge l'accès en lecture anonyme sans clé. Les routes liées au compte — notamment 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 accessibles via une clé API.

Obtenir la clé API

1. Aller à Settings > API Keys
2. Cliquer Create Key
3. Copiez la clé générée

Consultez les Clés API pour des instructions détaillées.

En-tête d'autorisation

Incluez votre 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

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers=headers,
)
data = response.json()

const response = await fetch("https://platform.ultralytics.com/api/datasets", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const data = await response.json();

URL de base

Tous les points d'accès API utilisent :

https://platform.ultralytics.com/api

Limites de débit

L'API applique des limites de débit par clé API (sur une fenêtre glissante, avec Upstash Redis en arrière-plan) afin de prévenir les abus tout en laissant l'utilisation légitime sans restriction. Le trafic anonyme bénéficie en outre de la protection offerte par les contrôles anti-abus de la plateforme Vercel.

Lorsqu'elle est limitée, l'API renvoie 429 avec les 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 afin d'éviter les abus, tandis que les opérations CRUD standard bénéficient d'une limite 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 votre allocation par défaut de 100 requêtes/min.

Points de terminaison dédiés (Illimités)

Points de terminaison dédiés sont non soumis aux limites de débit des clés API. Lorsque vous déployez un modèle sur un point de terminaison dédié, les requêtes vers l'URL de ce point de terminaison (par exemple, https://predict-abc123.run.app/predict) sont acheminés directement vers votre service dédié, sans aucune limitation de débit imposée par la plateforme. Comme vous payez pour la puissance de calcul, vous bénéficiez du débit correspondant à la configuration de votre service dédié, et non des limites imposées par l'API partagée.

Format de réponse

Réponses positives

Les réponses renvoient un JSON avec des champs spécifiques à la ressource :

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

Réponses d'erreur

{
    "error": "Dataset not found"
}

API des jeux de données

Créer, parcourir et gérer des jeux de données d'images étiquetées pour l'entraînement des modèles YOLO. Consulter la documentation des jeux de données.

Lister les ensembles 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"

import requests

resp = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 10},
)
for ds in resp.json()["datasets"]:
    print(f"{ds['name']}: {ds['imageCount']} images")

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

GET /api/datasets/{datasetId}

Renvoie tous les détails de l'ensemble de données, y compris les métadonnées, les noms de classe et les nombres de divisions.

Créer un jeu de données

POST /api/datasets

Corps :

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

Mettre à jour l'ensemble de données

PATCH /api/datasets/{datasetId}

Corps (mise à jour partielle) :

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

Supprimer l'ensemble de données

DELETE /api/datasets/{datasetId}

Supprime temporairement l'ensemble de données (déplacé vers la corbeille, récupérable pendant 30 jours).

Cloner le jeu de données

POST /api/datasets/{datasetId}/clone

Crée une copie de l'ensemble de données contenant toutes les images et toutes les étiquettes. Seuls les ensembles de données publics peuvent être clonés. Nécessite une session active dans le navigateur de la plateforme — cette fonctionnalité n'est pas disponible via une clé API.

Corps (tous les champs sont facultatifs) :

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

Exporter le jeu de données

GET /api/datasets/{datasetId}/export

Renvoie une réponse JSON avec une URL de téléchargement signée pour la dernière exportation de l'ensemble de données.

Paramètres de requête :

Réponse :

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

Créer une version de jeu de données

POST /api/datasets/{datasetId}/export

Créer un nouvel instantané de version numérotée du jeu de données. Réservé au propriétaire. La version capture le nombre actuel d'images, le nombre de classes, le nombre d'annotations et la distribution des divisions, 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 description Le champ est une étiquette fournie par l'utilisateur pour la version.

Réponse :

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

Description de la version mise à jour

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 des emplacements et les statistiques dimensionnelles. 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 des modèles formés sur un ensemble de données

GET /api/datasets/{datasetId}/models

Renvoie les modèles qui ont été entraînés à l'aide de cet ensemble de données.

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

POST /api/datasets/{datasetId}/predict

Exécutez YOLO sur les images de l'ensemble de données 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 du jeu de données

POST /api/datasets/ingest

Créer une tâche d'ingestion de jeu de données 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 jeu de données

Liste des images

GET /api/datasets/{datasetId}/images

Paramètres de requête :

Obtenir les URL des images signées

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

Obtenir des URL signées pour un lot de hachages d'images (à afficher dans le navigateur).

Supprimer l'image

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

Obtenir des étiquettes d'image

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

Renvoie les annotations et les noms de classe 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 d'images en masse

Déplacer des images entre les divisions (train/val/test) au sein d'un ensemble de données :

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

Supprimer les images en masse :

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

API des projets

Regroupez vos modèles dans des projets. Chaque modèle appartient à un seul projet. Consultez 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"}' \
  https://platform.ultralytics.com/api/projects

resp = requests.post(
    "https://platform.ultralytics.com/api/projects",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"name": "my-project", "slug": "my-project", "description": "Detection experiments"},
)
project_id = resp.json()["projectId"]

Mettre à jour le projet

PATCH /api/projects/{projectId}

Supprimer le projet

DELETE /api/projects/{projectId}

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

Cloner le projet

POST /api/projects/{projectId}/clone

Clone un projet public (avec tous ses modèles) dans votre espace de travail. Nécessite une session active sur le navigateur de la plateforme — cette fonctionnalité n'est pas disponible via une clé API.

Icône du projet

Télécharger une icône de projet (formulaire en plusieurs parties avec fichier image) :

POST /api/projects/{projectId}/icon

Supprimer l'icône du projet :

DELETE /api/projects/{projectId}/icon

Ces deux opérations nécessitent une session active sur le navigateur de la plateforme — elles ne sont pas disponibles via une clé API.

API des modèles

Gérer YOLO entraînés : consulter les métriques, télécharger les poids, effectuer des inférences et exporter vers d'autres formats. Consultez la documentation sur les modèles.

Lister les modèles

GET /api/models

Paramètres de requête :

Liste des modèles terminés

GET /api/models/completed

Renvoie les modèles dont la formation est terminée (à utiliser dans les sélecteurs de modèles et le déploiement).

Obtenir le 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 du modèle

GET /api/models/{modelId}/files

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

Cloner le modèle

POST /api/models/{modelId}/clone

Clonez un modèle public dans l'un de vos projets. Une session active dans le navigateur de la plateforme est requise — cette fonctionnalité n'est pas 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

Suivre les statistiques de téléchargement des modèles.

Exécuter l'inférence

POST /api/models/{modelId}/predict

Formulaire multipartie :

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

with open("image.jpg", "rb") as f:
    resp = requests.post(
        f"https://platform.ultralytics.com/api/models/{model_id}/predict",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": f},
        data={"conf": 0.5},
    )
results = resp.json()["images"][0]["results"]

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 Predict

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

Modèle d'échauffement

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

API d'entraînement

Lancez YOLO sur des GPU cloud (23 GPU , de la RTX 2000 Ada à la B200) et suivez la progression en temps réel. Consultez la documentation sur l'entraînement dans le 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

resp = requests.post(
    "https://platform.ultralytics.com/api/training/start",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "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,
        },
    },
)

Obtenir le statut d'entraînement

GET /api/models/{modelId}/training

Renvoie l'état actuel de la tâche 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 active dans le navigateur de la plateforme (cette route n'accepte pas l'authentification par clé API).

Annuler l'entraînement

DELETE /api/models/{modelId}/training

Arrête l'instance de calcul en cours d'exécution et marque le travail comme annulé. Nécessite une session active dans le navigateur de la plateforme — cette opération n'est pas disponible via une clé API.

API des déploiements

Déployez des modèles sur des points de terminaison d'inférence dédiés, avec des contrôles d'intégrité et une surveillance. Les nouveaux déploiements utilisent par défaut la fonctionnalité « scale-to-zero », et l'API accepte un paramètre facultatif resources objet. Voir Documentation sur les 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 le déploiement

GET /api/deployments/{deploymentId}

Supprimer le déploiement

DELETE /api/deployments/{deploymentId}

Démarrer le déploiement

POST /api/deployments/{deploymentId}/start

Reprendre un déploiement interrompu.

Arrêter le déploiement

POST /api/deployments/{deploymentId}/stop

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

Vérification de l'état

GET /api/deployments/{deploymentId}/health

Renvoie l'état de santé du point de terminaison de déploiement.

Exécuter l'inférence lors du déploiement

POST /api/deployments/{deploymentId}/predict

Envoyez une image directement à un point de terminaison de déploiement pour l'inférence. Fonctionnellement équivalent à la prédiction du modèle, mais acheminé via le point de terminaison dédié pour une latence réduite.

Formulaire multipartie :

Obtenir les métriques

GET /api/deployments/{deploymentId}/metrics

Renvoie les métriques relatives au nombre de demandes, à la latence et au 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 des mesures 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

Convertir les modèles vers des formats optimisés tels que ONNX, TensorRT, CoreML et TFLite pour le déploiement en périphérie. Consulter 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

resp = requests.post(
    "https://platform.ultralytics.com/api/exports",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"modelId": "MODEL_ID", "format": "onnx"},
)
export_id = resp.json()["exportId"]

Formats pris en charge :

Obtenir le statut d'exportation

GET /api/exports/{exportId}

Annuler l'exportation

DELETE /api/exports/{exportId}

Suivre l'exportation Télécharger

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

API d'activité

Consultez le flux des actions récentes sur votre compte : séances d'entraînement, fichiers téléchargés, etc. Consultez 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 transmettre des identifiants spécifiques :

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

Archiver les événements

POST /api/activity/archive

Corps :

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

Ou transmettre des identifiants spécifiques :

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

API Corbeille

Afficher et restaurer les éléments supprimés. Les éléments sont définitivement supprimés au bout de 30 jours. Consultez la documentation relative à 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 de la corbeille.

API Facturation

Vérifiez votre solde de crédits, achetez des crédits, consultez l'historique des transactions et configurez le rechargement automatique. Consultez 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

Retourne 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).

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 de l'abonnement Pro.

Corps :

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

Résilier ou réactiver l'abonnement

DELETE /api/billing/subscription-checkout

Annule par défaut l'abonnement Pro à la fin de la période. Envoyer {"resume": true} pour annuler une réservation déjà programmée avant la fin de la période de facturation.

Corps :

{
    "resume": true
}

Recharge automatique

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

Obtenir la configuration de la recharge automatique

GET /api/billing/auto-topup

Paramètres de requête :

Mettre à jour la configuration de la recharge automatique

PATCH /api/billing/auto-topup

Corps :

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

Méthodes de paiement

Liste des modes 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 un nouveau mode de paiement.

Définir le mode 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 le mode de paiement

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

API Stockage

Vérifiez la répartition de votre utilisation du stockage par catégorie (jeux de données, modèles, exportations) et visualisez vos é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échargez des fichiers directement vers un espace de stockage dans le cloud à l'aide d'URL signées pour des transferts rapides et fiables. La procédure se déroule en deux étapes : obtenez une URL signée, puis téléchargez le fichier. Consultez la documentation relative aux données.

Obtenir l'URL de téléchargement signée

POST /api/upload/signed-url

Demandez 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": "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"
}

Téléchargement terminé

POST /api/upload/complete

Informez la plateforme que le téléchargement d'un 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 Clés API

Gérez vos clés API pour l'accès programmatique. Consultez la documentation sur les 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 Équipes et membres

Créer des espaces de travail d'équipe, inviter des membres et gérer les rôles pour la collaboration. Consulter la documentation des équipes.

Liste des équipes

GET /api/teams

Créer une équipe

POST /api/teams/create

Corps :

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

Liste des 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 des membres

PATCH /api/members/{userId}

Supprimer le membre

DELETE /api/members/{userId}

Transfert de propriété

POST /api/members/transfer-ownership

Invitations

Accepter l'invitation

POST /api/invites/accept

Obtenir les informations relatives à l'invitation

GET /api/invites/info

Paramètres de requête :

Annuler l'invitation

DELETE /api/invites/{inviteId}

Renvoyer l'invitation

POST /api/invites/{inviteId}/resend

Explorer l'API

Recherchez et parcourez les ensembles de données publics et les projets partagés par la communauté. Consultez la documentation « Explorer ».

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 Explorer.

API utilisateur et paramètres

Gérez votre profil, vos clés API, votre utilisation du stockage et vos paramètres de confidentialité des données. Consultez la documentation relative aux 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é 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, biographie, liens vers les réseaux 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

Compléter le parcours d'intégration (définir la région des données, le nom d'utilisateur).

API RGPD

Demandez une exportation de toutes vos données ou supprimez définitivement votre compte. Consultez la documentation relative aux paramètres.

Obtenir le statut d'emploi 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 un downloadUrl.

Lancer l'exportation ou supprimer le flux

POST /api/gdpr

Corps :

{
    "action": "export"
}

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

Facultatif pour les espaces de travail d'équipe :

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

Codes d'erreur

Python

Pour faciliter l'intégration, utilisez lePython Ultralytics qui gère automatiquement l'authentification, les téléchargements et la diffusion en temps réel des métriques.

Installation et configuration

pip install ultralytics

Vérifier l'installation :

yolo check

Authentification

yolo settings api_key=YOUR_API_KEY

export ULTRALYTICS_API_KEY=YOUR_API_KEY

from ultralytics import settings

settings.api_key = "YOUR_API_KEY"

Utilisation des jeux de données de la plateforme

Ensembles de données de référence avec ul:// URI :

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 URI :

Poussée vers la plateforme

Envoyer les résultats à un projet Platform :

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 se synchronise :

• Indicateurs de formation (en temps réel)
• Poids des modèles finaux
• Graphiques de validation
• Sortie de la console
• Mesures du système

Exemples d'API

Charger un modèle depuis Platform :

# 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

Modèle d'exportation :

# 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 transmettre en continu les indicateurs de formation en temps réel depuis le ultralytics Python (exécuté sur des GPU dans le cloud ou sur des machines distantes/locales) renvoie à la plateforme les données suivantes : perte par époque, mAP, statistiques système et état d'avancement. Ces webhooks sont authentifiés via HMAC webhookSecret sont allouées par tâche de formation et ne sont pas destinées à être utilisées par les applications utilisateur.

FAQ

Comment paginer de grands ensembles de résultats ?

La plupart des terminaux utilisent un limit paramètre permettant de 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 Activity et Trash prennent également en charge un page paramètre 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"

Le point de terminaison 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 ?

Oui, toutes les fonctionnalités sont accessibles via REST. Le Python est une interface pratique qui ajoute des fonctionnalités telles que la diffusion de métriques en temps réel et le téléchargement automatique de modèles. Vous pouvez également explorer tous les points de terminaison de manière interactive sur platform.ultralytics.com/api/docs.

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

Actuellement, utilisez le package python Ultralytics ou effectuez 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 ?

Utilisez la Retry-After En-tête de la réponse 429 pour attendre le temps nécessaire :

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 ensemble de données ?

Les identifiants de ressources sont renvoyés lorsque vous créez des ressources via l'API. Vous pouvez également les trouver dans l'URL de la plateforme :

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

Utilisez les points de terminaison de la liste pour effectuer une recherche par nom ou filtrer par projet.

📅 Créé il y a 3 mois ✏️ Mis à jour il y a 5 jours

Commentaires