Riferimento REST API#

Ultralytics Platform fornisce una REST API per l'accesso programmatico a dataset, immagini, progetti, modelli, addestramento, esportazioni e deployment.

# 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 di 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 delle immagini di un dataset pubblico, esecuzione dell'inferenza su un modello pubblico o ricerca in Esplora — accettano anche richieste anonime e restituiscono semplicemente più risultati quando viene fornita una chiave.

Ottenere una chiave API#

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

Consulta Chiavi API per istruzioni dettagliate.

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

Le risorse vengono indirizzate utilizzando gli stessi nomi leggibili dalle persone che compaiono negli URL di Platform, non gli ID del database:

• {owner} è un nome utente personale o un identificatore di workspace del team: da 4 a 32 caratteri, alfanumerici minuscoli con singoli trattini tra i segmenti.
• {dataset}, {project}, {model} e {deployment} seguono lo stesso schema con caratteri minuscoli e trattini, fino a 128 caratteri.
• {imageId} e {exportId} sono ID esadecimali di 24 caratteri restituiti dall'API.
• La ridenominazione di una risorsa tramite PATCH modifica contemporaneamente il nome visualizzato name e il nome nell'URL, e la risposta restituisce il nome corrente nell'URL così puoi continuare a utilizzarlo.

Limiti di frequenza#

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

Le route di Platform utilizzabili solo dal browser, come il checkout della fatturazione e la gestione dei team, hanno limiti propri che non si applicano al traffico basato su chiavi API.

Quando viene applicato il throttling, 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",
    "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 di Platform quando chiami direttamente il serviceUrl del deployment (ad esempio, https://predict-abc123.run.app/predict). In questo caso, la velocità dipende dalla configurazione del servizio distribuito.

Formato della risposta#

Risposte di esito positivo#

Le risposte sono oggetti JSON con campi specifici per la risorsa. Non esiste un envelope generico: gli endpoint di elenco restituiscono una raccolta denominata insieme ai conteggi, mentre le modifiche 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), la regione di archiviazione del workspace.

Risposte di errore#

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

{
    "error": "Dataset not found"
}

Impaginazione#

Lo stile di paginazione dipende dalla raccolta:

API dei dataset#

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

Elenca dataset#

GET /api/datasets/{owner}

SDK Python: client.datasets.list(owner)

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

Parametri della 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}

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

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

La risposta restituisce lo slug dataset effettivamente creato, quindi leggilo prima di effettuare il caricamento a meno che tu non imposti requireExactSlug.

Risposta (201):

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

Aggiorna dataset#

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

SDK Python: 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 cancellare 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 ridenominazione modifica il nome nell'URL, quindi usa il valore dataset restituito per le richieste successive.

Elimina dataset#

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

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

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

Clona dataset#

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

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

Copia un dataset accessibile, con le relative immagini ed etichette, nel tuo workspace personale o in un workspace 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 supportati da una fonte di archiviazione connessa restituiscono 409 perché i relativi file non vengono copiati.

Scarica un'esportazione del dataset#

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

SDK Python: 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 dalla sua generazione.

Parametri della query:

Risposta:

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

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

Crea versione del dataset#

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

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

Crea uno snapshot numerato e immutabile del dataset e ne memorizza l'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 è true quando il dataset non è cambiato dalla versione precedente e viene restituito invece quello snapshot.

Aggiorna la descrizione della versione#

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

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

Corpo:

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

Risposta: {"ok": true}

Ripristina la versione del dataset#

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

SDK Python: 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 statistiche del dataset#

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

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

Restituisce i conteggi delle annotazioni per classe, gli istogrammi delle immagini e delle annotazioni e le mappe di calore. I dataset di grandi dimensioni vengono campionati; in tal 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 classi#

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

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

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

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

Elimina classi (le relative annotazioni vengono eliminate e gli ID delle classi rimanenti vengono decrementati):

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

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

{
    "classIds": [2, 4]
}

Entrambe le operazioni restituiscono success, i valori classNames e classColors aggiornati e un riepilogo delle modifiche (mergedClassIds e targetClassId, oppure deletedClassIds e deletedAnnotations).

Riditribuisci gli split#

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

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

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

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

Risposta: success, i conteggi splits risultanti 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 accoda un'analisi degli embedding e restituisce 202 con un jobId. DELETE annulla il job attivo e restituisce l'ID del job annullato o null.

Clustering delle immagini#

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

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

Restituisce il layout 2D UMAP di un'analisi completata, con paginazione tramite offset e limit (predefinito e massimo 50.000). Ogni voce contiene id, umapX, umapY, split, classIds, width, height, bytes, labelCount e missing.

Elenca i modelli addestrati su un dataset#

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

SDK Python: 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 immagini del dataset#

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

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

Parametri della 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

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

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

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

Acquisisci dati del dataset#

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

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

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

Le sessioni di caricamento sono associate a un dataset tramite assetId, passato a POST /api/upload/signed-url, e 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 delle etichette durante un'acquisizione successiva):

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

Corpo (associazione dei 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ò contenere il proprio oggetto metadata, che ha la precedenza su una voce corrispondente di imageMetadata. I percorsi dell'archivio sono limitati a 1.024 caratteri, le chiavi dei metadati di primo livello a 128 caratteri e ogni 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 relativo ID immagine di 24 caratteri. Consulta la documentazione sulle annotazioni.

Ottieni immagine#

GET /api/images/{imageId}

SDK Python: client.images.retrieve(image_id)

Restituisce l'oggetto metadata (personalizzato, definito dall'utente), un array properties di informazioni sintetiche per modello (stato, metriche, epoche, pesi, argomenti di addestramento), labels e classNames del dataset.

Aggiorna immagine#

PATCH /api/images/{imageId}

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

Sostituisce o le annotazioni o i metadati personalizzati — invia una 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}

SDK Python: client.images.delete(image_id)

Elimina definitivamente un'immagine e le relative annotazioni.

Annota automaticamente l'immagine#

POST /api/images/{imageId}/predict

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

Annota automaticamente un dataset#

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

SDK Python: client.datasets.create_batch(owner, dataset, model_id=...)

Salva una versione di un dataset, quindi accoda un'esecuzione che etichetta le immagini non etichettate del dataset con il modello e restituisce 202. Il corpo accetta gli stessi campi modelId, confidence e iou dell'endpoint per la singola immagine, oltre a includeAnnotated (predefinito false) per annotare anche le immagini che possiedono già etichette e un array opzionale classMapping che specifica l' indice della classe del dataset per ciascuna classe del modello, oppure null per saltarlo. Le etichette esistenti non vengono mai modificate e l'esecuzione viene fatturata per le immagini che elabora effettivamente. 402 significa che il saldo non può coprire la stima, 409 che il dataset non è pronto, non ha immagini rimanenti da annotare o ha già un'esecuzione in corso, e 422 che il dataset non ha classi: creale con l'endpoint delle classi prima di chiamare questo endpoint, operazione che il passaggio Map classes dell'app esegue 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 rimossa; DELETE (client.datasets.delete_batch(owner, dataset)) annulla un'esecuzione in corso o regola la fatturazione e rimuove il riepilogo completato.

Spostamento collettivo delle immagini#

PATCH /api/images/bulk

SDK Python: 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 contenuto restituiscono 409 finché non scegli un conflictPolicy valido per l'intero gruppo tra skip, keep_both o replace. La risposta restituisce modifiedCount, skippedCount e targetSplit.

Eliminazione collettiva delle immagini#

DELETE /api/images/bulk

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

SDK Python: 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. Ogni modello appartiene a un progetto. Consulta la documentazione sui progetti.

Elenca progetti#

GET /api/projects/{owner}

SDK Python: client.projects.list(owner)

Parametri della query:

Ottieni progetto#

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

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

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

SDK Python: 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 le chiavi e di 500.000 caratteri per gli oggetti serializzati dei metadati del dataset.

Elimina progetto#

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

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

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

Clona progetto#

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

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

Clona un progetto accessibile e i relativi modelli completati. Il corpo opzionale 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 l'inferenza e monitora l'addestramento. Consulta la documentazione sui modelli.

Elenca i modelli in un progetto#

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

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

Parametri della query:

Ottieni modello#

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

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

Parametri della query:

La risposta predefinita contiene l'oggetto model: stato, attività, metriche, trainArgs, trainResults, classNames, computeCost, metadata e altro ancora, oltre a isOwner.

Crea modello#

POST /api/models

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

SDK Python: 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. Il passaggio di projectId da solo sposta il modello in un altro progetto dello stesso proprietario; la risposta restituisce slug del modello nella destinazione, renamed: true quando tale slug è già occupato lì e 409 mentre il modello è ancora in fase di 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 modello#

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

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

Sposta il modello nel cestino per 30 giorni.

Scarica i file del modello#

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

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

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

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

È possibile eseguire previsioni sui modelli pubblici senza autenticazione. I modelli privati e condivisi richiedono una chiave API 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 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 tempi 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,
        "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

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

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

Annulla addestramento#

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

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

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

API di addestramento#

Avvia l'addestramento di 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 la disponibilità delle GPU#

GET /api/training/gpu-availability

SDK Python: client.training.gpu_availability()

Restituisce lo stato attuale delle scorte, indicizzato per ID GPU. Pubblico e senza autenticazione; passa managed=true per includere la capacità di addestramento gestita, che richiede una chiave API.

Avvia l'addestramento#

POST /api/training/start

SDK Python: 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 delle esportazioni#

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

Elenca le esportazioni#

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

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

Parametri della query:

Crea esportazione#

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

SDK Python: 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 condivisa delle esportazioni riportata di seguito. PyTorch è il formato di origine e non è una destinazione di esportazione API.

nms=None utilizza i valori predefiniti per gli output grezzi per la NMS esterna. Imposta nms=False per selezionare una testa senza NMS disponibile; i formati non supportati ricorrono al loro percorso di output nativo. Le voci nms sopra indicano i formati che possono incorporare la NMS con nms=True.

Ottieni lo stato dell'esportazione#

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

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

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

Annulla o elimina l'esportazione#

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

SDK Python: 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 delle due operazioni è stata eseguita:

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

API delle distribuzioni#

Distribuisci i modelli su endpoint di inferenza dedicati con controlli dello stato 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 le distribuzioni#

GET /api/deployments/{owner}

SDK Python: client.deployments.list(owner)

Parametri della query:

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

Crea distribuzione#

POST /api/deployments/{owner}

SDK Python: 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 la distribuzione#

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

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

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

Avvia, arresta o sostituisci una distribuzione#

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

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

Un singolo campo action seleziona l'operazione:

{ "action": "start" }

La sostituzione distribuisce una nuova revisione mantenendo l'ID della distribuzione, la regione e l'URL dell'endpoint; la revisione esistente rimane attiva se la distribuzione non riesce. 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 distribuzione restituiscono 202 con deploying o stopping.

Elimina distribuzione#

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

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

Rimuove definitivamente l'endpoint di inferenza.

Controllo dello stato#

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

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

Esegue il ping e il preriscaldamento dell'endpoint, restituendo healthy, latencyMs e il codice upstream status.

Esegui l'inferenza su una distribuzione#

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

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

Instrada un'immagine o un video attraverso l'endpoint dedicato. I contratti della richiesta e della risposta corrispondono a quelli dell'inferenza del modello.

Modulo multipart:

Ottieni le metriche#

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

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

Parametri della query:

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

Ottieni i log#

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

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

Parametri della query:

API del cestino#

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

Elenca il Cestino#

GET /api/trash

SDK Python: client.lifecycle.trash()

Parametri della 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

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

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

Il ripristino di un progetto ripristina anche i modelli che sono stati spostati nel cestino insieme a esso, riportati come restoredModels.

Elimina definitivamente#

DELETE /api/trash

SDK Python: 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 quando pertinenti.

API di caricamento#

Carica i file direttamente nello storage cloud utilizzando URL firmati. Il completamento del caricamento di un modello associa i relativi pesi; il completamento del caricamento di un archivio di dataset registra la sessione, che passerai poi all'acquisizione del dataset. Consulta la documentazione sui dati.

Ottieni l'URL firmato per il caricamento#

POST /api/upload/signed-url

SDK Python: 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, utilizzando lo stesso Content-Type che hai dichiarato e ogni intestazione restituita in headers. Gli URL di caricamento dei dataset sono validi per 12 ore e di sola creazione: un secondo PUT allo stesso URL restituisce 412 e un PUT senza le intestazioni restituite restituisce 400.

Completa il caricamento#

POST /api/upload/complete

SDK Python: 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 associa i pesi; per gli archivi di dataset, chiama ingest subito dopo per avviare l'elaborazione.

Quando viene fornito md5, questo viene confrontato con l'oggetto memorizzato. Una mancata corrispondenza restituisce 400; su una sessione non ancora completa elimina anche il file caricato e lascia la sessione incompleta, quindi richiedi un nuovo URL firmato e carica di nuovo. Una sessione di dataset completata può essere completata nuovamente finché esiste il suo archivio, ma completamenti concorrenti con digest differenti restituiscono 409; le sessioni dei modelli vengono rimosse al completamento. checksum viene memorizzato come metadato del file del modello e non viene verificato.

API delle integrazioni di storage#

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

Elenca integrazioni#

GET /api/integrations/buckets

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

SDK Python: 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"]}

Connetti spazio di archiviazione#

POST /api/integrations/buckets

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

Stesse strutture delle credenziali usate per l'individuazione, oltre a un array targets obbligatorio contenente da 1 a 50 nomi di bucket o container. Restituisce 201 con l'integrazione salvata. Le credenziali S3 temporanee (chiavi di accesso ASIA) vengono rifiutate.

Sfoglia oggetti#

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

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

Parametri della query:

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

Disconnetti spazio di archiviazione#

DELETE /api/integrations/buckets/{id}

SDK Python: client.storage_integrations.delete(id)

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

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

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

Risolvi una chiave API Roboflow in un piano di importazione: dettagli del workspace, newDatasets che verrebbero importati, conteggi dei progetti ignorati, non supportati e non risolti, bytesTotal e la tua disponibilità residua storage. La chiave API Roboflow viene letta dal corpo della richiesta e non viene salvata.

{
    "apiKey": "ROBOFLOW_API_KEY"
}

Importa da Roboflow#

POST /api/integrations/roboflow/import

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

Accoda i processi di acquisizione per un massimo di 500 versioni di progetti Roboflow selezionate, 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 rientrare nel limite dimensionale per importazione previsto dal tuo piano.

API dell'account#

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

Riepilogo dell'account#

GET /api/account/summary

SDK Python: client.account.summary()

Restituisce il piano, il saldo dei crediti e il conteggio delle risorse per il workspace che ha emesso 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

SDK Python: client.account.api_keys()

Restituisce keys con keyId, name, keyPrefix e createdAt per il workspace della chiave. Le richieste autenticate con chiave API ricevono solo i metadati; i valori completi delle chiavi vengono mostrati al proprietario del workspace in Impostazioni > Chiavi API nell'interfaccia Platform, dove è anche possibile creare e revocare le chiavi.

Controlla l'utilizzo dello spazio di archiviazione#

GET /api/storage

SDK Python: client.account.storage()

Parametri della 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

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

Parametri della query:

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

Segui o smetti di seguire un utente#

PATCH /api/users

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

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

Risposta: followed e followerCount aggiornato.

API di fatturazione#

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

Visualizza piano e utilizzo#

GET /api/billing/usage-summary

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

Visualizza transazioni#

GET /api/billing/transactions

SDK Python: client.billing.transactions()

Parametri della query:

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

Esplora API#

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

Cerca contenuti pubblici#

GET /api/explore/search

SDK Python: client.explore.search()

Parametri della query:

Risposta: projects, datasets e hasMore.

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

SDK Python#

ultralytics-platform è un client Python tipizzato 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 posizione, gli altri input come argomenti con nome e timeout e extra_headers opzionali per ogni richiesta.

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

from ultralytics_platform import Platform

with Platform() as client:  # reads ULTRALYTICS_API_KEY or the key saved by 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 lo stesso albero di risorse per il codice async/await; le risposte non riuscite generano APIError con status_code, body e json analizzato, mentre i problemi di connessione generano APIConnectionError. Consulta il repository SDK per il README completo.

Integrazione Python#

Per i flussi 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#

L'integrazione della piattaforma 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

Utilizzo dei dataset della Platform#

Fai riferimento ai dataset con 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 a Platform#

Invia i risultati a un progetto Platform:

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 addestramento (in tempo reale)
• Pesi finali del modello
• Grafici di validazione
• Output della console
• Metriche di sistema

Esempi di API#

Caricamento di un modello da Platform:

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

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

Esecuzione dell'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

Esportazione del 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#