Vai al contenuto

Riferimento REST API

Ultralytics Platform fornisce una REST API completa per l'accesso programmatico a dataset, modelli, training e deployment.

Guida rapida

# 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

Autenticazione

Tutte le richieste API richiedono l'autenticazione tramite chiave API.

Ottieni chiave API

  1. Vai a Impostazioni > Chiavi API
  2. Clicca su Crea chiave
  3. Copia la chiave generata

Vedi Chiavi API per istruzioni dettagliate.

Header di Autorizzazione

Includi la tua chiave API in tutte le richieste:

Authorization: Bearer ul_your_api_key_here

Esempio

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

URL di Base

Tutti gli endpoint API utilizzano:

https://platform.ultralytics.com/api

Limiti di Frequenza

PianoRichieste/MinutoRichieste/Giorno
Gratuito601,000
Pro30050,000
EnterprisePersonalizzatoPersonalizzato

Le intestazioni di limitazione della frequenza sono incluse nelle risposte:

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

Formato della Risposta

Tutte le risposte sono in formato JSON:

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

Risposte di Errore

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

API dei Dataset

Elenca i dataset

GET /api/datasets

Parametri di query:

ParametroTipoDescrizione
pageintNumero di pagina (predefinito: 1)
limitintElementi per pagina (predefinito: 20)
taskstringFiltra per tipo di attività

Risposta:

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

Recupera Dataset

GET /api/datasets/{datasetId}

Crea Dataset

POST /api/datasets

Corpo:

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

Elimina dataset

DELETE /api/datasets/{datasetId}

Esporta Dataset

POST /api/datasets/{datasetId}/export

Restituisce l'URL di download in formato NDJSON.

Ottieni modelli addestrati sul set di dati

GET /api/datasets/{datasetId}/models

Restituisce l'elenco dei modelli che sono stati addestrati utilizzando questo set di dati, mostrando la relazione tra i set di dati e i modelli che hanno prodotto.

Risposta:

{
    "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 dei Progetti

Elenca Progetti

GET /api/projects

Recupera Progetto

GET /api/projects/{projectId}

Crea progetto

POST /api/projects

Corpo:

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

Elimina progetto

DELETE /api/projects/{projectId}

API dei Modelli

Elenca Modelli

GET /api/models

Parametri di query:

ParametroTipoDescrizione
projectIdstringFiltra per progetto
taskstringFiltra per tipo di attività

Recupera Modello

GET /api/models/{modelId}

Carica Modello

POST /api/models

Formato Multipart:

CampoTipoDescrizione
filefileFile .pt del modello
projectIdstringProgetto di destinazione
namestringNome del modello

Elimina modello

DELETE /api/models/{modelId}

Scarica Modello

GET /api/models/{modelId}/files

Restituisce URL di download firmati per i file del modello.

Esegui inferenza

POST /api/models/{modelId}/predict

Formato Multipart:

CampoTipoDescrizione
filefileFile immagine
conffloatSoglia di confidenza
ioufloatSoglia IoU

Risposta:

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

API di Addestramento

Avvia l'addestramento

POST /api/training/start

Corpo:

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

Recupera Stato Addestramento

GET /api/models/{modelId}/training

Annulla Addestramento

DELETE /api/models/{modelId}/training

API di Distribuzione

Elenca Distribuzioni

GET /api/deployments

Parametri di query:

ParametroTipoDescrizione
modelIdstringFiltra per modello

Crea Distribuzione

POST /api/deployments

Corpo:

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

Recupera Distribuzione

GET /api/deployments/{deploymentId}

Avvia Distribuzione

POST /api/deployments/{deploymentId}/start

Ferma Distribuzione

POST /api/deployments/{deploymentId}/stop

Elimina Distribuzione

DELETE /api/deployments/{deploymentId}

Recupera Metriche

GET /api/deployments/{deploymentId}/metrics

Recupera Log

GET /api/deployments/{deploymentId}/logs

Parametri di query:

ParametroTipoDescrizione
severitystringINFO, WARNING, ERROR
limitintNumero di voci

API di Esportazione

Elenca Esportazioni

GET /api/exports

Crea Esportazione

POST /api/exports

Corpo:

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

Formati supportati:

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

Recupera Stato Esportazione

GET /api/exports/{exportId}

API di Attività

Track e gestisci gli eventi di attività per il tuo account.

Elenca Attività

GET /api/activity

Parametri di query:

ParametroTipoDescrizione
startDatestringFiltra dalla data (ISO)
endDatestringFiltra alla data (ISO)
searchstringCerca nei messaggi degli eventi

Contrassegna Eventi come Visti

POST /api/activity/mark-seen

Archivia Eventi

POST /api/activity/archive

API del Cestino

Gestisci le risorse eliminate temporaneamente (conservazione di 30 giorni).

Elenca Cestino

GET /api/trash

Ripristina Elemento

POST /api/trash

Corpo:

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

Svuota Cestino

POST /api/trash/empty

Elimina definitivamente tutti gli elementi nel cestino.

API di Fatturazione

Gestisci crediti e abbonamenti.

Recupera Saldo

GET /api/billing/balance

Risposta:

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

Micro-USD

Tutti gli importi sono in micro-USD (1.000.000 = $1,00) per una contabilità precisa.

Recupera Riepilogo Utilizzo

GET /api/billing/usage-summary

Restituisce i dettagli del piano, i limiti e le metriche di utilizzo.

Crea Sessione di Checkout

POST /api/billing/checkout-session

Corpo:

{
    "amount": 25
}

Crea una sessione di checkout Stripe per l'acquisto di crediti ($5-$1000).

Crea Checkout Abbonamento

POST /api/billing/subscription-checkout

Crea una sessione di checkout Stripe per l'abbonamento Pro.

Crea Sessione Portale

POST /api/billing/portal-session

Restituisce l'URL al portale di fatturazione Stripe per la gestione degli abbonamenti.

Recupera Cronologia Pagamenti

GET /api/billing/payments

Restituisce l'elenco delle transazioni di pagamento da Stripe.

API di Archiviazione

Recupera Informazioni Archiviazione

GET /api/storage

Risposta:

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

API GDPR

Endpoint di conformità GDPR per l'esportazione e l'eliminazione dei dati.

Esporta/Elimina Dati Account

POST /api/gdpr

Corpo:

{
    "action": "export"
}
AzioneDescrizione
exportScarica tutti i dati dell'account
deleteElimina account e tutti i dati

Azione irreversibile

L'eliminazione dell'account è permanente e non può essere annullata. Tutti i dati, i modelli e i deployment verranno eliminati.

API delle chiavi API

Elenca chiavi API

GET /api/api-keys

Crea chiave API

POST /api/api-keys

Corpo:

{
    "name": "training-server",
    "scopes": ["training", "models"]
}

Elimina chiave API

DELETE /api/api-keys/{keyId}

Codici di errore

CodiceDescrizione
UNAUTHORIZEDChiave API non valida o mancante
FORBIDDENPermessi insufficienti
NOT_FOUNDRisorsa non trovata
VALIDATION_ERRORDati della richiesta non validi
RATE_LIMITEDTroppe richieste
INTERNAL_ERRORErrore del server

Python

Per una più facile integrazione, utilizza il pacchetto Ultralytics python.

Installazione e configurazione

pip install ultralytics

Verifica l'installazione:

yolo check

Requisiti di versione del pacchetto

L'integrazione della Piattaforma richiede Ultralytics>=8.4.0. Versioni precedenti NON funzioneranno con la Piattaforma.

Autenticazione

Metodo 1: CLI (consigliato)

yolo settings api_key=YOUR_API_KEY

Metodo 2: Variabile di ambiente

export ULTRALYTICS_API_KEY=YOUR_API_KEY

Metodo 3: Nel codice

from ultralytics import settings

settings.api_key = "YOUR_API_KEY"

Utilizzo dei dataset della piattaforma

Set di dati di riferimento con 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,
)

Formato 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

Spingere verso la piattaforma

Invia i risultati a un progetto della piattaforma:

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",
)

Cosa si sincronizza:

  • Metriche di allenamento (in tempo reale)
  • Pesi del modello finale
  • Grafici di convalida
  • Output della console
  • Metriche di sistema

Esempi API

Carica un modello dalla piattaforma:

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

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

Esegui inferenza:

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

Modello di esportazione:

# 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)

Convalida:

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

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

Webhook

I webhook notificano al tuo server gli eventi della Piattaforma:

EventoDescrizione
training.startedAddestramento avviato
training.epochEpoca completata
training.completedAddestramento terminato
training.failedAddestramento fallito
export.completedEsportazione pronta

La configurazione dei webhook è disponibile nei piani Enterprise.

FAQ

Come si paginano risultati di grandi dimensioni?

Usa page e limit parametri:

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

Posso usare l'API senza un SDK?

Sì, tutte le funzionalità sono disponibili tramite REST. L'SDK è un wrapper di convenienza.

Esistono librerie client API?

Attualmente, utilizza il pacchetto Ultralytics python o effettua richieste HTTP dirette. Sono previste librerie client ufficiali per altri linguaggi.

Come si gestiscono i limiti di frequenza?

Implementa il backoff esponenziale:

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")


📅 Creato 20 giorni fa ✏️ Aggiornato 14 giorni fa
glenn-jocherLaughing-q

Commenti