Riferimento REST API#

Ultralytics Platform offre un'API REST completa per l'accesso programmatico a dataset, modelli, training e distribuzioni.

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

Panoramica API#

L'API è organizzata attorno alle risorse principali della piattaforma:

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

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

Autenticazione#

Le API delle risorse utilizzano l'autenticazione tramite API key, incluse la gestione delle classi e delle suddivisioni del dataset, la clonazione, l'addestramento, le esportazioni, i deployment e la lettura degli account supportati. Gli endpoint pubblici supportano l'accesso anonimo ove indicato. Le route dell'applicazione riservate al browser sono escluse.

Ottieni API Key#

1. Vai a Settings > API Keys
2. Fai clic su Create Key
3. Copia la chiave generata

Vedi le API Keys per istruzioni dettagliate.

Header di autorizzazione#

Includi la tua API key in tutte le richieste:

Authorization: Bearer YOUR_API_KEY

Esempio#

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

Base URL#

Tutti gli endpoint API utilizzano:

https://platform.ultralytics.com/api

Limiti di frequenza#

L'API applica limiti basati su finestra scorrevole e supportati da Upstash Redis per ogni chiave API. Ciascuna rotta utilizza la categoria corrispondente di seguito.

Quando viene limitata la frequenza, l'API restituisce 429 con metadati di nuovo tentativo:

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

Limiti per API Key#

I limiti di frequenza vengono applicati automaticamente in base all'endpoint chiamato. Le operazioni onerose hanno limiti più rigidi per prevenire abusi, mentre le operazioni CRUD standard condividono un generoso limite predefinito:

Ogni categoria ha un contatore indipendente per ogni API key. Ad esempio, effettuare 20 richieste di predizione non influisce sulla tua soglia predefinita di 100 richieste/min.

Endpoint dedicati (Illimitato)#

Gli endpoint dedicati non sono soggetti ai limiti di frequenza delle API key della piattaforma quando chiami direttamente l'URL dell'endpoint (ad esempio, https://predict-abc123.run.app/predict). Il throughput dipende quindi dalla configurazione del servizio distribuito.

Formato risposta#

Risposte di successo#

Le risposte restituiscono JSON con campi specifici per la risorsa:

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

Risposte di errore#

{
    "error": "Dataset not found"
}

API dei Dataset#

Crea, esplora e gestisci dataset di immagini etichettate per l'addestramento dei modelli YOLO. Vedi la documentazione dei dataset.

Elenca Dataset#

GET /api/datasets

Parametri di query:

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

Risposta:

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

Ottieni Dataset#

GET /api/datasets/{datasetId}

Restituisce i dettagli del dataset inclusi i nomi delle classi, i conteggi delle suddivisioni e altre proprietà gestite da Platform. I metadati personalizzati vengono caricati separatamente dall'endpoint dei metadati sottostante.

Passa username quando {datasetId} è uno slug di dataset anziché un ID.

Crea Dataset#

POST /api/datasets

Corpo:

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

Risposta:

{
    "datasetId": "dataset_abc123",
    "slug": "my-dataset",
    "region": "us"
}

Aggiorna Dataset#

PATCH /api/datasets/{datasetId}

Corpo (aggiornamento parziale):

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

Invia un oggetto metadata vuoto ({}) per cancellare i metadati personalizzati. L'oggetto di metadati serializzato è limitato a 500.000 caratteri e ogni chiave di primo livello è limitata a 128 caratteri.

Ottieni i metadati del dataset#

GET /api/datasets/{datasetId}/metadata

Restituisce l'oggetto di metadati personalizzati e un insieme curato di coppie chiave/valore gestite da Ultralytics in sola lettura. I metadati personalizzati vengono intenzionalmente omessi dai normali payload del dataset. Sono richiesti l'autenticazione e l'accesso al workspace del dataset.

Icona del dataset#

POST /api/datasets/{datasetId}/icon
DELETE /api/datasets/{datasetId}/icon

Carica un'icona WebP fino a 5 MB come campo form multipart image, oppure rimuovi l'icona corrente.

Elimina Dataset#

DELETE /api/datasets/{datasetId}

Elimina temporaneamente il dataset (spostato nel cestino, recuperabile per 30 giorni).

Clona dataset#

POST /api/datasets/{datasetId}/clone

Crea una copia di un dataset di un workspace pubblico, di proprietà o modificabile, con tutte le immagini e le etichette.

Body opzionale (tutti i campi sono opzionali):

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

Esporta Dataset#

GET /api/datasets/{datasetId}/export

Restituisce una risposta JSON con un URL di download firmato per l'ultima esportazione del dataset.

Parametri di query:

Risposta:

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

Crea Versione Dataset#

POST /api/datasets/{datasetId}/export

Crea una nuova istantanea di versione numerata del dataset. Questa operazione richiede almeno l'accesso come Editor. La versione acquisisce il conteggio corrente di immagini, classi, annotazioni e la distribuzione degli split, quindi genera e archivia un'esportazione NDJSON immutabile.

Corpo della richiesta:

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

Tutti i campi sono facoltativi. Il campo description è un'etichetta fornita dall'utente per la versione.

Risposta:

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

Aggiorna Descrizione Versione#

PATCH /api/datasets/{datasetId}/export

Aggiorna la descrizione di una versione esistente. Questa operazione richiede almeno l'accesso come Editor.

Corpo della richiesta:

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

Risposta:

{
    "ok": true
}

Ripristina versione dataset#

POST /api/datasets/{datasetId}/restore

Ricostruisci immagini, annotazioni e classi del dataset da una versione salvata senza copiare i byte delle immagini.

{
    "version": 2
}

Ottieni Statistiche Classi#

GET /api/datasets/{datasetId}/class-stats

Restituisce la distribuzione delle classi, la mappa di calore della posizione e le statistiche dimensionali. I risultati sono memorizzati nella cache fino a 5 minuti.

Risposta:

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

Gestisci Classi#

Unisci classi (riassegna le annotazioni dalle classi di origine a una destinazione, quindi rimuovi le origini):

POST /api/datasets/{datasetId}/classes/merge

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

Gli ID delle classi sono posizionali, quindi l'unione non è idempotente. Recupera nuovamente il dataset prima di riprovare.

Elimina classi:

POST /api/datasets/{datasetId}/classes/delete

{
    "classIds": [2, 4]
}

Ridistribuisci Split#

POST /api/datasets/{datasetId}/splits/redistribute

Riassegna casualmente le immagini tra le suddivisioni di training, validazione e test. Le percentuali devono sommare 100.

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

Embedding del Dataset#

GET /api/datasets/{datasetId}/embeddings
POST /api/datasets/{datasetId}/embeddings
DELETE /api/datasets/{datasetId}/embeddings

GET restituisce il sommario dell'analisi UMAP corrente e lo stato del job attivo; POST accoda un job di analisi degli embedding; DELETE annulla il job attivo.

Clustering Immagini#

GET /api/datasets/{datasetId}/images/clustering

Restituisce il layout 2D UMAP e i metadati per singola immagine per la vista a dispersione (paginata e con limitazione di frequenza).

Ottieni Modelli Addestrati sul Dataset#

GET /api/datasets/{datasetId}/models

Restituisce i modelli che sono stati addestrati utilizzando questo dataset.

Risposta:

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

Annotazione Automatica del Dataset#

POST /api/datasets/{datasetId}/predict

Esegue l'inferenza YOLO sulle immagini del dataset per generare automaticamente le annotazioni. Utilizza un modello selezionato per prevedere le etichette per le immagini non annotate.

Corpo:

Ingestione Dataset#

POST /api/datasets/ingest

Crea un processo di inserimento dataset per un dataset esistente. Il dataset di destinazione viene sempre passato come datasetId nel corpo JSON, non nel percorso dell'URL.

Il corpo della richiesta richiede datasetId più esattamente uno tra sessionId (la sessione di caricamento di un archivio caricato) o sourceUrl (un URL ZIP, TAR, TAR.GZ, TGZ o NDJSON remoto). Aggiungi l'elemento opzionale targetSplit (train, val o test) per sovrascrivere la struttura di suddivisione dell'archivio. Per allegare metadati personalizzati, utilizza imageMetadata, indicizzato dal percorso esatto relativo all'archivio di ciascuna immagine o dal valore NDJSON file.

Per gli archivi caricati, la sessione di caricamento è già associata al dataset tramite assetId passato a POST /api/upload/signed-url; l'inserimento convalida che assetId corrisponda al corpo datasetId. Le voci opzionali di classMapping mappano ciascun nome di classe in arrivo a un indice di classe esistente basato su zero, a un nome di classe da riutilizzare o creare, o a null per saltare la classe. Per le importazioni remote di sourceUrl, crea prima il dataset, quindi passa il suo datasetId all'inserimento.

Corpo (archivio caricato):

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

Corpo (una o più immagini con metadati):

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

Le immagini locali utilizzano il flusso di caricamento dell'archivio esistente, indipendentemente dal fatto che l'archivio contenga un'immagine o molteplici. La chiave deve corrispondere al percorso normalizzato all'interno dell'archivio, comprese le cartelle. Per le importazioni NDJSON, ogni record di immagine può invece contenere il proprio oggetto metadata. L'elemento locale al record metadata ha la precedenza su una voce corrispondente di imageMetadata.

I metadati sono in formato JSON e supportano valori nidificati. I percorsi degli archivi sono limitati a 1.024 caratteri, le chiavi dei metadati di primo livello a 128 caratteri e ciascun oggetto di metadati a 500.000 caratteri serializzati. Anche la mappa completa di imageMetadata, o i metadati effettivi combinati in un'importazione NDJSON, sono limitati a 500.000 caratteri serializzati. Questi vincoli sono inclusi nello schema OpenAPI interattivo.

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
dataset_id = "dataset_abc123"
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/ingest",
    headers=headers,
    json={
        "datasetId": dataset_id,
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

Corpo (archivio remoto o NDJSON):

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

Corpo (ingest successivo, importazione etichette):

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "car", "background": null }
}

Risposta:

{
    "jobId": "job_abc123",
    "datasetId": "dataset_abc123",
    "status": "queued"
}

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

Immagini del Dataset#

Elenca Immagini#

GET /api/datasets/{datasetId}/images

Parametri di query:

Ottieni immagini selezionate#

POST /api/datasets/{datasetId}/images

Restituisce la stessa forma dell'immagine per un massimo di 1.000 ID immagine forniti. Accetta gli stessi controlli URL e di query delle etichette dell'operazione list.

{
    "imageIds": ["IMAGE_OBJECT_ID"]
}

Ottieni URL Firmati delle Immagini#

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

Ottieni URL firmati per un batch di hash di immagini (per la visualizzazione nel browser).

Elimina Immagine#

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

Ottieni Etichette Immagine#

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

Restituisce annotazioni e nomi delle classi per un'immagine specifica.

Aggiorna Etichette Immagine#

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

Corpo:

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

Operazioni in Massa sulle Immagini#

Sposta le immagini tra le suddivisioni (train/val/test) all'interno di un dataset:

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

Eliminazione in massa delle immagini:

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

API dei Progetti#

Organizza i tuoi modelli in progetti. Ciascun modello appartiene a un progetto. Vedi la documentazione dei progetti.

Elenca Progetti#

GET /api/projects

Parametri di query:

Ottieni Progetto#

GET /api/projects/{projectId}

Crea Progetto#

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",
    "metadata": {"department": "manufacturing", "cost_center": "cv-01"}
  }' \
  https://platform.ultralytics.com/api/projects

Aggiorna Progetto#

PATCH /api/projects/{projectId}

Corpo (aggiornamento parziale):

{
    "metadata": { "department": "research", "program": "inspection" }
}

Invia un oggetto metadata vuoto ({}) per cancellarlo. I metadati del progetto utilizzano gli stessi limiti di 128 caratteri per la chiave di primo livello e 500.000 caratteri per l'oggetto serializzato dei metadati del dataset.

Ottieni i metadati del progetto#

GET /api/projects/{projectId}/metadata

Restituisce l'oggetto di metadati personalizzati e le coppie chiave/valore gestite da Ultralytics in sola lettura. Sono richiesti l'autenticazione e l'accesso al workspace del progetto.

Elimina Progetto#

DELETE /api/projects/{projectId}

Elimina temporaneamente il progetto (spostato nel cestino).

Clona Progetto#

POST /api/projects/{projectId}/clone

Clona un progetto di workspace pubblico, di proprietà o modificabile e i suoi modelli nel tuo account o workspace. Un corpo JSON facoltativo accetta sovrascritture per name, slug, description, visibility, license e la destinazione owner.

Icona Progetto#

POST /api/projects/{projectId}/icon
DELETE /api/projects/{projectId}/icon

Carica un'icona WebP fino a 5 MB come campo form multipart image, oppure rimuovi l'icona corrente.

API Modelli#

Gestisci i modelli YOLO addestrati: visualizza le metriche, scarica i pesi, esegui l'inferenza ed esporta in altri formati. Vedi la documentazione dei modelli.

Elenco Modelli#

GET /api/models

Parametri di query:

Elenco Modelli Completati#

GET /api/models/completed

Restituisce fino a 1.000 modelli con pesi utilizzabili in tutti i progetti per il training e la distribuzione. Passa owner per un workspace.

Ottieni Modello#

GET /api/models/{modelId}

Crea Modello#

POST /api/models

Corpo JSON:

Aggiorna Modello#

PATCH /api/models/{modelId}

Corpo (aggiornamento parziale):

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

Invia un oggetto metadata vuoto ({}) per cancellarlo. I metadati personalizzati del modello sono separati dalle informazioni del modello di proprietà dell'addestramento, dai dettagli dell'ambiente e dagli argomenti di addestramento, e utilizzano gli stessi limiti di oggetto serializzato e chiave di primo livello dei metadati del dataset.

Ottieni i metadati del modello#

GET /api/models/{modelId}/metadata

Restituisce l'oggetto di metadati personalizzati e le coppie chiave/valore gestite da Ultralytics in sola lettura. Sono richiesti l'autenticazione e l'accesso al workspace del modello.

Elimina Modello#

DELETE /api/models/{modelId}

Scarica File Modello#

GET /api/models/{modelId}/files

Restituisce URL di download firmati per i file del modello.

Clona modello#

POST /api/models/{modelId}/clone

Clona un modello di un workspace pubblico, di proprietà o modificabile in uno dei tuoi progetti.

Corpo:

{
    "targetProjectSlug": "my-project",
    "modelName": "cloned-model",
    "description": "Cloned from public model",
    "owner": "team-username"
}

Traccia Download#

POST /api/models/{modelId}/track-download

Traccia le analisi di download del modello.

Esegui l'inferenza#

POST /api/models/{modelId}/predict

I modelli pubblici possono essere utilizzati per la predizione senza autenticazione. I modelli privati e condivisi richiedono una API key con accesso al progetto padre.

Modulo Multipart:

Fornisci file oppure source. La dimensione massima di caricamento è 100 MB.

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

Risposta:

Le risposte contengono per ciascuna immagine shape, speed, results e dati opzionali di mappa di pixel densa (una mappa di classi semantiche, o una mappa di profondità in cui depth = pixel × max / divisor — divisore 255 per la mappa predefinita a 8 bit, 65535 con bits=12|16), oltre a metadata con il conteggio delle immagini, la tempistica delle funzioni, il task e le versioni del servizio. I percorsi interni dei modelli non vengono mai restituiti.

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

API di Addestramento#

Avvia il training YOLO su GPU cloud (26 tipi di GPU da RTX 2000 Ada a B300) e monitora i progressi in tempo reale. Vedi la documentazione del Cloud Training.

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

Avvia Addestramento#

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

Ottieni disponibilità GPU#

GET /api/training/gpu-availability

Restituisce lo stato attuale delle scorte di GPU (High, Medium, Low o null) indicizzato per ID del tipo di GPU. Pubblico, non è richiesta alcuna autenticazione; memorizzato nella cache per 5 minuti.

Ottieni Stato Addestramento#

GET /api/models/{modelId}/training

Restituisce lo stato attuale del job di addestramento, metriche, progressi, tempistiche, dettagli GPU ed errori. I progetti pubblici sono accessibili senza autenticazione; i progetti privati e condivisi richiedono una API key con accesso.

Annulla Addestramento#

DELETE /api/models/{modelId}/training

Termina l'istanza di calcolo in esecuzione e contrassegna il job come annullato.

API Deployments#

Distribuisci i modelli a endpoint di inferenza dedicati con controlli di integrità e monitoraggio. Per impostazione predefinita, le nuove distribuzioni utilizzano la scalabilità a zero e l'API accetta un oggetto opzionale resources. Vedi la documentazione degli endpoint.

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

Elenco Deployments#

GET /api/deployments

Parametri di query:

Crea Deployment#

POST /api/deployments

Corpo:

{
    "modelId": "model_abc123",
    "name": "my-deployment",
    "region": "us-central1",
    "resources": {
        "cpu": 1,
        "memoryGi": 2,
        "minInstances": 0,
        "maxInstances": 1
    }
}

Crea un endpoint di inferenza dedicato nella regione specificata. L'endpoint è accessibile globalmente tramite un URL univoco.

Ottieni Deployment#

GET /api/deployments/{deploymentId}

Elimina Deployment#

DELETE /api/deployments/{deploymentId}

Avvia Deployment#

POST /api/deployments/{deploymentId}/start

Riprendi un deployment interrotto.

Interrompi Deployment#

POST /api/deployments/{deploymentId}/stop

Interrompi la gestione delle richieste impostando a zero le istanze minime e massime del servizio.

Controllo Integrità#

GET /api/deployments/{deploymentId}/health

Restituisce lo stato di integrità dell'endpoint di deployment.

Esegui Inferenza sul Deployment#

POST /api/deployments/{deploymentId}/predict

Invia un'immagine direttamente a un endpoint di deployment per l'inferenza. Funzionalmente equivalente alla predizione del modello, ma instradata attraverso l'endpoint dedicato per una latenza inferiore.

Modulo Multipart:

Fornisci file oppure source. La risposta utilizza lo stesso contratto di immagine e metadati della predizione del modello e non restituisce mai il percorso interno del modello.

Ottieni Metriche#

GET /api/deployments/{deploymentId}/metrics

Restituisce il conteggio delle richieste, la latenza e le metriche del tasso di errore con dati sparkline.

Parametri di query:

Ottieni Log#

GET /api/deployments/{deploymentId}/logs

Parametri di query:

API di esportazione#

Converti i modelli in formati ottimizzati come ONNX, TensorRT, CoreML e LiteRT per la distribuzione edge. Vedi la documentazione di distribuzione.

Elenco esportazioni#

GET /api/exports

Parametri di query:

Crea esportazione#

POST /api/exports

Corpo:

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

Formati supportati:

Usa l'argomento format dalla tabella di esportazione condivisa sottostante. PyTorch è il formato di origine e non costituisce una destinazione di esportazione API.

Ottieni stato esportazione#

GET /api/exports/{exportId}

Annulla esportazione#

DELETE /api/exports/{exportId}

Traccia download esportazione#

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

API di attività#

Visualizza un feed delle azioni recenti sul tuo account: esecuzioni di training, caricamenti e altro ancora. Vedi la documentazione delle attività.

Elenco attività#

GET /api/activity

Parametri di query:

Contrassegna eventi come letti#

POST /api/activity/mark-seen

Corpo:

{
    "all": true
}

Oppure passa ID specifici:

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

Passa il parametro di query opzionale owner per contrassegnare gli eventi in un workspace.

Archivia eventi#

POST /api/activity/archive

Corpo:

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

Oppure passa ID specifici:

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

Passa il parametro di query opzionale owner per archiviare o ripristinare gli eventi del workspace.

API cestino#

Visualizza e ripristina gli elementi eliminati. Gli elementi vengono rimossi definitivamente dopo 30 giorni. Vedi la documentazione del cestino.

Elenco cestino#

GET /api/trash

Parametri di query:

Ripristina elemento#

POST /api/trash

Corpo:

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

Elimina definitivamente elemento#

DELETE /api/trash

Corpo:

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

Svuota cestino#

DELETE /api/trash/empty

Elimina definitivamente tutti gli elementi nel cestino.

API di fatturazione#

Controlla il tuo saldo crediti, l'utilizzo del piano e la cronologia delle transazioni. Vedi la documentazione di fatturazione.

Gli endpoint di saldo e transazione accettano un parametro di query opzionale owner con il nome utente del proprietario del workspace.

Ottieni saldo#

GET /api/billing/balance

Risposta:

{
    "creditsCents": 2500,
    "plan": "free"
}

Ottieni riepilogo utilizzo#

GET /api/billing/usage-summary

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

Ottieni transazioni#

GET /api/billing/transactions

Restituisce lo storico delle transazioni (i più recenti per primi).

Le transazioni includono campi del registro lato client come importo, saldo risultante, data, contesto del modello opzionale e URL della ricevuta. Note interne, ID pagamento/rimborso Stripe e chiavi di idempotenza non vengono restituiti.

API di archiviazione#

Controlla la suddivisione dell'utilizzo dello spazio di archiviazione per categoria (dataset, modelli, export) e visualizza i tuoi elementi più grandi.

Ottieni informazioni sull'archiviazione#

GET /api/storage

Parametri di query:

Risposta:

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

Integrazioni con cloud storage#

Connetti ed esplora integrazioni GCS, S3 o Azure Blob a sola lettura:

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

Tutte e quattro le operazioni accettano il parametro di query opzionale owner per un workspace. La visualizzazione degli oggetti accetta inoltre i parametri di query obbligatori target più quelli facoltativi prefix e del provider cursor. I corpi delle richieste di connessione e rilevamento utilizzano gli schemi delle credenziali del provider nella reference OpenAPI interattiva; le credenziali non vengono mai restituite.

API di caricamento#

Carica i file direttamente sull'archiviazione cloud utilizzando URL firmati per trasferimenti rapidi e affidabili. Il completamento del caricamento di un modello ne allega i relativi pesi. Il completamento del caricamento di un archivio di dataset registra la sessione; passa tale sessionId a POST /api/datasets/ingest per avviare l'elaborazione. Vedi la documentazione dei dati.

Ottieni URL di caricamento firmato#

POST /api/upload/signed-url

Richiedi un URL firmato per caricare un file direttamente nell'archiviazione cloud. L'URL firmato bypassa il server API per i trasferimenti di file di grandi dimensioni.

Corpo:

{
    "assetType": "datasets",
    "assetId": "dataset_abc123",
    "filename": "my-dataset.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

Risposta:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

Completa il caricamento#

POST /api/upload/complete

Notifica alla piattaforma che il caricamento di un file è completato. Per i modelli, questo allega i pesi caricati. Per gli archivi di dataset, questo verifica e registra la sessione di caricamento; chiama successivamente POST /api/datasets/ingest per avviare l'elaborazione del dataset.

Corpo:

{
    "sessionId": "session_abc123",
    "checksum": "<optional sha-256 hex>"
}

API di Integrazione#

Importa dataset da servizi di terze parti. Vedi la documentazione delle integrazioni.

Anteprima Importazione Roboflow#

POST /api/integrations/roboflow/preview

Risolvi una API key di Roboflow verso un piano di importazione massiva: informazioni sul workspace, quali progetti verrebbero importati come nuovi, conteggio delle versioni già importate (saltate) e tipi di progetto non supportati. La API key di Roboflow viene passata nel corpo della richiesta e non viene salvata.

Importa da Roboflow#

POST /api/integrations/roboflow/import

Accoda job di ingestione del dataset per importare i progetti Roboflow selezionati nel tuo workspace. Richiede spazio di archiviazione disponibile e ogni dataset deve rientrare nel limite di dimensione per importazione previsto dal tuo piano.

API delle chiavi API#

Gestisci le tue API keys per l'accesso programmatico. Vedi la documentazione delle API Keys.

Elenca le chiavi API#

GET /api/api-keys

I client autenticati tramite API key ricevono i metadati delle chiavi, mai i valori delle chiavi esistenti decrittografati. Una chiave appena creata viene restituita una sola volta da POST /api/api-keys.

Passa il parametro di query opzionale owner per gestire le chiavi di un workspace in cui disponi dell'accesso come editor.

Crea chiave API#

POST /api/api-keys

Corpo:

{
    "name": "training-server"
}

Elimina chiave API#

DELETE /api/api-keys

Parametri di query:

Esempio:

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/api-keys?keyId=KEY_ID"

API di team e membri#

Crea workspace di team, invita membri e gestisci i ruoli per la collaborazione. Vedi la documentazione dei team.

Elenca i team#

GET /api/teams

Crea team#

POST /api/teams/create

Corpo:

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

Elenca i membri#

GET /api/members

Restituisce i membri dello spazio di lavoro corrente.

Invita membro#

POST /api/members

Corpo:

{
    "email": "user@example.com",
    "role": "editor"
}

Aggiorna ruolo membro#

PATCH /api/members/{userId}

Rimuovi membro#

DELETE /api/members/{userId}

Trasferisci proprietà#

POST /api/members/transfer-ownership

API di esplorazione#

Cerca ed esplora dataset pubblici e progetti condivisi dalla community. Vedi la documentazione di esplorazione.

Cerca contenuti pubblici#

GET /api/explore/search

Parametri di query:

Dati della barra laterale#

GET /api/explore/sidebar

Restituisce contenuti curati per la barra laterale di esplorazione.

API utente e impostazioni#

Gestisci il tuo profilo, le API keys, l'utilizzo dello spazio di archiviazione e i workspace di team. Vedi la documentazione delle impostazioni.

Riepilogo account#

GET /api/account/summary

Restituisce il piano dell'account autenticato, il saldo crediti, i conteggi delle risorse e i workspace del team.

Ottieni utente tramite nome utente#

GET /api/users

Parametri di query:

Segui o smetti di seguire un utente#

PATCH /api/users

Corpo:

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

Verifica disponibilità nome utente#

GET /api/username/check

Parametri di query:

Impostazioni#

GET /api/settings
POST /api/settings

Ottieni o aggiorna le impostazioni del profilo utente (nome visualizzato, bio, link social, ecc.).

Icona del workspace#

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

Carica un'icona per il profilo o il workspace in formato WebP fino a 5 MB come campo form multipart image, oppure rimuovila. Passa l'elemento opzionale owner per un workspace di team.

Integrazione Python#

Per un'integrazione più semplice, usa il pacchetto Python Ultralytics che gestisce automaticamente l'autenticazione, i caricamenti e lo streaming delle metriche in tempo reale.

Installazione e configurazione#

pip install "ultralytics>=8.4.104"

Verifica l'installazione:

yolo check

Autenticazione#

yolo login YOUR_API_KEY

Uso dei dataset della piattaforma#

Fai riferimento ai dataset con gli 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,
)

Formato URI:

Invio alla piattaforma#

Invia i risultati a un progetto della piattaforma:

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

Cosa viene sincronizzato:

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

Esempi di 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 l'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

Esporta modello:

# 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

Validazione:

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

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

FAQ#

Come posso paginare grandi risultati?#

La maggior parte degli endpoint utilizza un parametro limit per controllare quanti risultati vengono restituiti per richiesta:

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

Gli endpoint Attività e Cestino supportano inoltre un parametro page per la paginazione basata sulle pagine:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/activity?page=2&limit=20"

L'endpoint Explore Search utilizza offset invece di page, con una dimensione di pagina fissa di 20:

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

Posso usare l'API senza un SDK?#

Le operazioni REST pubbliche documentate sopra sono disponibili senza il Python SDK. L'SDK è un wrapper di comodo utilizzo che aggiunge funzionalità come lo streaming di metriche in tempo reale e il caricamento automatico dei modelli. Puoi esplorare il contratto leggibile a macchina in modo interattivo su platform.ultralytics.com/api/docs; i flussi dell'account limitati alla sessione del browser rimangono nella Platform UI.

Esistono librerie client API?#

Usa il pacchetto Python di Ultralytics o effettua richieste HTTP dirette da qualsiasi linguaggio.

Come gestisco i limiti di velocità (rate limits)?#

Usa l'intestazione Retry-After della risposta 429 per attendere il tempo corretto:

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

Come trovo il mio ID modello o dataset?#

Gli ID delle risorse vengono restituiti dalle risposte API di creazione, elenco e recupero. Gli URL delle pagine della piattaforma utilizzano slug leggibili dall'utente, non ID di database:

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

Usa gli endpoint di elenco per trovare il corrispondente _id per un modello, un dataset, un progetto, un deployment o un'altra risorsa.