Passer au contenu

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.

Démarrage rapide

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

# Run inference on a model
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.jpg" \
  https://platform.ultralytics.com/api/models/MODEL_ID/predict

Authentification

Toutes les requêtes API nécessitent une authentification via une clé API.

Obtenir la clé API

  1. Accédez à Paramètres > Clés API
  2. Cliquez sur Créer une clé
  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 ul_your_api_key_here

Exemple

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

URL de base

Tous les points d'accès API utilisent :

https://platform.ultralytics.com/api

Limites de débit

ForfaitRequêtes/MinuteRequêtes/Jour
Gratuit601,000
Pro30050,000
EntreprisePersonnaliséPersonnalisé

Les en-têtes de limitation de débit sont inclus dans les réponses :

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1640000000

Format de réponse

Toutes les réponses sont au format JSON :

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

Réponses d'erreur

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid dataset ID",
    "details": { ... }
  }
}

API des jeux de données

Lister les ensembles de données

GET /api/datasets

Paramètres de requête :

ParamètreTypeDescription
pageintNuméro de page (par défaut : 1)
limitintÉléments par page (par défaut : 20)
taskchaîne de caractèresFiltrer par type de tâche

Réponse :

{
    "success": true,
    "data": [
        {
            "id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "visibility": "private",
            "createdAt": "2024-01-15T10:00:00Z"
        }
    ]
}

Obtenir un jeu de données

GET /api/datasets/{datasetId}

Créer un jeu de données

POST /api/datasets

Corps :

{
    "name": "my-dataset",
    "task": "detect",
    "description": "A custom detection dataset"
}

Supprimer l'ensemble de données

DELETE /api/datasets/{datasetId}

Exporter le jeu de données

POST /api/datasets/{datasetId}/export

Renvoie l'URL de téléchargement au format NDJSON.

Obtenir des modèles formés sur un ensemble de données

GET /api/datasets/{datasetId}/models

Renvoie la liste des modèles qui ont été entraînés à l'aide de cet ensemble de données, en indiquant la relation entre les ensembles de données et les modèles qu'ils ont produits.

Réponse :

{
    "success": true,
    "data": [
        {
            "id": "model_abc123",
            "name": "experiment-1",
            "projectId": "project_xyz",
            "trainedAt": "2024-01-15T10:00:00Z",
            "metrics": {
                "mAP50": 0.85,
                "mAP50-95": 0.72
            }
        }
    ]
}

API des projets

Lister les projets

GET /api/projects

Obtenir un projet

GET /api/projects/{projectId}

Créer un projet

POST /api/projects

Corps :

{
    "name": "my-project",
    "description": "Detection experiments"
}

Supprimer le projet

DELETE /api/projects/{projectId}

API des modèles

Lister les modèles

GET /api/models

Paramètres de requête :

ParamètreTypeDescription
projectIdchaîne de caractèresFiltrer par projet
taskchaîne de caractèresFiltrer par type de tâche

Obtenir le modèle

GET /api/models/{modelId}

Télécharger le modèle

POST /api/models

Formulaire multipartie :

ChampTypeDescription
filefichierFichier .pt du modèle
projectIdchaîne de caractèresProjet cible
namechaîne de caractèresNom du modèle

Supprimer le modèle

DELETE /api/models/{modelId}

Télécharger le modèle

GET /api/models/{modelId}/files

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

Exécuter l'inférence

POST /api/models/{modelId}/predict

Formulaire multipartie :

ChampTypeDescription
filefichierFichier image
confflottantSeuil de confiance
iouflottantSeuil d'IoU

Réponse :

{
    "success": true,
    "predictions": [
        {
            "class": "person",
            "confidence": 0.92,
            "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
        }
    ]
}

API d'entraînement

Démarrer l'entraînement

POST /api/training/start

Corps :

{
    "modelId": "model_abc123",
    "datasetId": "dataset_xyz789",
    "epochs": 100,
    "imageSize": 640,
    "gpuType": "rtx-4090"
}

Obtenir le statut d'entraînement

GET /api/models/{modelId}/training

Annuler l'entraînement

DELETE /api/models/{modelId}/training

API des déploiements

Lister les déploiements

GET /api/deployments

Paramètres de requête :

ParamètreTypeDescription
modelIdchaîne de caractèresFiltrer par modèle

Créer un déploiement

POST /api/deployments

Corps :

{
    "modelId": "model_abc123",
    "region": "us-central1",
    "minInstances": 0,
    "maxInstances": 10
}

Obtenir le déploiement

GET /api/deployments/{deploymentId}

Démarrer le déploiement

POST /api/deployments/{deploymentId}/start

Arrêter le déploiement

POST /api/deployments/{deploymentId}/stop

Supprimer le déploiement

DELETE /api/deployments/{deploymentId}

Obtenir les métriques

GET /api/deployments/{deploymentId}/metrics

Obtenir les journaux

GET /api/deployments/{deploymentId}/logs

Paramètres de requête :

ParamètreTypeDescription
severitychaîne de caractèresINFO, WARNING, ERROR
limitintNombre d'entrées

API d'exportation

Lister les exportations

GET /api/exports

Créer une exportation

POST /api/exports

Corps :

{
    "modelId": "model_abc123",
    "format": "onnx"
}

Formats pris en charge :

onnx, torchscript, openvino, tensorrt, coreml, tflite, saved_model, graphdef, paddle, ncnn, edgetpu, tfjs, mnn, rknn, imx, axelera, executorch

Obtenir le statut d'exportation

GET /api/exports/{exportId}

API d'activité

track et gérer les événements d'activité de votre compte.

Lister l'activité

GET /api/activity

Paramètres de requête :

ParamètreTypeDescription
startDatechaîne de caractèresFiltrer à partir de la date (ISO)
endDatechaîne de caractèresFiltrer jusqu'à la date (ISO)
searchchaîne de caractèresRechercher dans les messages d'événement

Marquer les événements comme vus

POST /api/activity/mark-seen

Archiver les événements

POST /api/activity/archive

API Corbeille

Gérer les ressources supprimées logiquement (rétention de 30 jours).

Lister la corbeille

GET /api/trash

Restaurer l'élément

POST /api/trash

Corps :

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

Vider la corbeille

POST /api/trash/empty

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

API Facturation

Gérer les crédits et les abonnements.

Obtenir le solde

GET /api/billing/balance

Réponse :

{
    "success": true,
    "data": {
        "cashBalance": 5000000,
        "creditBalance": 20000000,
        "reservedAmount": 0,
        "totalBalance": 25000000
    }
}

Micro-USD

Tous les montants sont en micro-USD (1 000 000 = 1,00 $) pour une comptabilité précise.

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.

Créer une session de paiement

POST /api/billing/checkout-session

Corps :

{
    "amount": 25
}

Crée une session de paiement Stripe pour l'achat de crédits (5 $ - 1000 $).

Créer un paiement d'abonnement

POST /api/billing/subscription-checkout

Crée une session de paiement Stripe pour l'abonnement Pro.

Créer une session de portail

POST /api/billing/portal-session

Retourne l'URL du portail de facturation Stripe pour la gestion des abonnements.

Obtenir l'historique des paiements

GET /api/billing/payments

Retourne la liste des transactions de paiement de Stripe.

API Stockage

Obtenir les informations de stockage

GET /api/storage

Réponse :

{
    "success": true,
    "data": {
        "used": 1073741824,
        "limit": 107374182400,
        "percentage": 1.0
    }
}

API RGPD

Points d'accès de conformité RGPD pour l'exportation et la suppression de données.

Exporter/Supprimer les données du compte

POST /api/gdpr

Corps :

{
    "action": "export"
}
ActionDescription
exportTélécharger toutes les données du compte
deleteSupprimer le compte et toutes les données

Action irréversible

La suppression du compte est permanente et ne peut être annulée. Toutes les données, modèles et déploiements seront supprimés.

API 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",
    "scopes": ["training", "models"]
}

Supprimer une clé API

DELETE /api/api-keys/{keyId}

Codes d'erreur

CodeDescription
UNAUTHORIZEDClé API invalide ou manquante
FORBIDDENAutorisations insuffisantes
NOT_FOUNDRessource introuvable
VALIDATION_ERRORDonnées de requête invalides
RATE_LIMITEDTrop de requêtes
INTERNAL_ERRORErreur serveur

Python

Pour une intégration plus facile, utilisez le package python Ultralytics.

Installation et configuration

pip install ultralytics

Vérifier l'installation :

yolo check

Version de package requise

L'intégration à la plateforme nécessite ultralytics>=8.4.0. Les versions antérieures NE fonctionneront PAS avec la plateforme.

Authentification

Méthode 1 : CLI (recommandée)

yolo settings api_key=YOUR_API_KEY

Méthode 2 : Variable d'environnement

export ULTRALYTICS_API_KEY=YOUR_API_KEY

Méthode 3 : Dans le code

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("yolo11n.pt")

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

Format URI :

ul://{username}/{resource-type}/{name}

Examples:
ul://john/datasets/coco-custom     # Dataset
ul://john/my-project               # Project
ul://john/my-project/exp-1         # Specific model
ul://ultralytics/yolo26/yolo26n    # Official model

Poussée vers la plateforme

Envoyer les résultats à un projet Platform :

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

# Results automatically sync to Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="ul://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/my-dataset")

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

Webhooks

Les webhooks informent votre serveur des événements de la plateforme :

ÉvénementDescription
training.startedTâche d'entraînement démarrée
training.epochÉpoque terminée
training.completedEntraînement terminé
training.failedÉchec de l'entraînement
export.completedExportation prête

La configuration des webhooks est disponible dans les plans Entreprise.

FAQ

Comment paginer de grands ensembles de résultats ?

Utilisez page et limit paramètres :

GET /api/datasets?page=2 &
limit=50

Puis-je utiliser l'API sans SDK ?

Oui, toutes les fonctionnalités sont disponibles via REST. Le SDK est une couche d'abstraction pratique.

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 ?

Implémenter le retrait exponentiel :

import time


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


📅 Créé il y a 20 jours ✏️ Mis à jour il y a 14 jours
glenn-jocherLaughing-q

Commentaires