Riferimento REST API#

Ultralytics Platform offre un'API REST per l'accesso programmatico a dataset, immagini, progetti, modelli, addestramenti, esportazioni e distribuzioni.

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

Panoramica API#

L'API è organizzata attorno alle risorse principali della 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

Autenticazione#

La maggior parte degli endpoint richiede una chiave API. Gli endpoint che espongono contenuti pubblici — la lettura di un dataset, progetto o modello pubblico, l'elenco delle immagini di un dataset pubblico, l'esecuzione di inferenza su un modello pubblico o la ricerca in Explore — accettano anche richieste anonime e restituiscono semplicemente più dati quando viene fornita una chiave.

Ottieni una Chiave API#

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 chiave API come token di tipo bearer:

Authorization: Bearer YOUR_API_KEY

Esempio#

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

Base URL#

Tutti gli endpoint API utilizzano:

https://platform.ultralytics.com/api

Percorsi delle Risorse#

Le risorse vengono indirizzate tramite gli stessi nomi leggibili dall'uomo che compaiono negli URL della Platform, e non tramite ID di database:

• {owner} è un nome utente personale o l'handle di un workspace di team: da 4 a 32 caratteri, alfanumerici minuscoli con singoli hyphen tra i segmenti.
• {dataset}, {project}, {model} e {deployment} seguono lo stesso pattern minuscolo con trattini, fino a 128 caratteri.
• {imageId} e {exportId} sono ID esadecimali a 24 caratteri restituiti dall'API.
• Rinominare una risorsa tramite PATCH modifica contemporaneamente il nome di visualizzazione name e il nome nell'URL, e la risposta restituisce il nome URL corrente in modo da poter continuare a seguirlo.

Limiti di frequenza#

L'API applica limiti a finestra scorrevole per ciascuna chiave API. Ogni rotta rientra in una categoria e ciascuna categoria ha un contatore indipendente, quindi 20 richieste di predizione non consumano la tua quota predefinita.

Le rotte della Platform riservate al browser, come il checkout della fatturazione e la gestione del team, hanno i propri limiti che non si applicano al traffico basato su chiavi API.

Quando viene applicata la limitazione di velocità (throttling), l'API restituisce 429 con sia le intestazioni che un corpo 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"
}

Endpoint dedicati (Illimitato)#

Gli endpoint dedicati non sono soggetti ai limiti di frequenza della chiave API della Platform quando chiami direttamente il serviceUrl della distribuzione (ad esempio, https://predict-abc123.run.app/predict). Il throughput dipende quindi dalla configurazione del servizio distribuito.

Formato risposta#

Risposte di successo#

Le risposte sono oggetti JSON con campi specifici per risorsa. Non esiste un involucro generico: gli endpoint di elenco restituiscono una collezione denominata insieme ai conteggi, e le mutazioni restituiscono gli identificatori modificati.

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

Le risposte contenenti dati includono anche region (us, eu o ap), ovvero la regione di storage per quel workspace.

Risposte di errore#

Ogni risposta di errore è un oggetto JSON con un messaggio error:

{
    "error": "Dataset not found"
}

Paginazione#

Lo stile di paginazione dipende dalla collezione:

API dei Dataset#

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

Elenca Dataset#

GET /api/datasets/{owner}

Python SDK: client.datasets.list(owner)

Restituisce i dataset pubblici del proprietario, oltre ai dataset privati quando la tua chiave può visualizzare quel workspace.

Parametri di query:

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

Risposta:

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

Ottieni Dataset#

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

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

Restituisce l'oggetto dataset completo sotto una chiave dataset, inclusi classNames, splits, versions, source e l'oggetto metadata definito dall'utente.

Crea Dataset#

POST /api/datasets

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

Corpo:

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

Risposta (201):

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

Aggiorna Dataset#

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

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

Corpo (aggiornamento parziale):

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

Campi accettati: name, description, visibility, metadata, tags, classNames, classColors, format, task, license, iconColor, iconLetter e starred. Invia un oggetto metadata vuoto ({}) per pulire i metadati personalizzati. Le chiavi dei metadati sono limitate a 128 caratteri e l'oggetto serializzato a 500.000 caratteri.

Risposta:

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

La modifica del nome cambia il nome nell'URL, quindi usa il valore dataset restituito per le richieste successive.

Elimina Dataset#

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

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

Sposta il dataset nel trash, dove rimane recuperabile per 30 giorni.

Clona dataset#

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

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

Copia un dataset accessibile, insieme alle sue immagini e etichette, nel tuo workspace personale o in un workspace di team.

Corpo opzionale (tutti i campi sono opzionali):

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

Risposta (201): id, owner, dataset, name, imageCount, classCount e region. I dataset supportati da una risorsa di storage connessa restituiscono 409 poiché i loro file non vengono copiati.

Scarica un'Esportazione di Dataset#

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

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

Restituisce un URL di download NDJSON firmato. Ometti v per esportare lo stato corrente del dataset, riutilizzando l'esportazione memorizzata nella cache quando non è cambiato nulla da quando è stata generata.

Parametri di query:

Risposta:

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

La richiesta di una versione specifica restituisce downloadUrl e version anziché cached.

Crea Versione Dataset#

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

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

Crea un'istantanea numerata immutabile del dataset e memorizza la sua esportazione NDJSON. Richiede l'accesso come editor.

Corpo (facoltativo):

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

Risposta:

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

reused corrisponde a true quando il dataset è rimasto invariato rispetto alla versione precedente e quell'istantanea è stata restituita al suo posto.

Aggiorna Descrizione Versione#

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

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

Corpo:

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

Risposta: {"ok": true}

Ripristina versione dataset#

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

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

Ricostruisce immagini, annotazioni e classi da una versione salvata senza copiare i byte delle immagini.

Corpo:

{
    "version": 2
}

Risposta: {"version": 2, "imageCount": 1000}

Ottieni le statistiche del dataset#

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

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

Restituisce i conteggi delle annotazioni per classe, gli istogrammi di immagini e annotazioni e le mappe termiche. I dataset di grandi dimensioni vengono campionati; in tal caso sampleSize segnala quante immagini hanno contribuito.

Risposta (abbreviata):

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

Gestisci Classi#

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

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

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

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

Elimina le classi (le relative annotazioni vengono eliminate e gli ID delle classi rimanenti scalano verso il basso):

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

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

{
    "classIds": [2, 4]
}

Entrambe le operazioni restituiscono success, il valore aggiornato classNames e classColors, e un riepilogo di ciò che è cambiato (mergedClassIds e targetClassId, oppure deletedClassIds e deletedAnnotations).

Ridistribuisci Split#

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

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

Riassegna casualmente le immagini tra le suddivisioni. Le tre percentuali devono totalizzare 100.

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

Risposta: success, i conteggi risultanti di splits e modified (numero di immagini spostate).

Embedding del Dataset#

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

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

GET restituisce il riepilogo dell'analisi (analyzedAt, embeddingsCount, latestImageAt, activeJob). POST accoda un'analisi degli embedding e restituisce 202 con un jobId. DELETE annulla il processo attivo e restituisce l'ID del processo annullato o null.

Clustering Immagini#

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

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

Restituisce il layout 2D UMAP da un'analisi completata, impaginato con offset e limit (predefinito e max 50.000). Ogni voce include id, umapX, umapY, split, classIds, width, height, bytes, labelCount e missing.

Elenca i modelli addestrati su un dataset#

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

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

Risposta:

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

Elenca le immagini del dataset#

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

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

Parametri di query:

Risposta:

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

Ottieni immagini selezionate#

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

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

Restituisce la stessa forma di immagine per un massimo di 1.000 ID immagine forniti e accetta gli stessi parametri di filtro e di query URL dell'operazione di elenco.

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

Ingestion di dati nel dataset#

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

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

Elabora un caricamento completato, un archivio remoto o una fonte di archiviazione connessa in un dataset esistente. Fornisci esattamente una fonte:

Le sessioni di caricamento sono vincolate a un dataset dal assetId passato a POST /api/upload/signed-url, e l'ingestion rifiuta una sessione che appartiene a un dataset diverso.

Corpo (archivio caricato):

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

Corpo (archivio remoto o NDJSON):

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

Corpo (importazione di etichette in un'ingestion successiva):

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

Corpo (associazione di metadati per immagine):

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

Le chiavi dei metadati devono corrispondere al percorso normalizzato all'interno dell'archivio, incluse le cartelle. Per le importazioni NDJSON, ogni record può trasportare il proprio oggetto metadata, che ha la precedenza su una voce corrispondente di imageMetadata. 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 — così come l'intera mappa imageMetadata — a 500.000 caratteri serializzati.

Risposta (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 delle immagini#

Ispeziona, annota, sposta ed elimina le immagini del dataset tramite il loro ID immagine di 24 caratteri. Consulta la documentazione delle annotazioni.

Ottieni immagine#

GET /api/images/{imageId}

Python SDK: client.images.retrieve(image_id)

Restituisce metadata (personalizzato, definito dall'utente), properties (nome file, hash, dimensioni, suddivisione, conteggi, timestamp), labels e classNames del dataset.

Aggiorna immagine#

PATCH /api/images/{imageId}

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

Sostituisce o le annotazioni o i metadati personalizzati: invia una delle due forme, non entrambe.

Corpo (annotazioni):

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

Corpo (metadati):

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

Elimina Immagine#

DELETE /api/images/{imageId}

Python SDK: client.images.delete(image_id)

Elimina permanentemente un'immagine e le relative annotazioni.

Annota automaticamente l'immagine#

POST /api/images/{imageId}/predict

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

Esegue l'inferenza YOLO sull'immagine e restituisce le annotazioni previste. Non le salva: riscrivi i risultati con PATCH /api/images/{imageId} quando sei soddisfatto.

Risposta: success, predictions (oggetti di annotazione), modelUsed e inferenceTime. Un modello le cui classi non corrispondono al dataset restituisce 422.

Sposta immagini in blocco#

PATCH /api/images/bulk

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

Sposta fino a 1.000 immagini da un dataset a una suddivisione diversa.

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

I conflitti di nome file o di contenuto restituiscono 409 finché non scegli un conflictPolicy valido per l'intero gruppo tra skip, keep_both o replace. La risposta riporta modifiedCount, skippedCount e targetSplit.

Elimina immagini in blocco#

DELETE /api/images/bulk

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

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

Elimina fino a 1.000 immagini da un singolo dataset e restituisce deletedCount e deletedImageIds.

Ottieni URL Firmati delle Immagini#

POST /api/images/urls

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

Restituisce URL firmati temporanei per un massimo di 100 ID immagine da un singolo dataset.

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

Risposta: urls e thumbnails, entrambi indicizzati per ID immagine.

API dei Progetti#

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

Elenca Progetti#

GET /api/projects/{owner}

Python SDK: client.projects.list(owner)

Parametri di query:

Ottieni Progetto#

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

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

Restituisce l'oggetto project, un array models di riepiloghi per modello (stato, metriche, epoche, pesi, argomenti di addestramento) e isOwner.

Crea Progetto#

POST /api/projects

Python SDK: 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

Risposta (201): id, owner, project, region.

Aggiorna Progetto#

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

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

Campi accettati: name, description, visibility, metadata, tags, license, archived, iconColor, iconLetter, viewPreferences e starred.

{
    "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 e di 500.000 caratteri per l'oggetto serializzato dei metadati del dataset.

Elimina Progetto#

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

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

Sposta il progetto e i suoi modelli nel cestino, restituendo cascadedModels.

Clona Progetto#

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

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

Clona un progetto accessibile e i suoi modelli completati. Il corpo facoltativo accetta project, name, description, visibility, license e un owner di destinazione.

API Modelli#

Gestisci i modelli YOLO addestrati: visualizza le metriche, scarica i pesi, esegui l'inferenza e monitora l'addestramento. Consulta la documentazione dei modelli.

Elenca i modelli in un progetto#

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

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

Parametri di query:

Ottieni Modello#

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

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

Parametri di query:

La risposta predefinita contiene l'oggetto model (stato, attività, metriche, trainArgs, trainResults, classNames, computeCost, metadata e altro ancora) più isOwner.

Crea Modello#

POST /api/models

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

Crea un record di modello non addestrato a cui puoi associare i pesi o che puoi addestrare.

Risposta (201): id, owner, project, model, region.

Aggiorna Modello#

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

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

I campi accettati includono name, description, color, metadata, status, license, datasetSlug, trainArgs, trainResults, epochs, bestEpoch, bestFitness, version, trainingError e starred.

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

Il metadata personalizzato è separato dai campi di proprietà dell'addestramento come trainArgs, environment e trainResults, e utilizza gli stessi limiti di dimensione dei metadati del dataset.

Elimina Modello#

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

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

Sposta il modello nel cestino per 30 giorni.

Scarica File Modello#

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

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

Restituisce URL firmati a breve scadenza per i pesi del modello.

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

Clona modello#

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

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

Copia un modello accessibile in un progetto esistente.

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

Esegui l'inferenza#

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

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

I modelli pubblici possono essere utilizzati per l'inferenza senza autenticazione. I modelli privati e condivisi richiedono una API key con accesso al progetto principale.

Modulo Multipart:

Fornisci file o source. I modelli di profondità accettano anche bits (8, 12 o 16) per selezionare la quantizzazione PNG della mappa di profondità. Le richieste che superano i limiti di input del servizio restituiscono 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

Risposta:

Ogni voce in images contiene shape, speed, results e, per i task di predizione densa, un payload PNG semantic_mask o depth (i valori di profondità sono pixel × max / divisor, con divisore 255 per la mappa predefinita a 8 bit e 65535 quando bits è 12 o 16). L'oggetto metadata riporta il conteggio delle immagini, i tempi delle funzioni, il task e le versioni del servizio. I percorsi interni del modello non vengono mai restituiti.

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

Controlla l'avanzamento dell'addestramento#

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

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

Restituisce job, contenente stato, avanzamento delle epoche, tempistiche, dettagli di calcolo, argomenti di addestramento, metriche delle epoche e dettagli di errore sicuri, oppure null se il modello non è mai stato addestrato. I modelli nei progetti pubblici sono leggibili senza autenticazione.

Annulla Addestramento#

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

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

Termina l'istanza di calcolo in esecuzione e contrassegna il processo come annullato. Restituisce 409 quando l'addestramento non è più attivo.

API di Addestramento#

Avvia l'addestramento YOLO su GPU cloud e monitora l'avanzamento in tempo reale. Vedi la documentazione sul Cloud Training.

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

Ottieni disponibilità GPU#

GET /api/training/gpu-availability

Python SDK: client.training.gpu_availability()

Restituisce lo stato attuale delle scorte indicizzato per ID GPU. Pubblico e non autenticato; passa managed=true per includere la capacità di addestramento gestito, che richiede una API key.

Avvia Addestramento#

POST /api/training/start

Python SDK: 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

Risposta:

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

L'addestramento restituisce 402 quando il saldo dei crediti è troppo basso e 503 quando non è disponibile capacità per la GPU richiesta.

API di esportazione#

Converti i modelli in formati ottimizzati come ONNX, TensorRT, CoreML e LiteRT per il deployment edge. Vedi la documentazione sul deployment.

Elenco esportazioni#

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

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

Parametri di query:

Crea esportazione#

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

Python SDK: 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

Risposta (201): id, format, status (queued o running), gpuType, region. Un'esportazione equivalente già in corso restituisce 409.

Formati supportati:

Usa l'argomento format dalla tabella di esportazione condivisa sottostante. PyTorch è il formato di origine e non è un target di esportazione delle API.

Ottieni stato esportazione#

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

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

Restituisce l'oggetto export con status, format, args, gpuType, i timestamp e — una volta completato — un oggetto file contenente size, downloadUrl e downloadFilename.

Annulla o elimina l'esportazione#

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

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

Annulla un'esportazione attiva o elimina una completata e il relativo file. La risposta riporta l'azione eseguita:

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

API Deployments#

Effettua il deployment dei modelli su endpoint di inferenza dedicati con controlli di integrità e monitoraggio. Vedi la documentazione sugli endpoint.

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

Elenco Deployments#

GET /api/deployments/{owner}

Python SDK: client.deployments.list(owner)

Parametri di query:

I chiamanti anonimi devono filtrare per un singolo modello pubblico; elencare un intero workspace richiede l'autenticazione.

Crea Deployment#

POST /api/deployments/{owner}

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

Corpo:

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

Risposta (201): id, deployment, status (creating), message e region.

Ottieni Deployment#

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

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

Restituisce l'oggetto deployment con status, statusMessage, region, serviceUrl e resources.

Avvia, arresta o sostituisci un deployment#

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

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

Un singolo campo action seleziona l'operazione:

{ "action": "start" }

La sostituzione rilascia una nuova revisione preservando l'ID del deployment, la regione e l'URL dell'endpoint; la revisione esistente rimane attiva se il rilascio fallisce. Il modello sostitutivo deve essere un modello completato con pesi a cui la tua chiave può accedere. Le operazioni completate restituiscono 200 con status ready o stopped; le operazioni ancora in fase di rilascio restituiscono 202 con deploying o stopping.

Elimina Deployment#

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

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

Rimuove permanentemente l'endpoint di inferenza.

Controllo Integrità#

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

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

Esegue il ping e riscalda l'endpoint, restituendo healthy, latencyMs e il codice upstream status.

Esegui l'inferenza su un deployment#

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

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

Invia un'immagine o un video attraverso l'endpoint dedicato. I contratti di richiesta e risposta corrispondono all'inferenza del modello.

Modulo Multipart:

Ottieni Metriche#

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

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

Parametri di query:

La risposta completa contiene summary (totale richieste, tasso di errore, latenza media e p50/p95/p99) e timeSeries (richieste, errori, latenza, CPU, memoria, conteggio istanze). La risposta sparkline restituisce requests24h, totalRequests, errorRate e avgLatencyMs.

Ottieni Log#

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

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

Parametri di query:

API cestino#

Visualizza, ripristina ed elimina permanentemente progetti, dataset e modelli eliminati logicamente. Gli elementi vengono svuotati automaticamente dopo 30 giorni. Vedi la documentazione sul Cestino.

Elenco cestino#

GET /api/trash

Python SDK: client.lifecycle.trash()

Parametri di query:

La risposta include items (ciascuno con daysRemaining), total, page, limit, totalPages e un summary con i totali per tipo.

Ripristina elemento#

POST /api/trash

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

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

Il ripristino di un progetto ripristina anche i modelli che sono stati cestinati insieme ad esso, segnalati come restoredModels.

Elimina permanentemente#

DELETE /api/trash

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

Elimina un elemento:

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

Oppure svuota l'intero cestino:

{
    "all": true
}

La risposta riporta deletedCount, oltre a cascadedModels e survivingDeployments dove rilevante.

API di caricamento#

Carica i file direttamente sullo storage cloud utilizzando URL firmati. Il completamento del caricamento di un modello ne collega i pesi; il completamento del caricamento di un archivio di dataset registra la sessione, che passi poi all'ingestion del dataset. Vedi la documentazione sui Dati.

Ottieni URL di caricamento firmato#

POST /api/upload/signed-url

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

Corpo:

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

Risposta:

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

Carica il file con una richiesta PUT su uploadUrl, utilizzando lo stesso Content-Type che hai dichiarato.

Completa il caricamento#

POST /api/upload/complete

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

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

Risposta: success e un oggetto file con size e contentType. Per i modelli questo collega i pesi; per gli archivi di dataset, chiama subito ingest per avviare l'elaborazione.

API di integrazione dello storage#

Collega account Google Cloud Storage, Amazon S3 o Azure Blob Storage di sola lettura e sfollali come origini di dataset. Vedi la documentazione sulle Integrazioni.

Elenca le integrazioni#

GET /api/integrations/buckets

Python SDK: client.storage_integrations.list()

Restituisce integrations, ciascuno con id, provider, credentialIdentity, targets e createdAt. Le credenziali non vengono mai restituite.

Scopri le posizioni#

POST /api/integrations/buckets/discover

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

Elenca i bucket o i container leggibili con le credenziali fornite, senza salvarli.

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

Risposta: {"targets": ["my-bucket", "another-bucket"]}

Collega lo storage#

POST /api/integrations/buckets

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

Stesse forme di credenziali della discovery, più un array obbligatorio targets di 1-50 nomi di bucket o container. Restituisce 201 con l'integrazione memorizzata. Le credenziali temporanee S3 (chiavi di accesso ASIA) vengono rifiutate.

Esplora gli oggetti#

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

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

Parametri di query:

Restituisce entries (ciascun kind è folder o file) e un cursor facoltativo per la pagina successiva.

Disconnetti lo storage#

DELETE /api/integrations/buckets/{id}

Python SDK: client.storage_integrations.delete(id)

Rimuove le credenziali salvate senza eliminare i dati del provider. I dataset connessi rimangono visibili, ma i loro file restano non disponibili finché lo stesso account di storage non viene ricollegato. Richiede l'accesso come amministratore del workspace.

API di importazione dei dataset#

Importa dataset da servizi di terze parti. Vedi l'integrazione con Roboflow.

Visualizza in anteprima un'importazione da Roboflow#

POST /api/integrations/roboflow/preview

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

Converte una chiave API di Roboflow in un piano di importazione: dettagli del workspace, newDatasets che verrebbero importati, conteggi di progetti saltati, non supportati e non risolti, bytesTotal e il tuo storage margine disponibile. La chiave API di Roboflow viene letta dal corpo della richiesta e non viene salvata.

{
    "apiKey": "ROBOFLOW_API_KEY"
}

Importa da Roboflow#

POST /api/integrations/roboflow/import

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

Accoda processi di inserimento per un massimo di 500 versioni di progetti Roboflow selezionate, utilizzando gli elementi restituiti dall'anteprima.

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

Risposta (201): array imported, failed e skipped. Le importazioni richiedono spazio di archiviazione disponibile e ciascun dataset deve rispettare il limite di dimensione per importazione del tuo piano.

API Account#

Ispeziona il tuo account Platform, le chiavi, lo spazio di archiviazione e i profili pubblici. Consulta la documentazione sulle impostazioni.

Riepilogo account#

GET /api/account/summary

Python SDK: client.account.summary()

Restituisce il piano, il saldo dei crediti e i conteggi delle risorse per il workspace che ha generato la chiave.

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

Elenca le chiavi API#

GET /api/api-keys

Python SDK: client.account.api_keys()

Restituisce keys con keyId, name, keyPrefix e createdAt per il workspace della chiave. Le richieste autenticate tramite chiave API ricevono solo metadati; i valori completi delle chiavi vengono mostrati al proprietario del workspace in Impostazioni > Chiavi API nell'interfaccia utente di Platform, che è anche il luogo in cui le chiavi vengono create e revocate.

Controlla l'utilizzo dello spazio di archiviazione#

GET /api/storage

Python SDK: client.account.storage()

Parametri di query:

Risposta:

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

Ottieni un profilo utente pubblico#

GET /api/users

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

Parametri di query:

Restituisce il profilo pubblico user con followerCount e, per i chiamanti autenticati, isFollowed.

Segui o smetti di seguire un utente#

PATCH /api/users

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

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

Risposta: followed e il followerCount aggiornato.

API di fatturazione#

Controlla l'utilizzo del piano e il tuo registro dei crediti. Consulta la documentazione sulla fatturazione.

Visualizza piano e utilizzo#

GET /api/billing/usage-summary

Python SDK: client.billing.usage_summary()

Restituisce plan (ID, stato, ciclo di fatturazione, fine del periodo), metrics (limite di archiviazione e utilizzo), trainingCredit, features, creditsCents e il numero di postazioni.

Visualizza transazioni#

GET /api/billing/transactions

Python SDK: client.billing.transactions()

Parametri di query:

Ogni transazione include id, type (come purchase, training, monthly_grant o refund), amountCents, balanceAfter, createdAt, un receiptUrl opzionale e il contesto del modello per i costi di training. I dettagli interni di fatturazione non vengono mai restituiti.

API di esplorazione#

Cerca progetti pubblici e dataset condivisi dalla community. Consulta la documentazione di Esplora.

Cerca contenuti pubblici#

GET /api/explore/search

Python SDK: client.explore.search()

Parametri di query:

Risposta: projects, datasets e hasMore.

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

Python SDK#

ultralytics-platform è un client Python tipizzato generato dal contratto OpenAPI, con un metodo per endpoint (client.datasets.list, client.models.predict, client.exports.create, ...). Ogni metodo accetta i parametri di percorso in modo posizionale, gli altri input come argomenti chiave-valore e timeout e extra_headers opzionali per richiesta.

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

from ultralytics_platform import Platform

with Platform() as client:  # reads ULTRALYTICS_API_KEY
    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 espone lo stesso albero di risorse per il codice async/await, le risposte senza successo sollevano APIError con status_code, body e json analizzato, e i guasti di connessione sollevano APIConnectionError. Consulta il repository dell'SDK per il README completo.

Integrazione Python#

Per i flussi di lavoro di addestramento e inferenza, usa il pacchetto Python di Ultralytics, che gestisce automaticamente l'autenticazione, i caricamenti e lo streaming delle metriche in tempo reale.

Installazione e configurazione#

pip install "ultralytics>=8.4.120"

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#