Link to this sectionRiferimento REST API#

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

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

Link to this sectionPanoramica API#

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

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

Link to this sectionAutenticazione#

Le API delle risorse come dataset, progetti, modelli, training, esportazioni e predizioni utilizzano l'autenticazione tramite API key. Gli endpoint pubblici (elenco di dataset, progetti e modelli pubblici) supportano l'accesso in lettura anonimo senza una chiave. Le rotte orientate all'account, inclusi flussi di attività, impostazioni, team, fatturazione e GDPR, richiedono attualmente una sessione browser autenticata e non sono disponibili tramite API key.

Link to this sectionOttieni API Key#

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

Vedi API Keys per istruzioni dettagliate.

Link to this sectionHeader di autorizzazione#

Includi la tua API key in tutte le richieste:

Authorization: Bearer YOUR_API_KEY

Link to this sectionEsempio#

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

Link to this sectionBase URL#

Tutti gli endpoint API utilizzano:

Link to this sectionLimiti di frequenza#

L'API impone limiti di frequenza per API key (sliding-window, basati su Upstash Redis) per proteggersi dagli abusi, mantenendo al contempo l'uso legittimo senza restrizioni. Il traffico anonimo è inoltre protetto dai controlli contro gli abusi a livello di piattaforma di Vercel.

In caso di limitazione, l'API restituisce 429 con metadati per il ripristino:

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

Link to this sectionLimiti per API Key#

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

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

Link to this sectionEndpoint dedicati (Illimitato)#

Gli endpoint dedicati non sono soggetti ai limiti di frequenza delle API key. Quando distribuisci un modello su un endpoint dedicato, le richieste a quell'URL dell'endpoint (ad esempio, https://predict-abc123.run.app/predict) vanno direttamente al tuo servizio dedicato senza limitazioni di frequenza dalla piattaforma. Paghi per la potenza di calcolo, quindi ottieni il throughput dalla configurazione del tuo servizio dedicato anziché dai limiti API condivisi.

Link to this sectionFormato risposta#

Link to this sectionRisposte di successo#

Le risposte restituiscono JSON con campi specifici per la risorsa:

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

Link to this sectionRisposte di errore#

{
    "error": "Dataset not found"
}

Link to this sectionAPI dei Dataset#

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

Link to this sectionElenca Dataset#

GET /api/datasets

Parametri di query:

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

Risposta:

{
    "datasets": [
        {
            "_id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "classNames": ["person", "car"],
            "visibility": "private",
            "username": "johndoe",
            "starCount": 3,
            "isStarred": false,
            "sampleImages": [
                {
                    "url": "https://storage.example.com/...",
                    "width": 1920,
                    "height": 1080,
                    "labels": [{ "classId": 0, "bbox": [0.5, 0.4, 0.3, 0.6] }]
                }
            ],
            "createdAt": "2024-01-15T10:00:00Z",
            "updatedAt": "2024-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

Link to this sectionOttieni Dataset#

GET /api/datasets/{datasetId}

Restituisce i dettagli completi del dataset inclusi metadati, nomi delle classi e conteggi delle suddivisioni.

Link to this sectionCrea Dataset#

POST /api/datasets

Corpo:

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

Link to this sectionAggiorna Dataset#

PATCH /api/datasets/{datasetId}

Corpo (aggiornamento parziale):

{
    "name": "Updated Name",
    "description": "New description",
    "visibility": "public"
}

Link to this sectionIcona del dataset#

Carica un'icona del dataset (form multipart con file immagine):

POST /api/datasets/{datasetId}/icon

Rimuovi l'icona del dataset:

DELETE /api/datasets/{datasetId}/icon

Entrambi richiedono una sessione browser attiva sulla piattaforma; non sono disponibili tramite chiave API.

Link to this sectionElimina Dataset#

DELETE /api/datasets/{datasetId}

Esegue l'eliminazione logica del dataset (spostato nel cestino, recuperabile per 30 giorni).

Link to this sectionClona dataset#

POST /api/datasets/{datasetId}/clone

Crea una copia del dataset con tutte le immagini e le etichette. Possono essere clonati solo i dataset pubblici, di tua proprietà o modificabili all'interno del workspace. Richiede una sessione browser attiva sulla piattaforma — non disponibile tramite API key.

Corpo (tutti i campi sono opzionali):

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

Link to this sectionEsporta Dataset#

GET /api/datasets/{datasetId}/export

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

Parametri di query:

Risposta:

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

Link to this sectionCrea Versione Dataset#

POST /api/datasets/{datasetId}/export

Crea un nuovo snapshot di versione numerato del dataset. Solo per il proprietario. La versione cattura il conteggio attuale delle immagini, delle classi, delle annotazioni e la distribuzione delle suddivisioni, quindi genera e archivia un'esportazione NDJSON immutabile.

Corpo della richiesta:

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

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

Risposta:

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

Link to this sectionAggiorna Descrizione Versione#

PATCH /api/datasets/{datasetId}/export

Aggiorna la descrizione di una versione esistente. Solo per il proprietario.

Corpo della richiesta:

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

Risposta:

{
    "ok": true
}

Link to this sectionOttieni Statistiche Classi#

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

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

Risposta:

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120 }],
        "heightHistogram": [{ "bin": 480, "count": 95 }],
        "pointsHistogram": [{ "bin": 4, "count": 200 }]
    },
    "locationHeatmap": {
        "bins": [
            [5, 10],
            [8, 3]
        ],
        "maxCount": 50
    },
    "dimensionHeatmap": {
        "bins": [
            [2, 5],
            [3, 1]
        ],
        "maxCount": 12,
        "minWidth": 10,
        "maxWidth": 1920,
        "minHeight": 10,
        "maxHeight": 1080
    },
    "classNames": ["person", "car", "dog"],
    "cached": true,
    "sampled": false,
    "sampleSize": 1000
}

Link to this sectionGestisci Classi#

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

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

Elimina classi:

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

Link to this sectionRidistribuisci Split#

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

Riassegna le immagini tra gli split train/val/test. Tutti e tre richiedono una sessione browser attiva sulla piattaforma — non disponibile tramite API key.

Link to this sectionEmbedding del Dataset#

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

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

Link to this sectionClustering Immagini#

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

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

Link to this sectionOttieni Modelli Addestrati sul Dataset#

GET /api/datasets/{datasetId}/models

Restituisce i modelli che sono stati addestrati utilizzando questo dataset.

Risposta:

{
    "models": [
        {
            "_id": "model_abc123",
            "name": "experiment-1",
            "slug": "experiment-1",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "projectId": "project_xyz",
            "projectSlug": "my-project",
            "projectIconColor": "#3b82f6",
            "projectIconLetter": "M",
            "username": "johndoe",
            "startedAt": "2024-01-14T22:00:00Z",
            "completedAt": "2024-01-15T10:00:00Z",
            "createdAt": "2024-01-14T21:55:00Z",
            "metrics": {
                "mAP50": 0.85,
                "mAP50-95": 0.72,
                "precision": 0.88,
                "recall": 0.81
            }
        }
    ],
    "count": 1
}

Link to this sectionAnnotazione Automatica del Dataset#

POST /api/datasets/{datasetId}/predict

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

Corpo:

Link to this sectionIngestione Dataset#

POST /api/datasets/ingest

Crea un processo di ingestione del dataset per elaborare file ZIP o TAR caricati, inclusi .tar.gz e .tgz, contenenti immagini ed etichette.

Il corpo della richiesta accetta esattamente uno tra sessionId (una sessione di caricamento di un archivio) o sourceUrl (un URL remoto ZIP, TAR, TAR.GZ, TGZ o NDJSON), più un targetSplit facoltativo (train, val o test) per sovrascrivere la struttura degli split dell'archivio.

graph LR
    A[Upload Archive] --> B[POST /api/datasets/ingest]
    B --> C[Process Archive]
    C --> D[Extract images]
    C --> E[Parse labels]
    C --> F[Generate thumbnails]
    D & E & F --> G[Dataset ready]

Link to this sectionImmagini del Dataset#

Link to this sectionElenca Immagini#

GET /api/datasets/{datasetId}/images

Parametri di query:

Link to this sectionOttieni URL Firmati delle Immagini#

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

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

Link to this sectionElimina Immagine#

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

Link to this sectionOttieni Etichette Immagine#

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

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

Link to this sectionAggiorna Etichette Immagine#

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

Corpo:

{
    "labels": [
        { "classId": 0, "bbox": [0.5, 0.5, 0.2, 0.3] },
        { "classId": 1, "segments": [0.1, 0.2, 0.3, 0.2, 0.2, 0.4] }
    ]
}

Link to this sectionOperazioni in Massa sulle Immagini#

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

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

Eliminazione in massa delle immagini:

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

Link to this sectionAPI dei Progetti#

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

Link to this sectionElenca Progetti#

GET /api/projects

Parametri di query:

Link to this sectionOttieni Progetto#

GET /api/projects/{projectId}

Link to this sectionCrea Progetto#

POST /api/projects

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "slug": "my-project", "description": "Detection experiments"}' \
  https://platform.ultralytics.com/api/projects

Link to this sectionAggiorna Progetto#

PATCH /api/projects/{projectId}

Link to this sectionElimina Progetto#

DELETE /api/projects/{projectId}

Esegue l'eliminazione logica del progetto (spostato nel cestino).

Link to this sectionClona Progetto#

POST /api/projects/{projectId}/clone

Clona un progetto pubblico (con tutti i suoi modelli) nel tuo spazio di lavoro. Richiede una sessione attiva nel browser della piattaforma — non disponibile tramite chiave API.

Link to this sectionIcona Progetto#

Carica un'icona del progetto (modulo multipart con file immagine):

POST /api/projects/{projectId}/icon

Rimuovi l'icona del progetto:

DELETE /api/projects/{projectId}/icon

Entrambi richiedono una sessione browser attiva sulla piattaforma; non sono disponibili tramite chiave API.

Link to this sectionAPI Modelli#

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

Link to this sectionElenco Modelli#

GET /api/models

Parametri di query:

Link to this sectionElenco Modelli Completati#

GET /api/models/completed

Restituisce i modelli che hanno terminato l'addestramento (da utilizzare nei selettori di modelli e nel deployment).

Link to this sectionOttieni Modello#

GET /api/models/{modelId}

Link to this sectionCrea Modello#

POST /api/models

Corpo JSON:

Link to this sectionAggiorna Modello#

PATCH /api/models/{modelId}

Link to this sectionElimina Modello#

DELETE /api/models/{modelId}

Link to this sectionScarica File Modello#

GET /api/models/{modelId}/files

Restituisce URL di download firmati per i file del modello.

Link to this sectionClona modello#

POST /api/models/{modelId}/clone

Clona un modello pubblico in uno dei tuoi progetti. Richiede una sessione browser attiva sulla piattaforma; non disponibile tramite chiave API.

Corpo:

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

Link to this sectionTraccia Download#

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

Traccia le analisi di download del modello.

Link to this sectionEsegui l'inferenza#

POST /api/models/{modelId}/predict

Modulo Multipart:

La dimensione massima di caricamento è 100 MB.

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.jpg" \
  -F "conf=0.5" \
  https://platform.ultralytics.com/api/models/MODEL_ID/predict

Risposta:

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

Link to this sectionOttieni Token di Predizione#

POST /api/models/{modelId}/predict/token

Link to this sectionRiscaldamento Modello#

POST /api/models/{modelId}/predict/warmup

Link to this sectionAPI di Addestramento#

Avvia l'addestramento YOLO su GPU cloud (24 tipi di GPU da RTX 2000 Ada a B300) e monitora l'avanzamento in tempo reale. Consulta la documentazione sull'Addestramento in Cloud.

graph LR
    A[POST /training/start] --> B[Job Created]
    B --> C{Training}
    C -->|progress| D[GET /models/id/training]
    C -->|cancel| E[DELETE /models/id/training]
    C -->|complete| F[Model Ready]
    F --> G[Deploy or Export]

Link to this sectionAvvia Addestramento#

POST /api/training/start

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "MODEL_ID",
    "projectId": "PROJECT_ID",
    "gpuType": "rtx-4090",
    "trainArgs": {
      "model": "yolo26n.pt",
      "data": "ul://username/datasets/my-dataset",
      "epochs": 100,
      "imgsz": 640,
      "batch": 16
    }
  }' \
  https://platform.ultralytics.com/api/training/start

Link to this sectionOttieni disponibilità GPU#

GET /api/training/gpu-availability

Restituisce lo stato attuale dello stock di GPU (High, Medium, Low o null) indicizzato per ID tipo di GPU. Pubblico, nessuna autenticazione richiesta; memorizzato nella cache per 5 minuti.

Link to this sectionOttieni Stato Addestramento#

GET /api/models/{modelId}/training

Restituisce lo stato corrente del lavoro di addestramento, le metriche e l'avanzamento di un modello. I progetti pubblici sono accessibili in modo anonimo; i progetti privati richiedono una sessione browser attiva sulla piattaforma (questa rotta non accetta autenticazione tramite chiave API).

Link to this sectionAnnulla Addestramento#

DELETE /api/models/{modelId}/training

Termina l'istanza di calcolo in esecuzione e contrassegna il lavoro come annullato. Richiede una sessione browser attiva sulla piattaforma; non disponibile tramite chiave API.

Link to this sectionAPI Deployments#

Distribuisci modelli su endpoint di inferenza dedicati con controlli di integrità e monitoraggio. I nuovi deployment utilizzano di default lo scale-to-zero e l'API accetta un oggetto resources opzionale. Consulta la documentazione sugli Endpoint.

graph LR
    A[Create] --> B[Deploying]
    B --> C[Ready]
    C -->|stop| D[Stopped]
    D -->|start| C
    C -->|delete| E[Deleted]
    D -->|delete| E
    C -->|predict| F[Inference Results]

Link to this sectionElenco Deployments#

GET /api/deployments

Parametri di query:

Link to this sectionCrea Deployment#

POST /api/deployments

Corpo:

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

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

Link to this sectionOttieni Deployment#

GET /api/deployments/{deploymentId}

Link to this sectionElimina Deployment#

DELETE /api/deployments/{deploymentId}

Link to this sectionAvvia Deployment#

POST /api/deployments/{deploymentId}/start

Riprendi un deployment interrotto.

Link to this sectionInterrompi Deployment#

POST /api/deployments/{deploymentId}/stop

Metti in pausa un deployment in esecuzione (interrompe la fatturazione).

Link to this sectionControllo Integrità#

GET /api/deployments/{deploymentId}/health

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

Link to this sectionEsegui Inferenza sul Deployment#

POST /api/deployments/{deploymentId}/predict

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

Modulo Multipart:

Link to this sectionOttieni Metriche#

GET /api/deployments/{deploymentId}/metrics

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

Parametri di query:

Link to this sectionOttieni Log#

GET /api/deployments/{deploymentId}/logs

Parametri di query:

Link to this sectionAPI di Monitoraggio#

Link to this sectionMetriche aggregate#

GET /api/monitoring

Restituisce le metriche aggregate di tutti i deployment dell'utente: numero totale di richieste, deployment attivi, tasso di errore e latenza media.

Link to this sectionAPI di esportazione#

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

Link to this sectionElenco esportazioni#

GET /api/exports

Parametri di query:

Link to this sectionCrea esportazione#

POST /api/exports

Corpo:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"modelId": "MODEL_ID", "format": "onnx"}' \
  https://platform.ultralytics.com/api/exports

Formati supportati:

Link to this sectionOttieni stato esportazione#

GET /api/exports/{exportId}

Link to this sectionAnnulla esportazione#

DELETE /api/exports/{exportId}

Link to this sectionTraccia download esportazione#

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

Link to this sectionAPI di attività#

Visualizza un feed delle azioni recenti sul tuo account: esecuzioni di training, upload e altro. Consulta la documentazione sull'attività.

Link to this sectionElenco attività#

GET /api/activity

Parametri di query:

Link to this sectionContrassegna eventi come letti#

POST /api/activity/mark-seen

Corpo:

{
    "all": true
}

Oppure passa ID specifici:

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

Link to this sectionArchivia eventi#

POST /api/activity/archive

Corpo:

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

Oppure passa ID specifici:

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

Link to this sectionAPI cestino#

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

Link to this sectionElenco cestino#

GET /api/trash

Parametri di query:

Link to this sectionRipristina elemento#

POST /api/trash

Corpo:

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

Link to this sectionElimina definitivamente elemento#

DELETE /api/trash

Corpo:

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

Link to this sectionSvuota cestino#

DELETE /api/trash/empty

Elimina definitivamente tutti gli elementi nel cestino.

Link to this sectionAPI di fatturazione#

Controlla il tuo saldo crediti, acquista crediti, visualizza lo storico delle transazioni e configura la ricarica automatica. Consulta la documentazione sulla fatturazione.

Link to this sectionOttieni saldo#

GET /api/billing/balance

Parametri di query:

Risposta:

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

Link to this sectionOttieni riepilogo utilizzo#

GET /api/billing/usage-summary

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

Link to this sectionOttieni transazioni#

GET /api/billing/transactions

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

Parametri di query:

Link to this sectionCrea sessione di checkout#

POST /api/billing/checkout-session

Corpo:

{
    "amount": 25,
    "owner": "team-username"
}

Crea una sessione di checkout per l'acquisto di crediti.

Link to this sectionCrea checkout abbonamento#

POST /api/billing/subscription-checkout

Crea una sessione di checkout per l'aggiornamento dell'abbonamento Pro.

Corpo:

{
    "planId": "pro",
    "billingCycle": "monthly",
    "owner": "team-username"
}

Link to this sectionAnnulla o riprendi abbonamento#

DELETE /api/billing/subscription-checkout

Annulla un abbonamento Pro alla fine del periodo per impostazione predefinita. Invia {"resume": true} per riprendere una cancellazione già programmata prima che finisca il periodo di fatturazione.

Corpo:

{
    "resume": true
}

Link to this sectionRicarica automatica#

Aggiungi automaticamente crediti quando il saldo scende sotto una soglia.

Link to this sectionOttieni la configurazione del ricaricamento automatico#

GET /api/billing/auto-topup

Parametri di query:

Link to this sectionAggiorna la configurazione del ricaricamento automatico#

PATCH /api/billing/auto-topup

Corpo:

{
    "enabled": true,
    "thresholdCents": 500,
    "amountCents": 2500
}

Link to this sectionMetodi di pagamento#

Link to this sectionElenca i metodi di pagamento#

GET /api/billing/payment-methods

Link to this sectionCrea setup intent#

POST /api/billing/payment-methods/setup

Restituisce un client secret per aggiungere un nuovo metodo di pagamento.

Link to this sectionImposta il metodo di pagamento predefinito#

POST /api/billing/payment-methods/default

Corpo:

{
    "paymentMethodId": "pm_123"
}

Link to this sectionAggiorna le informazioni di fatturazione#

PATCH /api/billing/payment-methods

Corpo:

{
    "name": "Jane Doe",
    "address": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
    }
}

Link to this sectionElimina metodo di pagamento#

DELETE /api/billing/payment-methods/{id}

Link to this sectionAPI di archiviazione#

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

Link to this sectionOttieni informazioni sull'archiviazione#

GET /api/storage

Parametri di query:

Risposta:

{
    "tier": "free",
    "usage": {
        "storage": {
            "current": 1073741824,
            "limit": 107374182400,
            "percent": 1.0
        }
    },
    "region": "us",
    "username": "johndoe",
    "updatedAt": "2024-01-15T10:00:00Z",
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "dataset_abc123",
                "name": "my-dataset",
                "slug": "my-dataset",
                "sizeBytes": 536870912,
                "type": "dataset"
            },
            {
                "_id": "model_def456",
                "name": "experiment-1",
                "slug": "experiment-1",
                "sizeBytes": 134217728,
                "type": "model",
                "parentName": "My Project",
                "parentSlug": "my-project"
            }
        ]
    }
}

Link to this sectionAPI di caricamento#

Carica i file direttamente nell'archiviazione cloud usando URL firmati per trasferimenti veloci e affidabili. Utilizza un flusso a due passaggi: ottieni un URL firmato, poi carica il file. Consulta la documentazione dati.

Link to this sectionOttieni URL di caricamento firmato#

POST /api/upload/signed-url

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

Corpo:

{
    "assetType": "images",
    "assetId": "abc123",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "totalBytes": 5242880
}

Risposta:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "gcsPath": "gs://bucket/users/user123/images/abc123/my-image.jpg",
    "downloadUrl": "https://cdn.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

Link to this sectionCompleta il caricamento#

POST /api/upload/complete

Notifica alla piattaforma che il caricamento di un file è completo, così da poter avviare l'elaborazione.

Corpo:

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

Link to this sectionAPI di Integrazione#

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

Link to this sectionAnteprima Importazione Roboflow#

POST /api/integrations/roboflow/preview

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

Link to this sectionImporta da Roboflow#

POST /api/integrations/roboflow/import

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

Link to this sectionAPI delle chiavi API#

Gestisci le tue chiavi API per l'accesso programmatico. Consulta la documentazione sulle chiavi API.

Link to this sectionElenca le chiavi API#

GET /api/api-keys

Link to this sectionCrea chiave API#

POST /api/api-keys

Corpo:

{
    "name": "training-server"
}

Link to this sectionElimina chiave API#

DELETE /api/api-keys

Parametri di query:

Esempio:

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

Link to this sectionAPI di team e membri#

Crea spazi di lavoro per i team, invita membri e gestisci i ruoli per la collaborazione. Consulta la documentazione sui team.

Link to this sectionElenca i team#

GET /api/teams

Link to this sectionCrea team#

POST /api/teams/create

Corpo:

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

Link to this sectionElenca i membri#

GET /api/members

Restituisce i membri dello spazio di lavoro corrente.

Link to this sectionInvita membro#

POST /api/members

Corpo:

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

Link to this sectionAggiorna ruolo membro#

PATCH /api/members/{userId}

Link to this sectionRimuovi membro#

DELETE /api/members/{userId}

Link to this sectionTrasferisci proprietà#

POST /api/members/transfer-ownership

Link to this sectionInviti#

Link to this sectionAccetta invito#

POST /api/invites/accept

Link to this sectionOttieni informazioni sull'invito#

GET /api/invites/info

Parametri di query:

Link to this sectionRevoca invito#

DELETE /api/invites/{inviteId}

Link to this sectionRispedisci invito#

POST /api/invites/{inviteId}/resend

Link to this sectionAPI di esplorazione#

Cerca e naviga tra dataset e progetti pubblici condivisi dalla community. Consulta la documentazione di esplorazione.

Link to this sectionCerca contenuti pubblici#

GET /api/explore/search

Parametri di query:

Link to this sectionDati della barra laterale#

GET /api/explore/sidebar

Restituisce contenuti curati per la barra laterale di esplorazione.

Link to this sectionAPI utente e impostazioni#

Gestisci il tuo profilo, le chiavi API, l'utilizzo dello spazio di archiviazione e le impostazioni sulla privacy dei dati. Consulta la documentazione sulle impostazioni.

Link to this sectionOttieni utente tramite nome utente#

GET /api/users

Parametri di query:

Link to this sectionSegui o smetti di seguire un utente#

PATCH /api/users

Corpo:

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

Link to this sectionVerifica disponibilità nome utente#

GET /api/username/check

Parametri di query:

Link to this sectionImpostazioni#

GET /api/settings
POST /api/settings

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

Link to this sectionIcona del profilo#

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

Carica o rimuovi l'avatar del profilo.

Link to this sectionOnboarding#

POST /api/onboarding

Completa il flusso di onboarding (imposta regione dati, nome utente).

Link to this sectionAPI GDPR#

Richiedi un export di tutti i tuoi dati o elimina permanentemente il tuo account. Consulta la documentazione sulle impostazioni.

Link to this sectionOttieni lo stato del job GDPR#

GET /api/gdpr

Parametri di query:

Restituisce lo stato del job. Per i job di export completati, la risposta include un downloadUrl.

Link to this sectionAvvia flusso di export o eliminazione#

POST /api/gdpr

Corpo:

{
    "action": "export"
}

{
    "action": "delete",
    "confirmationWord": "DELETE"
}

Opzionale per gli spazi di lavoro dei team:

{
    "action": "delete",
    "confirmationWord": "DELETE",
    "teamUsername": "my-team"
}

Link to this sectionCodici di errore#

Link to this sectionIntegrazione Python#

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

Link to this sectionInstallazione e configurazione#

pip install ultralytics

Verifica l'installazione:

yolo check

Link to this sectionAutenticazione#

yolo settings api_key=YOUR_API_KEY

Link to this sectionUso dei dataset della piattaforma#

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:

Link to this sectionInvio alla piattaforma#

Invia i risultati a un progetto della piattaforma:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Results automatically sync to Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="your-username/my-project",
    name="experiment-1",
)

Cosa viene sincronizzato:

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

Link to this sectionEsempi di API#

Carica un modello dalla piattaforma:

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

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

Esegui l'inferenza:

results = model("image.jpg")

# Access results
for r in results:
    boxes = r.boxes  # Detection boxes
    masks = r.masks  # Segmentation masks
    keypoints = r.keypoints  # Pose keypoints
    probs = r.probs  # Classification probabilities

Esporta modello:

# Export to ONNX
model.export(format="onnx", imgsz=640, half=True)

# Export to TensorRT
model.export(format="engine", imgsz=640, half=True)

# Export to CoreML
model.export(format="coreml", imgsz=640)

Validazione:

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

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

Link to this sectionWebhook#

La piattaforma utilizza webhook interni per trasmettere in streaming le metriche di training in tempo reale dall'SDK Python ultralytics (in esecuzione su GPU cloud o macchine remote/locali) alla piattaforma: loss epoca per epoca, mAP, statistiche di sistema e stato di completamento. Questi webhook sono autenticati tramite l'HMAC webhookSecret fornito per ogni job di training e non sono destinati ad essere utilizzati dalle applicazioni utente.

Link to this sectionFAQ#

Link to this sectionCome posso paginare grandi risultati?#

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

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

Gli endpoint Activity e Trash supportano anche un parametro page per la paginazione basata su pagine:

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

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

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

Link to this sectionPosso usare l'API senza un SDK?#

Sì, tutte le funzionalità sono disponibili tramite REST. L'SDK Python è un wrapper di comodità che aggiunge funzionalità come lo streaming di metriche in tempo reale e il caricamento automatico dei modelli. Puoi anche esplorare tutti gli endpoint in modo interattivo su platform.ultralytics.com/api/docs.

Link to this sectionEsistono librerie client API?#

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

Link to this sectionCome gestisco i limiti di velocità (rate limits)?#

Usa l'header Retry-After dalla risposta 429 per attendere la quantità di tempo corretta:

import time

import requests

def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code != 429:
            return response
        wait = int(response.headers.get("Retry-After", 2**attempt))
        time.sleep(wait)
    raise Exception("Rate limit exceeded")

Link to this sectionCome trovo il mio ID modello o dataset?#

Gli ID delle risorse vengono restituiti quando crei risorse tramite l'API. Puoi trovarli anche nell'URL della piattaforma:

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

Usa gli endpoint di elenco per cercare per nome o filtrare per progetto.