Documentazione di riferimento REST API#

Ultralytics Platform offre una REST API per accedere in modo programmatico a dataset, immagini, progetti, modelli, addestramento, 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 dell'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 — lettura di un dataset, progetto o modello pubblico, elenco di immagini di dataset pubblici, esecuzione dell'inferenza su un modello pubblico o ricerca in Explore — accettano anche richieste anonime e restituiscono semplicemente più risultati quando viene fornita una chiave.

Ottieni una chiave API#

1. Vai a Settings > API Keys
2. Fai clic su Add Key, mantieni Ultralytics come provider, inserisci un nome e fai clic su Create Key
3. Copia la chiave generata

Consulta Chiavi API per istruzioni dettagliate.

Intestazione di autorizzazione#

Includi la tua chiave API come token bearer:

Authorization: Bearer YOUR_API_KEY

Esempio#

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

URL di base#

Tutti gli endpoint API utilizzano:

https://platform.ultralytics.com/api

Percorsi delle risorse#

La maggior parte delle risorse viene identificata usando gli stessi nomi leggibili che compaiono negli URL della Platform, non tramite ID di database:

• {owner} è un nome utente personale o un identificativo di area di lavoro del team: 4-32 caratteri, alfanumerici minuscoli con trattini singoli tra i segmenti.
• {dataset}, {project}, {model} e {deployment} seguono lo stesso formato con lettere minuscole e trattini, fino a 128 caratteri.
• {imageId}, {exportId} e {agentId} sono ID esadecimali di 24 caratteri restituiti dall'API.
• Rinominando una risorsa tramite PATCH aggiorni contemporaneamente il name visualizzato e il nome nell'URL; la risposta restituisce il nome corrente nell'URL così puoi continuare a seguirlo.

Limiti di frequenza#

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

Le route della Platform accessibili solo dal browser, come il checkout dei pagamenti e la gestione dei team, hanno limiti specifici che non si applicano al traffico con chiave API.

Quando viene applicato un limite, l'API restituisce 429 sia negli header sia nel corpo JSON:

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

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

Endpoint dedicati (illimitati)#

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

Formato della risposta#

Risposte positive#

Le risposte sono oggetti JSON con campi specifici per la risorsa. Non esiste un involucro generico: gli endpoint di elenco restituiscono una raccolta con un nome, spesso insieme ai conteggi, mentre le operazioni di modifica restituiscono gli identificatori modificati.

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

Anche gli elenchi di risorse, le risposte di creazione e clonazione e alcune letture, come deployment, archiviazione e cestino, includono region (us, eu o ap), la regione di archiviazione per quell'area di lavoro.

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 raccolta:

API dei dataset#

Crea, esplora e gestisci dataset di immagini etichettate per addestrare modelli YOLO. Consulta la documentazione sui dataset.

Elenca i dataset#

GET /api/datasets/{owner}

Python SDK: client.datasets.list(owner)

Restituisce i dataset pubblici del proprietario e i dataset privati quando la tua chiave può accedere a quell'area di lavoro.

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'intero oggetto dataset sotto una chiave dataset, inclusi classNames, splits, versions, source e l'oggetto metadata definito dall'utente. Durante l'elaborazione dell'importazione di almeno 10.000 immagini, anche gli editor ricevono processingProgress con stage, percent e, se noti, processed, total e objects (oggetti cloud analizzati).

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

Uno slug dataset già esistente nell'area di lavoro, anche se si trova nel cestino, restituisce 409.

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, starred, blurFaces, kptSkeletonId (assegna un modello di scheletro di posa a un dataset di pose) e initializeClassNames (l'aggiornamento restituisce 409, a meno che il dataset non abbia ancora classi o annotazioni). Invia un oggetto metadata vuoto ({}) per cancellare i metadati personalizzati. Le chiavi dei metadati possono contenere al massimo 128 caratteri e l'oggetto serializzato al massimo 500.000 caratteri.

Risposta:

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

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

Eliminare un dataset#

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

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

Sposta il dataset nel cestino, dove può essere recuperato per 30 giorni.

Clonare un dataset#

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

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

Copia un dataset accessibile, con le relative immagini ed etichette, nella tua area di lavoro personale o in un'area di lavoro del team.

Corpo facoltativo (tutti i campi sono facoltativi):

{
    "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 basati su una sorgente di archiviazione connessa restituiscono 409, perché i relativi file non vengono copiati.

Scarica un'esportazione del dataset#

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

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

Restituisce un URL firmato per il download in formato NDJSON. Ometti v per esportare lo stato corrente del dataset, riutilizzando l'esportazione memorizzata nella cache se non è cambiato nulla dalla sua generazione.

Parametri di query:

Risposta:

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

Se richiedi una versione specifica, vengono restituiti downloadUrl e version invece di cached.

Crea versione del dataset#

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

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

Crea una versione numerata e immutabile del dataset. Richiede l'accesso come editor. Imposta download su false per salvare la versione senza preparare un download NDJSON; in tal caso, downloadUrl viene omesso. L'SDK accetta download da ultralytics-platform>=0.1.73.

Corpo (facoltativo):

{
    "description": "Added 500 training images",
    "download": true
}

Risposta:

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

reused è true quando il dataset corrisponde a una versione esistente, ad esempio subito dopo il ripristino; viene restituita quella versione e, se ne invii una, la relativa descrizione viene aggiornata.

Aggiorna la descrizione della 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 del dataset#

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

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

Ricrea immagini, annotazioni e classi da una versione salvata senza copiare i dati delle immagini.

Corpo:

{
    "version": 2
}

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

Confronta versioni del dataset#

GET /api/datasets/{owner}/{dataset}/versions/compare?base={from}&head={to}

SDK Python: client.datasets.compare(owner, dataset, base=1, head=2) (ultralytics-platform>=0.1.73)

Risposta (ridotta):

{
    "summary": { "added": 0, "removed": 1, "modified": 1, "moved": 1, "labelsAdded": 1, "labelsRemoved": 2 },
    "items": [
        {
            "hash": "b5c605c133f84c3024af7e652b135501",
            "name": "000000000042",
            "change": "moved",
            "base": { "split": "val", "labelCount": 1 },
            "head": { "split": "test", "labelCount": 1 }
        }
    ]
}

summary compare solo nella prima pagina e contiene i totali esatti, oltre a un header che elenca le classi aggiunte, rimosse o rinominate e gli altri campi del dataset che presentano differenze. change di ciascun elemento è added, removed, modified (con il fields modificato) oppure moved (split modificato), mentre labelsRemoved include le etichette delle immagini rimosse. Se presente, passa nextCursor come cursor per la pagina successiva. Con hash, la risposta è versions: l'immagine così come è archiviata in ciascuna versione, con le relative etichette e un imageUrl firmato. È possibile usare entrambi gli ordini; invertendo base e head, un'immagine rimossa viene segnalata come aggiunta. I confronti usano il limite di frequenza predefinito e le richieste senza hash sono inoltre limitate a 10 al minuto per utente e dataset, indipendentemente dalla chiave API utilizzata.

Ottieni 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 di calore. I dataset di grandi dimensioni vengono campionati; in questo caso, sampleSize indica 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 le 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 diminuiscono):

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, i valori aggiornati classNames e classColors e un riepilogo delle modifiche apportate (mergedClassIds e targetClassId, oppure deletedClassIds e deletedAnnotations).

Rid ridistribuisci le suddivisioni#

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

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

Riassegna casualmente le immagini alle 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

SDK Python: 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 mette in coda un' analisi degli embedding e restituisce 202 con un jobId. DELETE annulla il processo attivo e restituisce l'ID del processo annullato o null.

Raggruppamento delle immagini#

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

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

Restituisce la proiezione UMAP 2D di un'analisi completata, suddivisa in pagine con offset e limit (valore predefinito e massimo 50.000). Ogni voce contiene id, umapX, umapY, cluster, split, classIds, width, height, bytes, labelCount, labeled e missing. cluster indica l'isola visiva del punto, classificata per dimensione (0 = più grande, -1 = dispersa), oppure null per le proiezioni analizzate prima dell'introduzione del raggruppamento.

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",
            "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 le immagini selezionate#

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

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

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

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

Copia o sposta immagini#

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

SDK Python: client.datasets.adopt_images(owner, dataset, image_ids=..., release=...) (ultralytics-platform>=0.1.50)

Copia fino a 1.000 immagini da altri dataset in questo dataset, come fa la funzione dell'app copia e incolla, e restituisce il numero adopted.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"],
    "release": false,
    "classMapping": { "person": 0, "vase": null }
}

Impostando release o classMapping si mantengono le etichette e le suddivisioni dei dataset che puoi modificare: release: false copia le immagini e release: true le sposta fuori dal dataset di origine. Se ometti entrambi i campi, vengono importate immagini train senza etichette, come avviene copiando da una sorgente di sola lettura; lo spostamento da una sorgente di sola lettura restituisce 403. Le immagini esistenti vengono ignorate; se si mantengono etichette e suddivisioni, i duplicati vengono verificati all'interno della suddivisione di destinazione. Le classi vengono abbinate per nome, senza distinzione tra maiuscole e minuscole per i nomi di più di due caratteri; 422 restituisce le classi di origine che non trovano corrispondenza in unmatchedClasses, mentre classMapping associa ognuna a un indice di classe, a un nuovo nome di classe oppure a null per eliminarne le etichette. 409 indica che la destinazione è un dataset collegato o che una sorgente o destinazione è occupata. Se si mantengono etichette e suddivisioni, attività, canali immagine, impostazioni della posa o scale di profondità incompatibili restituiscono anch'essi 409, anche per immagini senza etichette.

Acquisisci i dati del dataset#

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

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

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

Le sessioni di caricamento sono associate a un dataset tramite assetId passato a POST /api/upload/signed-url; l'acquisizione rifiuta una sessione appartenente 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'acquisizione 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ò includere un proprio oggetto metadata, che ha la precedenza su una voce imageMetadata corrispondente. I percorsi dell'archivio 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 (optional)"]:::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()

headers_put = {"Content-Type": "application/zip", **upload.get("headers", {})}
requests.put(upload["uploadUrl"], headers=headers_put, 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#

Esamina, annota, sposta ed elimina le immagini del dataset usando il relativo ID immagine di 24 caratteri. Consulta la documentazione sulle annotazioni.

Ottieni immagine#

GET /api/images/{imageId}

Python SDK: client.images.retrieve(image_id)

Restituisce l'oggetto 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 le annotazioni oppure i metadati personalizzati: invia una sola delle due strutture, 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 definitivamente un'immagine e le relative annotazioni.

Annota automaticamente un'immagine#

POST /api/images/{imageId}/predict

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

Esegue il modello sull'immagine e restituisce le annotazioni previste. Non le salva: quando il risultato ti soddisfa, scrivilo di nuovo con PATCH /api/images/{imageId}.

Risposta: success, predictions (oggetti di annotazione), confidences (punteggi allineati agli indici, vuoto per i modelli con prompt di classe), modelUsed, inferenceTime; per i modelli con prompt di classe, partial (true quando l'output troncato di un modello generativo ha restituito solo le bounding box complete); per i modelli di provider a pagamento, un eventuale cost (costo stimato del provider in USD addebitato alla tua chiave del provider, omesso quando non è disponibile una stima). Un modello YOLO con classi non corrispondenti al dataset restituisce 422, così come un modello con prompt di classe usato su un dataset non di rilevamento o con un numero di classi fuori dall'intervallo 1–200; anche un modello di provider a pagamento senza una chiave del provider salvata in Impostazioni > Chiavi API dell'area di lavoro del dataset restituisce code: missing_provider_api_key. Un errore del provider include il messaggio del provider: 422 quando il provider risponde con 400, 401, 403 o 404 (chiave, modello o richiesta rifiutati), 429 per il limite di frequenza e 503 per qualsiasi altro errore del provider. I dataset di profondità restituiscono 400; i dataset su archiviazione connessa o con più di 3 canali immagine restituiscono 409.

Trova immagini simili#

GET /api/images/{imageId}/similar

Python SDK: client.images.find_similar_images(image_id)

Restituisce fino a 24 images visivamente simili provenienti da dataset pubblici e dai tuoi dataset personali e di team, ognuna con score (0-1), un thumbnailUrl firmato e il dataset di origine (owner, dataset, license). Le immagini già presenti nel dataset di origine e le copie dell'immagine di query sono escluse. È necessaria una chiave API con accesso di visualizzazione all'immagine; se un'immagine non è ancora stata incorporata, viene prima elaborata per generare l'embedding; 503 indica che la preparazione non è riuscita, quindi riprova.

Annota automaticamente un dataset#

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

SDK Python: client.datasets.create_batch(owner, dataset, body={...}) (ultralytics-platform>=0.1.57)

Salva una versione del dataset, quindi mette in coda un'esecuzione che etichetta con il modello le immagini senza etichetta del dataset e restituisce 202. Il corpo accetta gli stessi campi modelId, confidence, iou e classMapping dell'endpoint per una singola immagine, oltre a includeAnnotated (predefinito false) per annotare anche le immagini già etichettate. Un modello con prompt di classe rileva le classi del dataset senza punteggi di confidenza; un modello di provider a pagamento richiede una chiave del provider salvata nell'area di lavoro del dataset, in Impostazioni > Chiavi API (422, code: missing_provider_api_key, prima dell'ammissione dell'esecuzione). Le etichette esistenti non vengono mai modificate e l'esecuzione viene fatturata per le immagini effettivamente elaborate. 402 indica che il saldo non copre la stima; 409 indica che il dataset non è pronto, non ha più immagini da annotare o ha già un'esecuzione in corso; 422 indica che il dataset non ha classi oppure che un modello con prompt di classe è stato usato su un dataset non di rilevamento o con un numero di classi fuori dall'intervallo 1–200: crea le classi con l' endpoint delle classi prima di chiamare questo endpoint, come fa il passaggio Mappa classi dell'app prima di avviare un'esecuzione.

GET sullo stesso percorso (client.datasets.batch(owner, dataset)) restituisce l'esecuzione in corso e il relativo avanzamento oppure l'ultima esecuzione completata finché non viene chiusa; i relativi results includono partialImages se l'esecuzione del modello generativo ha conservato solo le bounding box complete dell'output troncato. DELETE (client.datasets.delete_batch(owner, dataset)) annulla un'esecuzione in corso oppure regola la fatturazione e chiude il riepilogo dell'esecuzione completata.

Lo stesso endpoint sfoca i volti con "operation": "blur", confidence (predefinito 0.25) e boxScale (0.5–1.5, predefinito 1); imageId limita l'esecuzione a una sola immagine. Non crea versioni e non modifica mai le etichette. Invia "preview": true per elaborare fino a sei immagini senza modificarle, quindi invia il valore restituito jobId come previewJobId con le stesse impostazioni per applicare le modifiche; un'anteprima già applicata non può essere riutilizzata e restituisce 409. Mentre un'anteprima è in attesa, passa il relativo ID come previewJobId a DELETE per eliminarla.

{ "operation": "blur", "confidence": 0.25, "boxScale": 1, "preview": true }

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 relativi al nome file o al 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 temporanei firmati per un massimo di 100 ID immagine di un singolo dataset.

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

Risposta: urls, thumbnails e depths (anteprime del target di profondità per immagini di profondità appaiate), tutti associati all'ID immagine.

API dei progetti#

Organizza i tuoi modelli in progetti. Ogni modello appartiene a un progetto. Consulta la documentazione sui progetti.

Elenca i 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. Passa search (massimo 200 caratteri) per filtrare models in base al nome del modello o ai metadati.

Crea un 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.

Uno slug project già esistente nell'area di lavoro, anche se si trova nel cestino, restituisce 409.

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 usano gli stessi limiti di 128 caratteri per la chiave e 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 relativi modelli nel cestino, restituendo cascadedModels, ed elimina definitivamente le relative distribuzioni. Il ripristino del progetto non ripristina le distribuzioni. 502 indica che la pulizia delle distribuzioni non è stata completata; i modelli restano nel Cestino finché l'operazione non riesce.

Clona progetto#

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

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

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

API dei modelli#

Gestisci i modelli YOLO addestrati: visualizza le metriche, scarica i pesi, esegui inferenze e monitora l'addestramento. Consulta la documentazione sui 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, oltre a 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. Passando solo projectId, il modello viene spostato in un altro progetto dello stesso proprietario; la risposta restituisce slug del modello nella destinazione, renamed: true se lo slug è già occupato in quella destinazione e 409 mentre il modello è ancora in addestramento.

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

metadata personalizzato è separato dai campi gestiti dall'addestramento, come trainArgs, environment e trainResults, e usa gli stessi limiti di dimensione dei metadati del dataset.

Elimina il modello#

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

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

Sposta il modello nel cestino per 30 giorni ed elimina definitivamente tutte le distribuzioni che lo utilizzano, comprese quelle sostitutive in attesa. Il ripristino del modello non ripristina le distribuzioni.

Scarica i file del modello#

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

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

Restituisce URL firmati e di breve durata per i pesi del modello.

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

Trova immagini simili alle peggiori immagini di convalida#

GET /api/models/{owner}/{project}/{model}/similar-images

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

Restituisce fino a 100 images, nello stesso formato di Trova immagini simili, che assomigliano alle immagini di convalida su cui questa esecuzione di addestramento ha ottenuto i risultati peggiori, escludendo le immagini già presenti nel dataset di addestramento. Passa hashes (separati da virgole, fino a 100) per effettuare la ricerca partendo da un sottoinsieme delle immagini peggiori. È necessaria una chiave API con accesso all'area di lavoro del modello. L'elenco è vuoto se l'esecuzione non ha registrato risultati per immagine; inoltre, 404 indica che le immagini peggiori non sono ancora incorporate: esegui prima gli embedding del dataset sul dataset di addestramento.

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=...)

È possibile eseguire previsioni con i modelli pubblici senza autenticazione. Per i modelli privati e condivisi è necessaria una chiave API con accesso al progetto principale.

Modulo multipart:

Fornisci file oppure 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 elemento in images contiene shape, speed, results e, per le attività 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 numero di immagini, i nomi delle classi del modello, i tempi di esecuzione delle funzioni, l'attività e le versioni del servizio. I percorsi interni dei modelli 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,
        "classNames": ["person", "forklift"],
        "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, che contiene lo stato, l'avanzamento delle epoche, i tempi, i dettagli di calcolo, gli argomenti di addestramento, le metriche delle epoche e i dettagli sicuri degli errori, oppure null se il modello non è mai stato addestrato. I modelli nei progetti pubblici sono accessibili 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. Consulta la documentazione sull'addestramento cloud.

graph LR
    A[POST /api/training/start]:::start --> B[Job Created]:::proc
    B --> C{Training}:::decide
    C -->|progress| D[GET .../training]:::proc
    C -->|cancel| E[DELETE .../training]:::error
    C -->|complete| F[Model Ready]:::out
    F --> G[Deploy or Export]:::proc

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef decide fill:#FF9800,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff

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 richiede autenticazione; passa managed=true per includere la capacità di addestramento gestita, che richiede una chiave API.

Avvia l'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 se il saldo dei crediti è insufficiente e 503 se non è disponibile capacità per la GPU richiesta.

API delle esportazioni#

Converti i modelli in formati ottimizzati come ONNX, TensorRT, CoreML e LiteRT per la distribuzione su dispositivi edge. Consulta la documentazione sulla distribuzione.

Elenca 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

Ogni formato supporta solo le opzioni indicate nella colonna Argomenti della tabella di esportazione qui sotto: se si specifica un valore diverso da quello predefinito per batch, dynamic, opset, simplify, workspace o optimize per un formato che non lo supporta, viene restituito 400. Le esportazioni imx sono solo INT8 e disponibili per i modelli di rilevamento, segmentazione, classificazione e posa; i modelli YOLO26 e le dimensioni diverse da nano per YOLOv8 o YOLO11 restituiscono 400.

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

Formati supportati:

Usa l'argomento format della tabella di esportazione condivisa qui sotto. PyTorch è il formato di origine e non è un formato di destinazione per l'esportazione tramite API.

nms=None restituisce per impostazione predefinita output grezzi per NMS esterno. Imposta nms=False per selezionare una head disponibile senza NMS; i formati non supportati utilizzano il proprio percorso di output nativo. Le voci nms qui sopra identificano i formati che possono integrare NMS con nms=True.

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 (solo TensorRT), le marche temporali e, una volta completata, un oggetto file contenente size, downloadUrl e downloadFilename.

Annulla o elimina esportazione#

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

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

Annulla un'esportazione attiva oppure elimina un'esportazione completata e il relativo file. La risposta indica quale operazione è stata eseguita:

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

API delle distribuzioni#

Distribuisci i modelli su endpoint di inferenza dedicati, con controlli dello stato di salute e monitoraggio. Consulta 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

Elenca distribuzioni#

GET /api/deployments/{owner}

Python SDK: client.deployments.list(owner)

Parametri di query:

Chi effettua richieste in forma anonima deve filtrare per un singolo modello pubblico; per elencare un'intera area di lavoro è necessaria l'autenticazione.

Crea distribuzione#

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

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

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

Restituisce l'oggetto deployment con status, statusMessage, region, serviceUrl, resources e metadata personalizzato, oltre a camera e cameraApplying per il proprietario.

Aggiorna una distribuzione#

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

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

Invia uno dei seguenti corpi:

{ "name": "Edge 1 (primary)" }

La ridenominazione imposta nell'URL il valore deployment su uno slug derivato dal nuovo nome, restituito come deployment; il vecchio percorso restituisce 404 e serviceUrl rimane invariato. Un oggetto metadata vuoto cancella i metadati personalizzati. La sostituzione distribuisce una nuova revisione mantenendo invariati l'ID della distribuzione, la regione e l'URL dell'endpoint; se la distribuzione non riesce, la revisione esistente resta attiva. Il modello sostitutivo deve essere un modello completato con pesi accessibili con la tua chiave. L'azione della telecamera salva una telecamera RTSP o RTSPS su cui un endpoint pronto con risorse personalizzate continua a eseguire l'inferenza (vedi Telecamera in background); "url": null la rimuove, così come il ripristino delle dimensioni predefinite, mentre il salvataggio di una telecamera su un endpoint con dimensioni predefinite restituisce 403. Una modifica della telecamera restituisce 202 con status ready durante l'applicazione: interroga la distribuzione finché cameraApplying non è più true, quindi controlla camera; se la modifica non riesce, la telecamera precedente viene mantenuta e viene impostato statusMessage. Le operazioni completate restituiscono 200 con status ready oppure stopped; le altre operazioni ancora in fase di distribuzione restituiscono 202 con deploying o stopping.

Elimina distribuzione#

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

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

Rimuove definitivamente l'endpoint di inferenza.

Controllo dello stato#

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

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

Invia richieste di ping all'endpoint e lo riscalda, restituendo healthy, latencyMs e il codice upstream status.

Esegui inferenza su una distribuzione#

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

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

Instrada un'immagine o un video attraverso l'endpoint dedicato. I contratti di richiesta e risposta corrispondono a quelli dell'inferenza del modello. I flussi delle telecamere non vengono inoltrati tramite proxy; inviali all'URL dell'endpoint come descritto in Inferenza da telecamera in diretta.

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 delle richieste, tasso di errore, latenza media e p50/p95/p99) e timeSeries (richieste, errori, latenza, CPU, memoria, numero di istanze). La risposta con mini-grafico restituisce requests24h (conteggi orari delle richieste; le ore senza richieste vengono omesse), totalRequests, errorRate e avgLatencyMs (la media delle latenze P95 orarie). Con view=overview, summary contiene totalRequests, errorRate, e p95LatencyMs, mentre timeSeries contiene requests, errors e latencyP95.

Ottieni log#

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

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

Parametri di query:

API degli agenti#

Salva e gestisci i flussi di lavoro degli agenti. L'API memorizza le definizioni degli agenti; le esecuzioni vengono avviate nell'area di lavoro degli agenti, dove https://platform.ultralytics.com/agents?workflow={id} apre un agente salvato. I metodi dell'SDK Python richiedono ultralytics-platform>=0.1.74.

Ogni operazione accetta un parametro di query facoltativo owner con il nome utente di un'area di lavoro a cui appartieni (predefinito: la tua). Per elencare gli elementi serve l'accesso di visualizzazione; per salvare ed eliminare serve l'accesso di modifica.

Elenca agenti#

GET /api/workflows

Python SDK: client.agents.list()

La risposta elenca fino a 100 agenti in workflows, dal più recente aggiornato al meno recente, ciascuno con id, username, name, version, createdAt e updatedAt. Se richiedi un id, viene restituito anche graph dell'agente.

Salva un agente#

PUT /api/workflows

Python SDK: client.agents.save(name=..., graph=..., version=...)

Invia version: 0 per creare un agente. Per aggiornarne uno, invia id e version restituito dall'ultima operazione di elenco o salvataggio; un version non aggiornato restituisce 409, quindi elenca nuovamente l'agente e riprova. Un grafo le cui connessioni formano un ciclo o assegnano a un blocco più di un input restituisce 400.

from ultralytics_platform import Platform

def block(node_id, kind, x, config):
    return {
        "id": node_id,
        "type": "agent",
        "position": {"x": x, "y": 0},
        "data": {"label": kind, "type": kind, "config": config},
    }

graph = {
    "nodes": [
        block("images", "Dataset", 0, {"dataset": "official:coco8", "split": "val", "maxInputs": 2}),
        block("yolo", "YOLO", 220, {"model": "ul://ultralytics/yolo26/yolo26n", "task": "detect"}),
        block("output", "Output", 440, {}),
    ],
    "edges": [{"id": "e1", "source": "images", "target": "yolo"}, {"id": "e2", "source": "yolo", "target": "output"}],
    "templateId": "",
}

with Platform() as client:
    saved = client.agents.save(name="Detect COCO8", graph=graph, version=0)
    print(saved["id"], saved["version"], saved["errors"])

La risposta restituisce id dell'agente, il suo nuovo version e errors: i blocchi che l'area di lavoro segnalerebbe, ad esempio un blocco Dataset senza un dataset selezionato. L'agente viene salvato in ogni caso. Consulta openapi.json per tutti i tipi di blocco e le relative configurazioni.

Elimina un agente#

DELETE /api/workflows?id={id}

Python SDK: client.agents.delete(id=...)

Elimina l'agente e annulla le sue esecuzioni attive. Gli agenti eliminati non compaiono nel Cestino e non possono essere ripristinati.

API del cestino#

Visualizza, ripristina ed elimina definitivamente progetti, dataset e modelli eliminati logicamente. Gli elementi vengono rimossi automaticamente dopo 30 giorni. Consulta la documentazione del cestino.

Elenca 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. Con id, restituisce invece resources: i modelli interessati e le distribuzioni che verrebbero eliminati definitivamente.

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 erano stati spostati nel cestino insieme a esso, indicati come restoredModels.

Elimina definitivamente#

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 e, se pertinenti, cascadedModels e survivingDeployments.

API di caricamento#

Carica i file direttamente nell'archiviazione cloud usando URL firmati. Il completamento del caricamento di un modello collega i relativi pesi; il completamento del caricamento di un archivio di dataset lo verifica e, successivamente, passi la sessione a ingestione del dataset, che completa a sua volta il caricamento se salti questo passaggio. Consulta 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",
    "headers": { "x-goog-if-generation-match": "0" }
}

Carica il file con una richiesta PUT a uploadUrl, usando lo stesso Content-Type dichiarato e tutte le intestazioni restituite in headers. Gli URL di caricamento dei dataset sono validi per 12 ore e consentono solo la creazione: una seconda richiesta PUT allo stesso URL restituisce 412, mentre una richiesta PUT senza le intestazioni restituite restituisce 400.

Completa caricamento#

POST /api/upload/complete

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

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

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

Se viene fornito md5, viene confrontato con l'oggetto memorizzato. In caso di mancata corrispondenza viene restituito 400; per una sessione non ancora completata, il file caricato viene anche eliminato e la sessione rimane incompleta: richiedi quindi un nuovo URL firmato e carica nuovamente il file. Una sessione di dataset completata può essere completata di nuovo finché l'archivio esiste, ma i completamenti concorrenti con hash diversi restituiscono 409; le sessioni dei modelli vengono eliminate al completamento. checksum viene memorizzato come metadato del file del modello e non viene verificato.

API delle integrazioni di archiviazione#

Collega account Google Cloud Storage, Amazon S3 o Azure Blob Storage in sola lettura e sfogliali come origini di dataset. Consulta la documentazione sulle integrazioni.

Per individuare e collegare l'archiviazione serve l'accesso di amministratore dell'area di lavoro e un piano Pro o Enterprise (403 altrimenti); per elencare le integrazioni e sfogliare gli oggetti serve l'accesso di modifica.

Elenca 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.

Individua posizioni#

POST /api/integrations/buckets/discover

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

Elenca i bucket o i container accessibili con le credenziali fornite, senza salvarle.

{
    "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 archiviazione#

POST /api/integrations/buckets

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

Gli stessi formati delle credenziali usati per l'individuazione, più un array obbligatorio targets di 1-50 nomi di bucket o container. Restituisce 201 con l'integrazione memorizzata. Le credenziali S3 temporanee (chiavi di accesso ASIA) non sono accettate.

Sfoglia oggetti#

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

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

Parametri di query:

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

Disconnetti archiviazione#

DELETE /api/integrations/buckets/{id}

Python SDK: client.storage_integrations.delete(id)

Rimuove le credenziali salvate senza eliminare i dati del provider. I dataset collegati rimangono visibili, ma i relativi file restano inaccessibili finché non viene ricollegato lo stesso account di archiviazione. Richiede l'accesso di amministratore dell'area di lavoro.

API di importazione dei dataset#

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

Visualizza in anteprima un'importazione Roboflow#

POST /api/integrations/roboflow/preview

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

Converte una chiave API Roboflow in un piano di importazione: dettagli dell'area di lavoro, newDatasets da importare, conteggi dei progetti già importati (skippedCount), senza versione, non supportati e non risolti, bytesTotal e la capacità residua (storage) del tuo piano. La chiave API Roboflow viene letta dal corpo della richiesta e non viene memorizzata.

{
    "apiKey": "ROBOFLOW_API_KEY"
}

Importa da Roboflow#

POST /api/integrations/roboflow/import

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

Accoda processi di ingestione per un massimo di 500 versioni selezionate di progetti Roboflow, usando 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 ogni dataset deve rispettare il limite di dimensione per importazione previsto dal tuo piano.

API dell'account#

Esamina il tuo account Platform, le chiavi, l'archiviazione e i profili pubblici. Consulta la documentazione delle impostazioni.

Riepilogo account#

GET /api/account/summary

Python SDK: client.account.summary()

Restituisce il piano, il saldo dei crediti e il conteggio delle risorse per l'area di lavoro 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 chiavi API#

GET /api/api-keys

Python SDK: client.account.api_keys()

Restituisce keys con keyId, name, keyPrefix e createdAt per l'area di lavoro della chiave. Le richieste autenticate con chiave API ricevono solo metadati; i valori completi delle chiavi sono visibili al proprietario dell'area di lavoro in Impostazioni > Chiavi API nell'interfaccia utente Platform, dove è anche possibile creare e revocare le chiavi.

Verifica utilizzo archiviazione#

GET /api/storage

Python SDK: client.account.storage()

Parametri di query:

Risposta:

{
    "tier": "pro",
    "usage": {
        "storage": { "current": 1073741824, "limit": 536870912000, "percent": 0 },
        "datasets": { "current": 2, "limit": -1, "percent": 0 },
        "models": { "current": 4, "limit": 500, "percent": 1 }
    },
    "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"
}

usage riporta i conteggi di projects, datasets, models, images, annotations e deployments, e i byte per storage. Un limit pari a -1 indica un valore illimitato, mentre percent è una percentuale intera del limite.

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 chi effettua chiamate autenticato, 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 valore aggiornato di followerCount.

API di fatturazione#

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

Visualizzare 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 e utilizzo dello spazio di archiviazione), trainingCredit, features, creditsCents e il numero di postazioni.

Visualizzare le transazioni#

GET /api/billing/transactions

Python SDK: client.billing.transactions()

Parametri di query:

Ogni transazione include id, type (ad esempio purchase, training, monthly_grant o refund), amountCents, balanceAfter, createdAt, un receiptUrl facoltativo e il contesto del modello per gli addebiti di addestramento. I dettagli interni di fatturazione non vengono mai restituiti.

API Esplora#

Cerca progetti pubblici e dataset condivisi dalla community oppure immagini in base a ciò che raffigurano. Consulta la documentazione di Esplora.

Cercare contenuti pubblici#

GET /api/explore/search

Python SDK: client.explore.search()

Parametri di query:

Risposta: projects, datasets e hasMore. type=images restituisce le corrispondenze in images, ordinate dalla più pertinente, ciascuna con la propria dataset di origine e un valore di somiglianza score compreso tra 0 e 1; richiede q e cerca nei dataset pubblici, oltre che nei tuoi dataset e in quelli del team quando invii una chiave API.

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

SDK Python#

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

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

from ultralytics_platform import Platform

with Platform() as client:  # legge ULTRALYTICS_API_KEY o la chiave salvata da yolo login
    dataset = client.datasets.retrieve("acme-vision", "warehouse")
    images = client.datasets.images("acme-vision", "warehouse", limit=10)
    export = client.exports.create("acme-vision", "inspection", "v3", format="onnx")

AsyncPlatform espone la stessa struttura di risorse per il codice async/await; le risposte non riuscite generano APIError con status_code, body e json analizzato, mentre gli errori di connessione generano 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 Ultralytics, che gestisce automaticamente autenticazione, caricamenti e trasmissione di metriche in tempo reale. Con Python 3.11+, pip install ultralytics installa anche l'SDK ultralytics-platform. Quando model.train(project=...) è destinato a Platform, i callback di addestramento trasmettono gli eventi tramite client.training.metrics() dell'SDK e richiedono gli URL per caricare i checkpoint tramite client.models.upload_checkpoint(), le operazioni POST /api/webhooks/training/metrics e POST /api/webhooks/models/upload del documento OpenAPI, quindi non devi effettuare chiamate direttamente.

Installazione e configurazione#

L'integrazione con Platform richiede Python>=3.11 e ultralytics>=8.4.120:

pip install "ultralytics>=8.4.120"

Verifica l'installazione:

yolo check

Autenticazione#

yolo login YOUR_API_KEY

Uso dei dataset della Platform#

Fai riferimento ai dataset con URI ul://:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Addestra sul tuo dataset Platform
model.train(
    data="ul://your-username/datasets/your-dataset",
    epochs=100,
    imgsz=640,
)

Formato URI:

Invio a Platform#

Invia i risultati a un progetto Platform:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# I risultati vengono sincronizzati automaticamente con Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="your-username/my-project",
    name="experiment-1",
)

Elementi sincronizzati:

• Metriche di addestramento (in tempo reale)
• Pesi del modello finali
• Grafici di convalida
• L'output della console
• Metriche di sistema
• Argomenti di addestramento e ambiente host (nome host, sistema operativo, Python, hardware, commit git, riga di comando)

Esempi di API#

Carica un modello da Platform:

# Il tuo modello
model = YOLO("ul://username/project/model-name")

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

Esegui l'inferenza:

results = model("image.jpg")

# Accedi ai risultati
for r in results:
    boxes = r.boxes  # Riquadri di rilevamento
    masks = r.masks  # Maschere di segmentazione
    keypoints = r.keypoints  # Keypoint di posa
    probs = r.probs  # Probabilità di classificazione

Esporta il modello:

# Esporta in ONNX
model.export(format="onnx", imgsz=640, quantize=16)

# Esporta in TensorRT
model.export(format="engine", imgsz=640, quantize=16)

# Esporta in CoreML
model.export(format="coreml", imgsz=640)  # usa imgsz=224 per la classificazione

Convalida:

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

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

Domande frequenti#