Riferimento API REST

Ultralytics Platform fornisce una API REST 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

Panoramica API

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

Autenticazione

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

Ottieni chiave API

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

Consulta Chiavi API per istruzioni dettagliate.

Intestazione di autorizzazione

Includi la tua chiave API in tutte le richieste:

Authorization: Bearer YOUR_API_KEY

Esempio

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

URL di base

Tutti gli endpoint API utilizzano:

Limiti di frequenza

L'API applica limiti di frequenza per chiave API (finestra scorrevole, basata su Upstash Redis) per proteggersi dagli abusi mantenendo l'utilizzo legittimo senza restrizioni. Il traffico anonimo è ulteriormente protetto dai controlli di abuso a livello di piattaforma di Vercel.

Quando viene applicato il throttling, l'API restituisce 429 con metadati di retry:

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

Limiti per chiave API

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 chiave API. Ad esempio, effettuare 20 richieste di predizione non influisce sulla tua franchigia predefinita di 100 richieste/min.

Endpoint dedicati (Illimitato)

Gli endpoint dedicati non sono soggetti ai limiti di frequenza delle chiavi API. 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 il calcolo, quindi ottieni il throughput dalla configurazione del tuo servizio dedicato anziché dai limiti dell'API condivisa.

Formato di risposta

Risposte di successo

Le risposte restituiscono JSON con campi specifici per la risorsa:

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

Risposte di errore

{
    "error": "Dataset not found"
}

API Dataset

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

Elenca dataset

GET /api/datasets

Parametri di query:

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

Risposta:

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

Ottieni dataset

GET /api/datasets/{datasetId}

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

Crea dataset

POST /api/datasets

Corpo:

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

Aggiorna dataset

PATCH /api/datasets/{datasetId}

Corpo (aggiornamento parziale):

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

Elimina dataset

DELETE /api/datasets/{datasetId}

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

Clona dataset

POST /api/datasets/{datasetId}/clone

Crea una copia del dataset con tutte le immagini e le etichette. Solo i dataset pubblici possono essere clonati. Richiede una sessione browser della piattaforma attiva — non disponibile tramite chiave API.

Corpo (tutti i campi facoltativi):

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

Esporta dataset

GET /api/datasets/{datasetId}/export

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

Parametri di query:

Risposta:

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

Crea versione dataset

POST /api/datasets/{datasetId}/export

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

Corpo della richiesta:

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

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

Risposta:

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

Aggiorna descrizione versione

PATCH /api/datasets/{datasetId}/export

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

Corpo della richiesta:

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

Risposta:

{
    "ok": true
}

Ottieni statistiche classe

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

Restituisce la distribuzione delle classi, la heatmap di posizione e le statistiche dimensionali. I risultati sono memorizzati nella cache per un massimo di 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
}

Ottieni modelli addestrati sul dataset

GET /api/datasets/{datasetId}/models

Restituisce i modelli che sono stati addestrati utilizzando questo dataset.

Risposta:

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

Annotazione automatica del dataset

POST /api/datasets/{datasetId}/predict

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

Corpo:

Ingestione dataset

POST /api/datasets/ingest

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

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]

Immagini dataset

Elenca immagini

GET /api/datasets/{datasetId}/images

Parametri di query:

Ottieni URL immagini firmate

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

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

Elimina immagine

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

Ottieni etichette immagine

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

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

Aggiorna etichette immagine

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

Corpo:

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

Operazioni in blocco sulle immagini

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

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

Elimina le immagini in blocco:

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

API Progetti

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

Elenca progetti

GET /api/projects

Parametri di query:

Ottieni progetto

GET /api/projects/{projectId}

Crea progetto

POST /api/projects

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

Aggiorna progetto

PATCH /api/projects/{projectId}

Elimina progetto

DELETE /api/projects/{projectId}

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

Clona progetto

POST /api/projects/{projectId}/clone

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

Icona 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 disponibili tramite API key.

API Modelli

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

Elenca modelli

GET /api/models

Parametri di query:

Elenca modelli completati

GET /api/models/completed

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

Ottieni modello

GET /api/models/{modelId}

Crea modello

POST /api/models

Corpo JSON:

Aggiorna modello

PATCH /api/models/{modelId}

Elimina modello

DELETE /api/models/{modelId}

Scarica file modello

GET /api/models/{modelId}/files

Restituisce URL di download firmati per i file modello.

Clona 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 API key.

Corpo:

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

Traccia download

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

Traccia le analisi di download del modello.

Esegui inferenza

POST /api/models/{modelId}/predict

Multipart Form:

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

Ottieni token di predizione

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

Warmup modello

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

API Addestramento

Avvia l'addestramento YOLO su GPU cloud (24 tipi di GPU da RTX 2000 Ada a B300) e monitora il progresso in tempo reale. Vedi la documentazione sull'addestramento 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]

Avvia addestramento

POST /api/training/start

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

Ottieni stato addestramento

GET /api/models/{modelId}/training

Restituisce lo stato attuale del job di addestramento, le metriche e il progresso per 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 API key).

Annulla addestramento

DELETE /api/models/{modelId}/training

Termina l'istanza di calcolo in esecuzione e segna il job come annullato. Richiede una sessione browser attiva sulla piattaforma — non disponibile tramite API key.

API Deployment

Distribuisci modelli su endpoint di inferenza dedicati con controlli di salute e monitoraggio. I nuovi deployment usano scale-to-zero per default e l'API accetta un oggetto resources opzionale. Vedi 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]

Elenca deployment

GET /api/deployments

Parametri di query:

Crea deployment

POST /api/deployments

Corpo:

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

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

Ottieni deployment

GET /api/deployments/{deploymentId}

Elimina deployment

DELETE /api/deployments/{deploymentId}

Avvia deployment

POST /api/deployments/{deploymentId}/start

Riprendi un deployment interrotto.

Ferma deployment

POST /api/deployments/{deploymentId}/stop

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

Controllo salute

GET /api/deployments/{deploymentId}/health

Restituisce lo stato di salute dell'endpoint di deployment.

Esegui inferenza su 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 instradato attraverso l'endpoint dedicato per una latenza inferiore.

Multipart Form:

Ottieni metriche

GET /api/deployments/{deploymentId}/metrics

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

Parametri di query:

Ottieni log

GET /api/deployments/{deploymentId}/logs

Parametri di query:

API di monitoraggio

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

API di esportazione

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

Elenco esportazioni

GET /api/exports

Parametri di query:

Crea esportazione

POST /api/exports

Corpo:

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

Formati supportati:

Ottieni stato esportazione

GET /api/exports/{exportId}

Annulla esportazione

DELETE /api/exports/{exportId}

Traccia download esportazione

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

API attività

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

Elenca attività

GET /api/activity

Parametri di query:

Segna eventi come letti

POST /api/activity/mark-seen

Corpo:

{
    "all": true
}

Oppure passa ID specifici:

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

Archivia eventi

POST /api/activity/archive

Corpo:

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

Oppure passa ID specifici:

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

API cestino

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

Elenca cestino

GET /api/trash

Parametri di query:

Ripristina elemento

POST /api/trash

Corpo:

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

Elimina elemento definitivamente

DELETE /api/trash

Corpo:

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

Svuota cestino

DELETE /api/trash/empty

Elimina definitivamente tutti gli elementi nel cestino.

API di fatturazione

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

Ottieni saldo

GET /api/billing/balance

Parametri di query:

Risposta:

{
    "creditsCents": 2500,
    "plan": "free",
    "cashBalance": 25,
    "creditBalance": 0,
    "reservedAmount": 0,
    "totalBalance": 25
}

Ottieni riepilogo utilizzo

GET /api/billing/usage-summary

Restituisce dettagli del piano, limiti e metriche di utilizzo.

Ottieni transazioni

GET /api/billing/transactions

Restituisce la cronologia delle transazioni (dalla più recente alla meno recente).

Parametri di query:

Crea sessione di checkout

POST /api/billing/checkout-session

Corpo:

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

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

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

Annulla o riprendi l'abbonamento

DELETE /api/billing/subscription-checkout

Annulla un abbonamento Pro al termine del periodo per impostazione predefinita. Invia {"resume": true} per riprendere una cancellazione già pianificata prima della fine del periodo di fatturazione.

Corpo:

{
    "resume": true
}

Ricarica Automatica

Aggiungi automaticamente crediti quando il saldo scende al di sotto di una soglia.

Ottieni configurazione ricarica automatica

GET /api/billing/auto-topup

Parametri di query:

Aggiorna configurazione ricarica automatica

PATCH /api/billing/auto-topup

Corpo:

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

Metodi di pagamento

Elenca metodi di pagamento

GET /api/billing/payment-methods

Crea setup intent

POST /api/billing/payment-methods/setup

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

Imposta metodo di pagamento predefinito

POST /api/billing/payment-methods/default

Corpo:

{
    "paymentMethodId": "pm_123"
}

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

Elimina metodo di pagamento

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

API di archiviazione

Controlla il dettaglio dell'utilizzo dello spazio di archiviazione per categoria (dataset, modelli, esportazioni) e visualizza gli elementi più grandi.

Ottieni informazioni archiviazione

GET /api/storage

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

API di caricamento

Carica i file direttamente nell'archiviazione cloud usando URL firmati per trasferimenti veloci e affidabili. Utilizza un flusso in due passaggi: ottieni un URL firmato, quindi carica il file. Vedi Data documentation.

Ottieni URL di caricamento firmato

POST /api/upload/signed-url

Richiedi un URL firmato per caricare un file direttamente nell'archiviazione cloud. L'URL firmato aggira 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/...",
    "objectPath": "images/abc123/my-image.jpg",
    "downloadUrl": "https://cdn.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

Completa caricamento

POST /api/upload/complete

Notifica alla piattaforma che un caricamento file è completo affinché possa iniziare l'elaborazione.

Corpo:

{
    "datasetId": "abc123",
    "objectPath": "datasets/abc123/images/my-image.jpg",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "size": 5242880
}

API delle chiavi API

Gestisci le tue chiavi API per l'accesso programmatico. Vedi API Keys documentation.

Elenca chiavi API

GET /api/api-keys

Crea chiave API

POST /api/api-keys

Corpo:

{
    "name": "training-server"
}

Elimina chiave API

DELETE /api/api-keys

Parametri di query:

Esempio:

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

API di team e membri

Crea aree di lavoro del team, invita membri e gestisci i ruoli per la collaborazione. Vedi Teams documentation.

Elenca team

GET /api/teams

Crea team

POST /api/teams/create

Corpo:

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

Elenca membri

GET /api/members

Restituisce i membri dell'area di lavoro corrente.

Invita membro

POST /api/members

Corpo:

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

Aggiorna ruolo del membro

PATCH /api/members/{userId}

Rimuovi membro

DELETE /api/members/{userId}

Trasferisci proprietà

POST /api/members/transfer-ownership

Inviti

Accetta invito

POST /api/invites/accept

Ottieni informazioni invito

GET /api/invites/info

Parametri di query:

Revoca invito

DELETE /api/invites/{inviteId}

Reinvia invito

POST /api/invites/{inviteId}/resend

API di esplorazione

Cerca e naviga tra dataset pubblici e progetti condivisi dalla community. Vedi Explore documentation.

Cerca contenuti pubblici

GET /api/explore/search

Parametri di query:

Dati barra laterale

GET /api/explore/sidebar

Restituisce contenuti curati per la barra laterale di Esplorazione.

API utente e impostazioni

Gestisci il tuo profilo, le chiavi API, l'utilizzo dello spazio di archiviazione e le impostazioni sulla privacy dei dati. Vedi Settings documentation.

Ottieni utente tramite nome utente

GET /api/users

Parametri di query:

Segui o smetti di seguire un utente

PATCH /api/users

Corpo:

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

Verifica disponibilità nome utente

GET /api/username/check

Parametri di query:

Impostazioni

GET /api/settings
POST /api/settings

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

Icona profilo

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

Carica o rimuovi avatar del profilo.

Onboarding

POST /api/onboarding

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

API GDPR

Richiedi un'esportazione di tutti i tuoi dati o elimina definitivamente il tuo account. Vedi Settings documentation.

Ottieni stato lavoro GDPR

GET /api/gdpr

Parametri di query:

Restituisce lo stato del lavoro. Per i lavori di esportazione completati, la risposta include un downloadUrl.

Avvia il flusso di esportazione o eliminazione

POST /api/gdpr

Corpo:

{
    "action": "export"
}

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

Facoltativo per gli spazi di lavoro del team:

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

Codici di errore

Integrazione Python

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

Installazione e configurazione

pip install ultralytics

Verifica l'installazione:

yolo check

Autenticazione

yolo settings api_key=YOUR_API_KEY

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

Invio alla piattaforma

Invia i risultati a un progetto della piattaforma:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

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

Cosa viene sincronizzato:

• Metriche di addestramento (tempo reale)
• Pesi finali del modello
• Grafici di validazione
• Output della console
• Metriche di sistema

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

Webhook

La piattaforma utilizza webhook interni per trasmettere in streaming le metriche di addestramento 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 addestramento e non sono destinati all'uso da parte delle applicazioni utente.

FAQ

Come posso impaginare 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"

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

Esistono librerie client API?

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

Come gestisco i limiti di frequenza?

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

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

Come trovo il mio ID modello o dataset?

Gli ID delle risorse vengono restituiti quando crei risorse tramite l'API. Puoi anche trovarli 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.