Référence de l’API REST#

Ultralytics Platform fournit une API REST pour accéder par programmation aux jeux de données, images, projets, modèles, entraînements, exportations et déploiements.

# List the datasets owned by a workspace
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/datasets/YOUR_USERNAME

Vue d’ensemble de l’API#

L’API est organisée autour des ressources principales de Platform :

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

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

Authentification#

La plupart des endpoints nécessitent une clé API. Les endpoints qui exposent du contenu public — lecture d’un jeu de données, d’un projet ou d’un modèle public, liste des images d’un jeu de données public, exécution d’une inférence sur un modèle public ou recherche dans Explorer — acceptent également les requêtes anonymes et renvoient simplement davantage de résultats lorsqu’une clé est fournie.

Obtenir une clé API#

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

Consulte Clés API pour obtenir des instructions détaillées.

En-tête d’autorisation#

Inclue ta clé API en tant que jeton bearer :

Authorization: Bearer YOUR_API_KEY

Exemple#

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

URL de base#

Tous les endpoints de l’API utilisent :

https://platform.ultralytics.com/api

Chemins des ressources#

Les ressources sont désignées par les mêmes noms lisibles utilisés dans les URL de Platform, et non par des identifiants de base de données :

• {owner} est un nom d’utilisateur personnel ou un identifiant d’espace de travail d’équipe : 4 à 32 caractères, alphanumériques minuscules, avec des traits d’union simples entre les segments.
• {dataset}, {project}, {model} et {deployment} suivent le même modèle en minuscules séparées par des traits d’union, sur 128 caractères maximum.
• {imageId} et {exportId} sont des identifiants hexadécimaux de 24 caractères renvoyés par l’API.
• Renommer une ressource via PATCH modifie simultanément le nom d’affichage name et le nom dans l’URL, et la réponse renvoie le nom actuel dans l’URL afin que tu puisses continuer à l’utiliser.

Limites de débit#

L’API applique des limites par clé API sur une fenêtre glissante. Chaque route appartient à une catégorie, et chaque catégorie possède son propre compteur : 20 requêtes de prédiction ne consomment donc pas ton quota par défaut.

Les routes de Platform réservées au navigateur, comme le paiement de la facturation et la gestion d’équipe, ont leurs propres limites, qui ne s’appliquent pas au trafic utilisant une clé API.

En cas de limitation, l’API renvoie 429 avec des en-têtes et un corps JSON :

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

{
    "error": "Rate limit exceeded",
    "retryAfter": 12,
    "resetAt": "2026-02-21T12:34:56.000Z"
}

Endpoints dédiés (illimités)#

Les endpoints dédiés ne sont pas soumis aux limites de débit des clés API de Platform lorsque tu appelles directement le serviceUrl propre au déploiement (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 réussies#

Les réponses sont des objets JSON contenant des champs propres à chaque ressource. Il n’existe pas d’enveloppe générique : les endpoints de liste renvoient une collection nommée accompagnée de compteurs, et les mutations renvoient les identifiants modifiés.

{
    "datasets": [{ "id": "65f1c0a2b3d4e5f601234567", "owner": "acme-vision", "dataset": "warehouse" }],
    "total": 1,
    "region": "us"
}

Les réponses contenant des données incluent également region (us, eu ou ap), la région de stockage de cet espace de travail.

Réponses d’erreur#

Chaque réponse d’erreur est un objet JSON contenant un message error :

{
    "error": "Dataset not found"
}

Pagination#

Le style de pagination dépend de la collection :

API des jeux de données#

Crée, parcoure 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 jeux de données#

GET /api/datasets/{owner}

SDK Python : client.datasets.list(owner)

Renvoie les jeux de données publics du propriétaire, ainsi que les jeux de données privés lorsque ta clé peut accéder à cet espace de travail.

Paramètres de requête :

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

Réponse :

{
    "datasets": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "owner": "acme-vision",
            "dataset": "warehouse",
            "name": "Warehouse",
            "task": "detect",
            "visibility": "private",
            "imageCount": 1000,
            "classCount": 2,
            "classNames": ["person", "forklift"],
            "splits": { "train": 800, "val": 200, "test": 0, "labeled": 1000 },
            "annotationCount": 5400,
            "starCount": 3,
            "isStarred": false,
            "status": "ready",
            "createdAt": "2026-01-15T10:00:00Z",
            "updatedAt": "2026-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

Obtenir un jeu de données#

GET /api/datasets/{owner}/{dataset}

SDK Python : client.datasets.retrieve(owner, dataset)

Renvoie l'objet complet du jeu de données sous une clé dataset, y compris classNames, splits, versions, source et l'objet metadata défini par l'utilisateur.

Créer un jeu de données#

POST /api/datasets

SDK Python : client.datasets.create(dataset=..., name=...)

Corps :

{
    "dataset": "warehouse",
    "name": "Warehouse",
    "task": "detect",
    "description": "Forklift and pedestrian safety dataset",
    "classNames": ["person", "forklift"],
    "visibility": "private",
    "metadata": { "location": "factory-1", "reviewed": true },
    "owner": "acme-vision"
}

La réponse renvoie l'identifiant dataset qui a réellement été créé, lis-le donc avant de l'importer, sauf si tu définis requireExactSlug.

Réponse (201) :

{
    "id": "65f1c0a2b3d4e5f601234567",
    "owner": "acme-vision",
    "dataset": "warehouse",
    "region": "us"
}

Mettre à jour un jeu de données#

PATCH /api/datasets/{owner}/{dataset}

SDK Python : client.datasets.update(owner, dataset)

Corps (mise à jour partielle) :

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

Champs acceptés : name, description, visibility, metadata, tags, classNames, classColors, format, task, license, iconColor, iconLetter et starred. Envoie un objet metadata vide ({}) pour effacer les métadonnées personnalisées. Les clés de métadonnées sont limitées à 128 caractères et l'objet sérialisé à 500 000 caractères.

Réponse :

{
    "success": true,
    "dataset": "warehouse-safety"
}

Le renommage modifie le nom dans l'URL ; utilise donc la valeur dataset renvoyée pour les requêtes suivantes.

Supprimer le jeu de données#

DELETE /api/datasets/{owner}/{dataset}

SDK Python : client.datasets.delete(owner, dataset)

Déplace le jeu de données vers la corbeille, où tu peux le récupérer pendant 30 jours.

Cloner le jeu de données#

POST /api/datasets/{owner}/{dataset}/clone

SDK Python : client.datasets.clone(owner, dataset)

Copie un jeu de données accessible, avec ses images et ses annotations, dans ton espace de travail personnel ou dans un espace de travail d'équipe.

Corps facultatif (tous les champs sont facultatifs) :

{
    "dataset": "warehouse-copy",
    "name": "Warehouse Copy",
    "description": "Cloned for experimentation",
    "visibility": "private",
    "license": "CC-BY-4.0",
    "owner": "acme-vision"
}

Réponse (201) : id, owner, dataset, name, imageCount, classCount et region. Les jeux de données associés à une source de stockage connectée renvoient 409, car leurs fichiers ne sont pas copiés.

Télécharger un export de jeu de données#

GET /api/datasets/{owner}/{dataset}/export

SDK Python : client.datasets.export(owner, dataset)

Renvoie une URL de téléchargement NDJSON signée. Omet v pour exporter l'état actuel du jeu de données et réutiliser l'export mis en cache lorsqu' aucune modification n'a été effectuée depuis sa génération.

Paramètres de requête :

Réponse :

{
    "downloadUrl": "https://storage.googleapis.com/...&signature=...",
    "cached": true
}

La demande d'une version spécifique renvoie downloadUrl et version au lieu de cached.

Créer une version de jeu de données#

POST /api/datasets/{owner}/{dataset}/export

SDK Python : client.datasets.create_export(owner, dataset)

Crée un instantané numéroté et immuable du jeu de données et enregistre son export NDJSON. Un accès éditeur est requis.

Corps (facultatif) :

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

Réponse :

{
    "version": 3,
    "downloadUrl": "https://storage.googleapis.com/...&signature=...",
    "reused": false
}

reused vaut true lorsque le jeu de données n'a pas changé depuis la version précédente et que cet instantané est renvoyé à la place.

Mettre à jour la description de la version#

PATCH /api/datasets/{owner}/{dataset}/export

SDK Python : client.datasets.update_export(owner, dataset, version=..., description=...)

Corps :

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

Réponse : {"ok": true}

Restaurer une version du jeu de données#

POST /api/datasets/{owner}/{dataset}/restore

SDK Python : client.datasets.restore(owner, dataset, version=...)

Reconstruit les images, les annotations et les classes à partir d'une version enregistrée sans copier les octets des images.

Corps :

{
    "version": 2
}

Réponse : {"version": 2, "imageCount": 1000}

Obtenir les statistiques du jeu de données#

GET /api/datasets/{owner}/{dataset}/class-stats

SDK Python : client.datasets.class_stats(owner, dataset)

Renvoie les décomptes d'annotations par classe, les histogrammes d'images et d'annotations ainsi que les cartes thermiques. Les jeux de données volumineux sont échantillonnés, auquel cas sampleSize indique combien d'images ont contribué.

Réponse (abrégée) :

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120, "size": 1 }],
        "heightHistogram": [{ "bin": 480, "count": 95, "size": 1 }],
        "pointsHistogram": [{ "bin": 4, "count": 200, "size": 1 }],
        "formatDistribution": { "jpg": 900, "png": 100 },
        "fileSizeHistogram": [{ "bin": 250000, "count": 300, "size": 50000 }],
        "objectsPerImageHistogram": [{ "bin": 5, "count": 210, "size": 1 }],
        "bboxWidthHistogram": [{ "bin": 120, "count": 340, "size": 20 }],
        "bboxHeightHistogram": [{ "bin": 90, "count": 300, "size": 20 }]
    },
    "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", "forklift"],
    "cached": true,
    "sampleSize": null
}

Gérer les classes#

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

POST /api/datasets/{owner}/{dataset}/classes/merge

SDK Python : client.datasets.merge_classes(owner, dataset, source_class_ids=..., target_class_id=...)

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

Supprimer des classes (leurs annotations sont supprimées et les identifiants des classes restantes sont décalés vers le bas) :

POST /api/datasets/{owner}/{dataset}/classes/delete

SDK Python : client.datasets.delete_classes(owner, dataset, class_ids=...)

{
    "classIds": [2, 4]
}

Les deux opérations renvoient success, les valeurs mises à jour classNames et classColors, ainsi qu'un résumé des modifications (mergedClassIds et targetClassId, ou deletedClassIds et deletedAnnotations).

Redistribuer les partitions#

POST /api/datasets/{owner}/{dataset}/splits/redistribute

SDK Python : client.datasets.redistribute_splits(owner, dataset, train=..., val=..., test=...)

Réattribue aléatoirement les images entre les partitions. Les trois pourcentages doivent totaliser 100.

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

Réponse : success, les décomptes splits obtenus et modified (nombre d'images déplacées).

Plongements du jeu de données#

GET /api/datasets/{owner}/{dataset}/embeddings
POST /api/datasets/{owner}/{dataset}/embeddings
DELETE /api/datasets/{owner}/{dataset}/embeddings

SDK Python : client.datasets.embeddings(owner, dataset), client.datasets.create_embeddings(owner, dataset), client.datasets.delete_embeddings(owner, dataset)

GET renvoie le résumé de l'analyse (analyzedAt, embeddingsCount, latestImageAt, activeJob). POST met en file d'attente une analyse des plongements et renvoie 202 avec un jobId. DELETE annule la tâche active et renvoie l'ID de la tâche annulée ou null.

Regroupement d'images#

GET /api/datasets/{owner}/{dataset}/images/clustering

SDK Python : client.datasets.clustering(owner, dataset)

Renvoie la disposition 2D UMAP d'une analyse terminée, avec pagination via offset et limit (valeur par défaut et maximum de 50 000). Chaque entrée contient id, umapX, umapY, split, classIds, width, height, bytes, labelCount et missing.

Lister les modèles entraînés sur un jeu de données#

GET /api/datasets/{owner}/{dataset}/models

SDK Python : client.datasets.models(owner, dataset)

Réponse :

{
    "models": [
        {
            "id": "65f1c0a2b3d4e5f601234599",
            "owner": "acme-vision",
            "project": "inspection",
            "model": "v3",
            "name": "v3",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "metrics": { "mAP50": 0.85, "mAP50-95": 0.72, "precision": 0.88, "recall": 0.81 },
            "startedAt": "2026-01-14T22:00:00Z",
            "completedAt": "2026-01-15T10:00:00Z",
            "createdAt": "2026-01-14T21:55:00Z"
        }
    ],
    "count": 1
}

Lister les images d'un jeu de données#

GET /api/datasets/{owner}/{dataset}/images

SDK Python : client.datasets.images(owner, dataset)

Paramètres de requête :

Réponse :

{
    "images": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "hash": "9f2c1d4b6a8e0f3c5d7b9a1e2f4c6d8b",
            "ext": "jpg",
            "name": "aisle-04.jpg",
            "thumbnailUrl": "https://storage.googleapis.com/...&signature=...",
            "width": 1920,
            "height": 1080,
            "split": "train",
            "labelCount": 6,
            "bytes": 284213,
            "error": null
        }
    ],
    "total": 1000,
    "hasMore": true,
    "classes": ["person", "forklift"],
    "errorCount": 0,
    "nextCursor": "65f1c0a2b3d4e5f601234567"
}

Obtenir les images sélectionnées#

POST /api/datasets/{owner}/{dataset}/images

SDK Python : client.datasets.selected_images(owner, dataset, image_ids=...)

Renvoie la même structure d’image pour jusqu’à 1 000 ID d’image fournis et accepte les mêmes paramètres de filtre et de requête d’URL que l’opération de liste.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}

Ingérer les données du jeu de données#

POST /api/datasets/{owner}/{dataset}/ingest

SDK Python : client.datasets.ingest(owner, dataset, body=...)

Traite un téléversement terminé, une archive distante ou une source de stockage connectée pour l’intégrer à un jeu de données existant. Fournis exactement une source :

Les sessions de téléversement sont liées à un jeu de données par le assetId transmis à POST /api/upload/signed-url, et l’ingestion rejette une session appartenant à un autre jeu de données.

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

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

Corps (archive distante ou NDJSON) :

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

Corps (importation d’étiquettes lors d’une ingestion ultérieure) :

{
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "forklift", "background": null }
}

Corps (ajout de métadonnées par image) :

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

Les clés de métadonnées doivent correspondre au chemin normalisé à l’intérieur de l’archive, y compris les dossiers. Pour les importations NDJSON, chaque enregistrement peut contenir son propre objet metadata, qui prend le dessus sur une entrée imageMetadata correspondante. Les chemins d’archive sont limités à 1 024 caractères, les clés de métadonnées de premier niveau à 128 caractères, et chaque objet de métadonnées — ainsi que l’ensemble de la map imageMetadata — à 500 000 caractères sérialisés.

Réponse (201) :

{
    "jobId": "65f1c0a2b3d4e5f6012345aa",
    "status": "queued"
}

graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[PUT archive to signed URL]:::proc
    C --> D[POST /api/upload/complete]:::proc
    D --> E["POST /api/datasets/{owner}/{dataset}/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

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
owner, dataset = "acme-vision", "warehouse"
dataset_id = "65f1c0a2b3d4e5f601234567"  # id returned by POST /api/datasets
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/{owner}/{dataset}/ingest",
    headers=headers,
    json={
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

API Images#

Inspecte, annote, déplace et supprime les images d’un jeu de données à l’aide de leur ID d’image de 24 caractères. Consulte la documentation sur les annotations.

Obtenir une image#

GET /api/images/{imageId}

SDK Python : client.images.retrieve(image_id)

Renvoie l’objet metadata (personnalisé, défini par l’utilisateur), properties (nom de fichier, hachage, dimensions, sous-ensemble, compteurs, horodatages), labels et le classNames du jeu de données.

Mettre à jour une image#

PATCH /api/images/{imageId}

SDK Python : client.images.update(image_id, body=...)

Remplace soit les annotations, soit les métadonnées personnalisées — envoie l’une des deux structures, pas les deux.

Corps (annotations) :

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

Corps (métadonnées) :

{
    "metadata": { "location": "strasbourg", "reviewed": true }
}

Supprimer une image#

DELETE /api/images/{imageId}

SDK Python : client.images.delete(image_id)

Supprime définitivement une image et ses annotations.

Annoter automatiquement une image#

POST /api/images/{imageId}/predict

SDK Python : client.images.predict(image_id, model_id=...)

Exécute l’inférence YOLO sur l’image et renvoie les annotations prédites. Elles ne sont pas enregistrées — réécris les résultats avec PATCH /api/images/{imageId} lorsque tu en es satisfait.

Réponse : success, predictions (objets d’annotation), modelUsed et inferenceTime. Un modèle dont les classes ne correspondent pas à celles du jeu de données renvoie 422.

Annotation automatique d'un jeu de données#

POST /api/datasets/{owner}/{dataset}/predict/batch

SDK Python : client.datasets.create_batch(owner, dataset, model_id=...)

Sauvegarde une version de jeu de données, puis met en file d'attente une exécution qui étiquette les images non étiquetées du jeu de données avec le modèle et retourne 202. Le corps prend les mêmes champs modelId, confidence et iou que le point de terminaison d'image unique, plus includeAnnotated (par défaut false) pour étiqueter également les images qui ont déjà des étiquettes et un tableau facultatif classMapping indiquant l' indice de classe du jeu de données pour chaque classe de modèle, ou null pour l'ignorer. Les étiquettes existantes ne sont jamais modifiées, et l'exécution est facturée pour les images qu'elle traite réellement. 402 signifie que le solde ne peut pas couvrir l'estimation, 409 que le jeu de données n'est pas prêt, n'a plus d'images à étiqueter ou a déjà une exécution en cours, et 422 que le jeu de données n'a pas de classes : crée-les avec le point de terminaison des classes avant d'appeler ce point de terminaison, ce que fait l'étape Map classes de l'application avant de démarrer une exécution.

GET sur le même chemin (client.datasets.batch(owner, dataset)) retourne l'exécution en cours et sa progression, ou la dernière exécution terminée jusqu'à ce qu'elle soit rejetée ; DELETE (client.datasets.delete_batch(owner, dataset)) annule une exécution en cours ou règle la facturation et rejette le résumé terminé.

Déplacer des images en masse#

PATCH /api/images/bulk

SDK Python : client.images.update_bulk(image_ids=..., split=...)

Déplace jusqu’à 1 000 images d’un jeu de données vers un autre sous-ensemble.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"],
    "split": "val",
    "conflictPolicy": "skip"
}

Les conflits de noms de fichiers ou de contenu renvoient 409 jusqu’à ce que tu choisisses une conflictPolicy commune à tout le lot parmi skip, keep_both ou replace. La réponse indique modifiedCount, skippedCount et targetSplit.

Supprimer des images en masse#

DELETE /api/images/bulk

SDK Python : client.images.delete_bulk(image_ids=...)

{
    "imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}

Supprime jusqu’à 1 000 images d’un seul jeu de données et renvoie deletedCount et deletedImageIds.

Obtenir les URL signées des images#

POST /api/images/urls

SDK Python : client.images.urls(image_ids=...)

Renvoie des URL signées temporaires pour jusqu’à 100 ID d’image d’un même jeu de données.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"]
}

Réponse : urls et thumbnails, tous deux indexés par ID d’image.

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/{owner}

SDK Python : client.projects.list(owner)

Paramètres de requête :

Obtenir un projet#

GET /api/projects/{owner}/{project}

SDK Python : client.projects.retrieve(owner, project)

Renvoie l’objet project, un tableau models de résumés par modèle (état, métriques, époques, poids, arguments d’entraînement), et isOwner.

Créer un projet#

POST /api/projects

SDK Python : client.projects.create(project=..., name=...)

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

Réponse (201) : id, owner, project, region.

Mettre à jour un projet#

PATCH /api/projects/{owner}/{project}

SDK Python : client.projects.update(owner, project)

Champs acceptés : name, description, visibility, metadata, tags, license, archived, iconColor, iconLetter, viewPreferences et starred.

{
    "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 128 caractères par clé et de 500 000 caractères pour l’objet sérialisé que les métadonnées de jeu de données.

Supprimer le projet#

DELETE /api/projects/{owner}/{project}

SDK Python : client.projects.delete(owner, project)

Déplace le projet et ses modèles vers la corbeille et renvoie cascadedModels.

Cloner un projet#

POST /api/projects/{owner}/{project}/clone

SDK Python : client.projects.clone(owner, project)

Clone un projet accessible et ses modèles terminés. Le corps facultatif accepte project, name, description, visibility, license et une destination owner.

API Modèles#

Gère les modèles YOLO entraînés : consulte les métriques, télécharge les poids, exécute l’inférence et surveille l’entraînement. Consulte la documentation sur les modèles.

Lister les modèles d’un projet#

GET /api/models/{owner}/{project}

SDK Python : client.models.list(owner, project)

Paramètres de requête :

Obtenir un modèle#

GET /api/models/{owner}/{project}/{model}

SDK Python : client.models.retrieve(owner, project, model)

Paramètres de requête :

La réponse par défaut contient l’objet model — état, tâche, métriques, trainArgs, trainResults, classNames, computeCost, metadata et plus encore — ainsi que isOwner.

Créer un modèle#

POST /api/models

SDK Python : client.models.create(body=...)

Crée un enregistrement de modèle non entraîné auquel tu peux associer des poids ou que tu peux entraîner.

Réponse (201) : id, owner, project, model, region.

Mettre à jour un modèle#

PATCH /api/models/{owner}/{project}/{model}

SDK Python : client.models.update(owner, project, model)

Les champs acceptés incluent name, description, color, metadata, status, license, datasetSlug, trainArgs, trainResults, epochs, bestEpoch, bestFitness, version, trainingError et starred. Transmettre projectId seul déplace le modèle vers un autre projet du même propriétaire ; la réponse renvoie l'slug du modèle dans la destination, renamed: true lorsque cet identifiant y était déjà pris, et 409 tant que le modèle est encore en cours d'entraînement.

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

Les metadata personnalisées sont distinctes des champs gérés par l’entraînement, tels que trainArgs, environment et trainResults, et utilisent les mêmes limites de taille que les métadonnées de jeu de données.

Supprimer un modèle#

DELETE /api/models/{owner}/{project}/{model}

SDK Python : client.models.delete(owner, project, model)

Déplace le modèle vers la corbeille pendant 30 jours.

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

GET /api/models/{owner}/{project}/{model}/files

SDK Python : client.models.files(owner, project, model)

Renvoie des URL signées à durée de validité limitée pour les poids du modèle.

{
    "files": [
        {
            "name": "best.pt",
            "size": 6534127,
            "downloadUrl": "https://storage.googleapis.com/...&signature=..."
        }
    ]
}

Cloner un modèle#

POST /api/models/{owner}/{project}/{model}/clone

SDK Python : client.models.clone(owner, project, model, project_body=...)

Copie un modèle accessible dans un projet existant.

{
    "owner": "acme-vision",
    "project": "inspection",
    "model": "v3-copy",
    "name": "V3 Copy",
    "description": "Cloned from a public model"
}

Exécuter l'inférence#

POST /api/models/{owner}/{project}/{model}/predict

SDK Python : client.models.predict(owner, project, model, body=...)

Les modèles publics peuvent être utilisés pour effectuer des prédictions sans authentification. Les modèles privés et partagés nécessitent une clé API donnant accès au projet parent.

Formulaire multipart :

Fournis file ou source. Les modèles de profondeur acceptent également bits (8, 12 ou 16) pour sélectionner la quantification PNG de la carte de profondeur. Les requêtes qui dépassent les limites d’entrée du service renvoient 413.

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

Réponse :

Chaque entrée de images contient shape, speed, results et, pour les tâches de prédiction dense, un contenu PNG semantic_mask ou depth (les valeurs de profondeur sont pixel × max / divisor, avec un diviseur de 255 pour la carte 8 bits par défaut et de 65535 lorsque bits vaut 12 ou 16). L'objet metadata indique le nombre d'images, les durées d'exécution des fonctions, la tâche et les versions du service. Les chemins internes des modèles ne sont jamais renvoyés.

{
    "images": [
        {
            "shape": [1080, 1920],
            "speed": { "preprocess": 2.1, "inference": 12.4, "postprocess": 1.3 },
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1,
        "functionTimeAlive": 184.2,
        "functionTimeCall": 0.31,
        "task": "detect",
        "version": { "ultralytics": "8.4.120" }
    }
}

Vérifier la progression de l'entraînement#

GET /api/models/{owner}/{project}/{model}/training

SDK Python : client.models.training(owner, project, model)

Renvoie job, qui contient l'état, la progression des époques, les durées, les détails du calcul, les arguments d'entraînement, les métriques par époque et des détails d'erreur sécurisés, ou null lorsque le modèle n'a jamais été entraîné. Les modèles des projets publics sont consultables sans authentification.

Annuler l'entraînement#

DELETE /api/models/{owner}/{project}/{model}/training

SDK Python : client.models.delete_training(owner, project, model)

Met fin à l'instance de calcul en cours et marque la tâche comme annulée. Renvoie 409 lorsque l'entraînement n'est plus actif.

API d'entraînement#

Lance l'entraînement YOLO sur des GPU cloud et suis la progression en temps réel. Consulte la documentation sur l'entraînement cloud.

graph LR
    A[POST /api/training/start]:::start --> B[Job Created]:::proc
    B --> C{Training}:::decide
    C -->|progress| D[GET .../training]:::proc
    C -->|cancel| E[DELETE .../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

Obtenir la disponibilité des GPU#

GET /api/training/gpu-availability

SDK Python : client.training.gpu_availability()

Renvoie l'état actuel des stocks, indexé par ID de GPU. Public et sans authentification ; passe managed=true pour inclure la capacité d'entraînement gérée, qui nécessite une clé API.

Démarrer l'entraînement#

POST /api/training/start

SDK Python : client.training.start(model_id=..., train_args=...)

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

Réponse :

{
    "modelId": "65f1c0a2b3d4e5f601234599",
    "status": "starting",
    "gpuType": "rtx-4090",
    "estimatedCost": { "pricePerHour": 0.69, "gpuMemoryGb": 24 },
    "billing": {
        "estimatedCostCents": 138,
        "estimatedCostDisplay": "$1.38",
        "balanceCents": 2500
    }
}

L'entraînement renvoie 402 lorsque ton solde de crédits est insuffisant et 503 lorsqu'aucune capacité n'est disponible pour le GPU demandé.

API d'exportation#

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

Lister les exportations#

GET /api/models/{owner}/{project}/{model}/exports

SDK Python : client.exports.list(owner, project, model)

Paramètres de requête :

Créer une exportation#

POST /api/models/{owner}/{project}/{model}/exports

SDK Python : client.exports.create(owner, project, model, format=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "onnx", "args": {"imgsz": 640, "quantize": 16}}' \
  https://platform.ultralytics.com/api/models/acme-vision/inspection/v3/exports

Réponse (201) : id, format, status (queued ou running), gpuType, region. Une exportation équivalente déjà en cours renvoie 409.

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.

nms=None utilise par défaut des sorties brutes pour NMS externe. Définis nms=False pour sélectionner une tête sans NMS disponible ; les formats non pris en charge reviennent à leur chemin de sortie natif. Les entrées nms ci-dessus identifient les formats capables d'intégrer NMS avec nms=True.

Obtenir l'état d'une exportation#

GET /api/models/{owner}/{project}/{model}/exports/{exportId}

SDK Python : client.exports.retrieve(owner, project, model, export_id)

Renvoie l'objet export avec status, format, args, gpuType, les horodatages et, une fois terminée, un objet file contenant size, downloadUrl et downloadFilename.

Annuler ou supprimer une exportation#

DELETE /api/models/{owner}/{project}/{model}/exports/{exportId}

SDK Python : client.exports.delete(owner, project, model, export_id)

Annule une exportation active ou supprime une exportation terminée et son fichier. La réponse indique ce qui s'est produit :

{
    "success": true,
    "action": "cancelled"
}

API des déploiements#

Déploie les modèles sur des points de terminaison d'inférence dédiés avec vérifications d'état et supervision. Consulte la documentation sur les points de terminaison.

graph LR
    A[Create]:::start --> B[Deploying]:::proc
    B --> C[Ready]:::out
    C -->|action stop| D[Stopped]:::extern
    C -->|action replace| B
    D -->|action 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/{owner}

SDK Python : client.deployments.list(owner)

Paramètres de requête :

Les appelants anonymes doivent filtrer sur un modèle public ; lister un espace de travail entier nécessite une authentification.

Créer un déploiement#

POST /api/deployments/{owner}

SDK Python : client.deployments.create(owner, project=..., model=..., deployment=..., name=..., region=...)

Corps :

{
    "project": "inspection",
    "model": "v3",
    "deployment": "edge-1",
    "name": "Edge 1",
    "region": "us-central1"
}

Réponse (201) : id, deployment, status (creating), message et region.

Obtenir un déploiement#

GET /api/deployments/{owner}/{deployment}

SDK Python : client.deployments.retrieve(owner, deployment)

Renvoie l'objet deployment avec status, statusMessage, region, serviceUrl et resources.

Démarrer, arrêter ou remplacer un déploiement#

PATCH /api/deployments/{owner}/{deployment}

SDK Python : client.deployments.update(owner, deployment, body=...)

Un seul champ action sélectionne l'opération :

{ "action": "start" }

Le remplacement déploie une nouvelle révision tout en conservant l'ID du déploiement, la région et l'URL du point de terminaison ; la révision existante reste active si le déploiement échoue. Le modèle de remplacement doit être un modèle terminé dont les poids sont accessibles avec ta clé. Les opérations terminées renvoient 200 avec status, ready ou stopped ; les opérations encore en cours de déploiement renvoient 202 avec deploying ou stopping.

Supprimer un déploiement#

DELETE /api/deployments/{owner}/{deployment}

SDK Python : client.deployments.delete(owner, deployment)

Supprime définitivement le point de terminaison d'inférence.

Health Check#

GET /api/deployments/{owner}/{deployment}/health

SDK Python : client.deployments.health(owner, deployment)

Envoie des requêtes ping au point de terminaison et le préchauffe, en renvoyant healthy, latencyMs et le code amont status.

Exécuter une inférence sur un déploiement#

POST /api/deployments/{owner}/{deployment}/predict

SDK Python : client.deployments.predict(owner, deployment, body=...)

Achemine une image ou une vidéo via le point de terminaison dédié. Les contrats de requête et de réponse correspondent à ceux de l'inférence de modèle.

Formulaire multipart :

Obtenir les métriques#

GET /api/deployments/{owner}/{deployment}/metrics

SDK Python : client.deployments.metrics(owner, deployment)

Paramètres de requête :

La réponse complète contient summary (totaux des requêtes, taux d'erreur, latence moyenne et p50/p95/p99) et timeSeries (requêtes, erreurs, latence, CPU, mémoire, nombre d'instances). La réponse sparkline renvoie requests24h, totalRequests, errorRate et avgLatencyMs.

Obtenir les journaux#

GET /api/deployments/{owner}/{deployment}/logs

SDK Python : client.deployments.logs(owner, deployment)

Paramètres de requête :

API de la corbeille#

Consulte, restaure et supprime définitivement les projets, jeux de données et modèles supprimés de manière réversible. Les éléments sont purgés automatiquement après 30 jours. Consulte la documentation de la corbeille.

Lister la Corbeille#

GET /api/trash

SDK Python : client.lifecycle.trash()

Paramètres de requête :

La réponse inclut items (chacun avec daysRemaining), total, page, limit, totalPages et un summary avec les totaux par type.

Restaurer un élément#

POST /api/trash

SDK Python : client.lifecycle.restore(id=..., type=...)

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

La restauration d'un projet restaure également les modèles mis à la corbeille avec celui-ci, indiqués par restoredModels.

Supprimer définitivement#

DELETE /api/trash

SDK Python : client.lifecycle.delete_trash(body=...)

Supprimer un élément :

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

Ou vider toute la corbeille :

{
    "all": true
}

La réponse renvoie deletedCount, ainsi que cascadedModels et survivingDeployments le cas échéant.

API d'importation#

Téléverse des fichiers directement vers le stockage cloud à l'aide d'URL signées. La finalisation du téléversement d'un modèle associe ses poids ; la finalisation du téléversement d'une archive de jeu de données enregistre la session, que tu transmets ensuite à l'ingestion du jeu de données. Consulte la documentation sur les données.

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

POST /api/upload/signed-url

SDK Python : client.upload.signed_url(body=...)

Corps :

{
    "assetType": "datasets",
    "assetId": "65f1c0a2b3d4e5f601234567",
    "filename": "warehouse.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

Réponse :

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.googleapis.com/...&signature=...",
    "expiresAt": "2026-02-22T12:00:00Z",
    "headers": { "x-goog-if-generation-match": "0" }
}

importe le fichier avec une requête PUT vers uploadUrl, en utilisant le même Content-Type que tu as déclaré et chaque en-tête renvoyé dans headers. Les URL de téléchargement de jeux de données sont valables pendant 12 heures et servent uniquement à la création : une seconde PUT vers la même URL renvoie 412, et une PUT sans les en-têtes renvoyés renvoie 400.

Finaliser le téléversement#

POST /api/upload/complete

SDK Python : client.upload.complete(session_id=...)

{
    "sessionId": "session_abc123",
    "md5": "<optional md5 hex>"
}

Réponse : success et un objet file avec size et contentType. Pour les modèles, cela associe les poids ; pour les archives de jeux de données, appelle ensuite ingest pour commencer le traitement.

Lorsque md5 est fourni, il est comparé à l'objet stocké. Une non-correspondance renvoie 400 ; sur une session qui n'est pas encore terminée, cela supprime également le fichier importé et laisse la session incomplète, demande donc une nouvelle URL signée et importe à nouveau. Une session de jeu de données terminée peut être terminée à nouveau tant que son archive existe, mais des finalisations concurrentes avec différents résumés cryptographiques renvoient 409 ; les sessions de modèles sont supprimées à la fin. checksum est stocké en tant que métadonnées de fichier de modèle et n'est pas vérifié.

API des intégrations de stockage#

Connecte des comptes Google Cloud Storage, Amazon S3 ou Azure Blob Storage en lecture seule et parcours-les comme sources de jeux de données. Consulte la documentation sur les intégrations.

Lister les intégrations#

GET /api/integrations/buckets

SDK Python : client.storage_integrations.list()

Renvoie integrations, chacun avec id, provider, credentialIdentity, targets et createdAt. Les identifiants ne sont jamais renvoyés.

Découvrir les emplacements#

POST /api/integrations/buckets/discover

SDK Python : client.storage_integrations.discover(body=...)

Répertorie les buckets ou conteneurs accessibles en lecture avec les identifiants fournis, sans les enregistrer.

{
    "provider": "gcs",
    "credentials": {
        "client_email": "svc@project.iam.gserviceaccount.com",
        "private_key": "-----BEGIN PRIVATE KEY-----\n...",
        "project_id": "my-project"
    }
}

Réponse : {"targets": ["my-bucket", "another-bucket"]}

Connecter un stockage#

POST /api/integrations/buckets

SDK Python : client.storage_integrations.create(body=...)

Mêmes formats d'identifiants que pour la découverte, avec en plus un tableau targets obligatoire contenant de 1 à 50 noms de buckets ou de conteneurs. Renvoie 201 avec l'intégration enregistrée. Les identifiants S3 temporaires (ASIA clés d'accès) sont rejetés.

Parcourir les objets#

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

SDK Python : client.storage_integrations.objects(id, target=...)

Paramètres de requête :

Renvoie entries (chaque kind est folder ou file) et un cursor facultatif pour la page suivante.

Déconnecter le stockage#

DELETE /api/integrations/buckets/{id}

SDK Python : client.storage_integrations.delete(id)

Supprime les identifiants enregistrés sans supprimer les données du fournisseur. Les jeux de données connectés restent visibles, mais leurs fichiers restent inaccessibles jusqu'à la reconnexion du même compte de stockage. Nécessite un accès administrateur à l'espace de travail.

API d'importation de jeux de données#

Importe des jeux de données depuis des services tiers. Consulte l'intégration Roboflow.

Prévisualiser une importation Roboflow#

POST /api/integrations/roboflow/preview

SDK Python : client.datasets.preview_roboflow(api_key=...)

Résout une clé API Roboflow en un plan d'importation : détails de l'espace de travail, newDatasets qui seraient importés, nombres de projets ignorés, non pris en charge et non résolus, bytesTotal, ainsi que l'espace disponible de ton storage. La clé API Roboflow est lue dans le corps de la requête et n'est pas conservée.

{
    "apiKey": "ROBOFLOW_API_KEY"
}

Importer depuis Roboflow#

POST /api/integrations/roboflow/import

SDK Python : client.datasets.import_roboflow(api_key=..., items=...)

Met en file d'attente les tâches d'ingestion pour un maximum de 500 versions de projets Roboflow sélectionnées, à l'aide des éléments renvoyés par la prévisualisation.

{
    "apiKey": "ROBOFLOW_API_KEY",
    "items": [
        {
            "workspace": "my-workspace",
            "projectId": "warehouse-safety",
            "projectName": "Warehouse Safety",
            "projectType": "object-detection",
            "latestVersion": 4
        }
    ]
}

Réponse (201) : tableaux imported, failed et skipped. Les importations nécessitent un espace de stockage suffisant, et chaque jeu de données doit respecter la limite de taille par importation de ton forfait.

API du compte#

Consulte ton compte Platform, tes clés, ton stockage et tes profils publics. Consulte la documentation des paramètres.

Résumé du compte#

GET /api/account/summary

SDK Python : client.account.summary()

Renvoie le forfait, le solde de crédits et le nombre de ressources de l'espace de travail qui a émis la clé.

{
    "username": "acme-vision",
    "name": "Acme Vision",
    "accountType": "team",
    "plan": "pro",
    "creditsCents": 2500,
    "counts": { "projects": 4, "datasets": 7, "models": 21 },
    "teams": []
}

Lister les clés API#

GET /api/api-keys

SDK Python : client.account.api_keys()

Renvoie keys avec keyId, name, keyPrefix et createdAt pour l'espace de travail de la clé. Les requêtes authentifiées par clé API ne reçoivent que les métadonnées ; les valeurs complètes des clés sont affichées au propriétaire de l'espace de travail dans Paramètres > Clés API de l'interface Platform, où les clés sont également créées et révoquées.

Vérifier l'utilisation du stockage#

GET /api/storage

SDK Python : client.account.storage()

Paramètres de requête :

Réponse :

{
    "tier": "pro",
    "usage": {
        "storage": { "current": 1073741824, "limit": 107374182400, "percent": 1.0 },
        "datasets": { "current": 536870912, "limit": 107374182400, "percent": 0.5 }
    },
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "65f1c0a2b3d4e5f601234567",
                "name": "Warehouse",
                "slug": "warehouse",
                "sizeBytes": 536870912,
                "type": "dataset"
            }
        ]
    },
    "region": "us",
    "username": "acme-vision",
    "updatedAt": "2026-01-15T10:00:00Z"
}

Obtenir le profil public d'un utilisateur#

GET /api/users

SDK Python : client.account.profile(username=...)

Paramètres de requête :

Renvoie le profil public user avec followerCount et, pour les appelants authentifiés, isFollowed.

Suivre un utilisateur ou ne plus le suivre#

PATCH /api/users

SDK Python : client.account.follow(username=..., followed=...)

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

Réponse : followed et followerCount mis à jour.

API de facturation#

Consulte l'utilisation de ton forfait et ton registre de crédits. Consulte la documentation de facturation.

Afficher le forfait et l'utilisation#

GET /api/billing/usage-summary

SDK Python : client.billing.usage_summary()

Renvoie plan (ID, état, cycle de facturation, fin de période), metrics (limite et utilisation du stockage), trainingCredit, features, creditsCents et le nombre de sièges.

Afficher les transactions#

GET /api/billing/transactions

SDK Python : client.billing.transactions()

Paramètres de requête :

Chaque transaction inclut id, type (comme purchase, training, monthly_grant ou refund), amountCents, balanceAfter, createdAt, un receiptUrl facultatif et le contexte du modèle pour les frais d'entraînement. Les détails internes de facturation ne sont jamais renvoyés.

Explorer l'API#

Recherche les projets et jeux de données publics partagés par la communauté. Consulte la documentation d'Explore.

Rechercher du contenu public#

GET /api/explore/search

SDK Python : client.explore.search()

Paramètres de requête :

Réponse : projects, datasets et hasMore.

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

SDK Python#

ultralytics-platform est un client Python typé généré à partir du contrat OpenAPI, avec une méthode par endpoint (client.datasets.list, client.models.predict, client.exports.create, ...). Chaque méthode accepte les paramètres de chemin positionnellement, les autres entrées comme arguments nommés, et timeout et extra_headers facultatifs par requête.

pip install "ultralytics-platform>=0.1.45" # Python 3.11+

from ultralytics_platform import Platform

with Platform() as client:  # reads ULTRALYTICS_API_KEY or the key saved by yolo login
    dataset = client.datasets.retrieve("acme-vision", "warehouse")
    images = client.datasets.images("acme-vision", "warehouse", limit=10)
    export = client.exports.create("acme-vision", "inspection", "v3", format="onnx")

AsyncPlatform expose la même arborescence de ressources pour le code async/await, les réponses infructueuses lèvent APIError avec status_code, body et json analysé, tandis que les échecs de connexion lèvent APIConnectionError. Consulte le dépôt du SDK pour lire le README complet.

Intégration Python#

Pour les flux de travail d'entraînement et d'inférence, utilise le package Python d'Ultralytics, qui gère automatiquement l'authentification, les transferts et la diffusion en continu des métriques en temps réel. Sur Python 3.11+, pip install ultralytics installe également le SDK ultralytics-platform. Lorsque model.train(project=...) cible Platform, les rappels d'entraînement diffusent les événements via le client.training.metrics() du SDK et demandent des URL de téléchargement de points de contrôle via client.models.upload_checkpoint(), les opérations POST /api/webhooks/training/metrics et POST /api/webhooks/models/upload dans le document OpenAPI, il n'y a donc rien à appeler toi-même.

Installation et configuration#

L'intégration de la plateforme nécessite Python>=3.11 et ultralytics>=8.4.120 :

pip install "ultralytics>=8.4.120"

Vérifie l'installation :

yolo check

Authentification#

yolo login YOUR_API_KEY

Utiliser les jeux de données de la plateforme#

Référence les jeux de données 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 d'URI :

Envoyer vers Platform#

Envoie les résultats vers 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",
)

Éléments synchronisés :

• Métriques d'entraînement (en temps réel)
• Poids finaux du modèle
• Graphiques de validation
• La sortie de la console
• Métriques système
• Arguments d'entraînement et environnement hôte (nom d'hôte, système d'exploitation, Python, matériel, commit git, ligne de commande)

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

Exporter le 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#