Riferimento 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

Panoramica 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

Autenticazione

La maggior parte delle richieste API richiede l'autenticazione tramite chiave API. Gli endpoint pubblici (che elencano dataset, progetti e modelli pubblici) supportano l'accesso in lettura anonimo senza una chiave.

Ottieni chiave API

1. Vai a Settings > Profile (sezione Chiavi API)
2. Clicca Create Key
3. Copia la chiave generata

Vedi Chiavi API per istruzioni dettagliate.

Header di Autorizzazione

Includi la tua chiave API in tutte le richieste:

Authorization: Bearer ul_your_api_key_here

Esempio

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

import requests

headers = {"Authorization": "Bearer ul_abc123..."}
response = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers=headers,
)
data = response.json()

const response = await fetch("https://platform.ultralytics.com/api/datasets", {
  headers: { Authorization: "Bearer ul_abc123..." },
});
const data = await response.json();

URL di Base

Tutti gli endpoint API utilizzano:

https://platform.ultralytics.com/api

Limiti di Frequenza

L'API utilizza un sistema di limitazione della frequenza a due livelli per proteggere dagli abusi mantenendo l'utilizzo legittimo illimitato:

• Per chiave API — Limiti applicati per chiave API sulle richieste autenticate
• Per IP — 100 richieste/min per indirizzo IP su tutti /api/* percorsi (si applica sia alle richieste autenticate che a quelle non autenticate)

Quando limitata, l'API restituisce 429 con metadati di ritentativo:

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ù stringenti per prevenire abusi, mentre le operazioni CRUD standard condividono un valore predefinito generoso:

Ogni categoria ha un contatore indipendente per chiave API. Ad esempio, l'esecuzione di 20 richieste di predict non influisce sulla tua quota predefinita di 100 richieste/min.

Endpoint dedicati (Illimitati)

Endpoint dedicati sono non soggetto a limiti di frequenza della chiave API. Quando si distribuisce un modello su un endpoint dedicato, le richieste a quell'URL dell'endpoint (ad esempio, https://predict-abc123.run.app/predict) accedono direttamente al tuo servizio dedicato senza limitazioni di frequenza dalla Piattaforma. Stai pagando per la potenza di calcolo, quindi ottieni un throughput illimitato fino alla configurazione di scalabilità del tuo endpoint.

Formato della Risposta

Risposte di successo

Le risposte restituiscono JSON con campi specifici della risorsa:

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

Risposte di Errore

{
    "error": "Invalid dataset ID"
}

API dei Dataset

Gestisci le raccolte di immagini etichettate per l'addestramento dei modelli YOLO.

Elenca i dataset

GET /api/datasets

Parametri di query:

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

import requests

resp = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 10},
)
for ds in resp.json()["datasets"]:
    print(f"{ds['name']}: {ds['imageCount']} images")

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

Recupera Dataset

GET /api/datasets/{datasetId}

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

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}

Elimina in modo soft il 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.

Corpo (tutti i campi opzionali):

{
    "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'ultima esportazione 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 una nuova istantanea di versione numerata del dataset. Solo per il proprietario. La versione acquisisce il conteggio corrente di immagini, classi e annotazioni, nonché la distribuzione degli split, quindi genera e memorizza un'esportazione NDJSON immutabile.

Corpo della Richiesta:

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

Tutti i campi sono opzionali. Il description il campo è 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 Classi

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

Restituisce la distribuzione delle classi, la heatmap di posizione e le statistiche sulle dimensioni. 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 set di dati

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 su immagini del dataset per generare automaticamente annotazioni. Utilizza un modello selezionato per predire etichette per immagini non annotate.

Corpo:

Ingestione del Dataset

POST /api/datasets/ingest

Crea un job di ingestione del dataset per elaborare i file ZIP caricati contenenti immagini ed etichette.

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

Immagini del Dataset

Elenca Immagini

GET /api/datasets/{datasetId}/images

Parametri di query:

Ottieni URL di Immagini Firmati

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 Immagini

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

Operazioni su immagini in blocco

Spostare le immagini tra gli split (addestramento/validazione/test) all'interno di un dataset:

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

Elimina immagini in blocco:

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

API dei Progetti

Gestisci gli spazi di lavoro di addestramento che raggruppano i modelli.

Elenca Progetti

GET /api/projects

Parametri di query:

Recupera Progetto

GET /api/projects/{projectId}

Crea progetto

POST /api/projects

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

resp = requests.post(
    "https://platform.ultralytics.com/api/projects",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"name": "my-project", "slug": "my-project", "description": "Detection experiments"},
)
project_id = resp.json()["projectId"]

Aggiorna progetto

PATCH /api/projects/{projectId}

Elimina progetto

DELETE /api/projects/{projectId}

Elimina in modo soft il progetto (spostato nel cestino).

Clona Progetto

POST /api/projects/{projectId}/clone

Icona del Progetto

Carica un'icona di progetto (form multipart con file immagine):

POST /api/projects/{projectId}/icon

Rimuovi l'icona del progetto:

DELETE /api/projects/{projectId}/icon

API dei Modelli

Gestisci i checkpoint dei modelli addestrati all'interno dei progetti.

Elenca Modelli

GET /api/models

Parametri di query:

Elenca Modelli Completati

GET /api/models/completed

Restituisce i modelli che hanno completato l'addestramento (per l'utilizzo in selettori di modelli e deployment).

Recupera 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 i File del Modello

GET /api/models/{modelId}/files

Restituisce URL di download firmati per i file del modello.

Clona Modello

POST /api/models/{modelId}/clone

Clona un modello pubblico in uno dei tuoi progetti.

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 dei download dei modelli.

Esegui inferenza

POST /api/models/{modelId}/predict

Formato Multipart:

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

with open("image.jpg", "rb") as f:
    resp = requests.post(
        f"https://platform.ultralytics.com/api/models/{model_id}/predict",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": f},
        data={"conf": 0.5},
    )
results = resp.json()["images"][0]["results"]

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

Ottieni un token di breve durata per le richieste di predizione dirette. Il token bypassa il proxy API per un'inferenza a latenza inferiore dalle applicazioni lato client.

Modello di warmup

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

Pre-caricare un modello per una prima inferenza più rapida. Chiamare questa funzione prima di eseguire le previsioni per evitare ritardi sulla richiesta iniziale.

API di Addestramento

Avvia, monitora e annulla i job di addestramento su 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 l'addestramento

POST /api/training/start

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

resp = requests.post(
    "https://platform.ultralytics.com/api/training/start",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "modelId": "MODEL_ID",
        "projectId": "PROJECT_ID",
        "gpuType": "rtx-4090",
        "trainArgs": {
            "model": "yolo11n.pt",
            "data": "ul://username/datasets/my-dataset",
            "epochs": 100,
            "imgsz": 640,
            "batch": 16,
        },
    },
)

Recupera Stato Addestramento

GET /api/models/{modelId}/training

Restituisce lo stato corrente del lavoro di addestramento, le metriche e l'avanzamento per un modello.

Annulla Addestramento

DELETE /api/models/{modelId}/training

Termina l'istanza di calcolo in esecuzione e contrassegna il lavoro come annullato.

API di Distribuzione

Crea e gestisci endpoint di inferenza dedicati.

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 Distribuzioni

GET /api/deployments

Parametri di query:

Crea Distribuzione

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.

Recupera Distribuzione

GET /api/deployments/{deploymentId}

Elimina Distribuzione

DELETE /api/deployments/{deploymentId}

Avvia Distribuzione

POST /api/deployments/{deploymentId}/start

Riprendi un deployment interrotto.

Ferma Distribuzione

POST /api/deployments/{deploymentId}/stop

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

Controllo dello stato

GET /api/deployments/{deploymentId}/health

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

Esegui l'Inferenza in Fase di 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.

Formato Multipart:

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

Recupera Log

GET /api/deployments/{deploymentId}/logs

Parametri di query:

API di Monitoraggio

Metriche Aggregate

GET /api/monitoring

Restituisce metriche aggregate per tutti i deployment utente: richieste totali, deployment attivi, tasso di errore e latenza media.

API di Esportazione

Convertire i modelli in formati ottimizzati per la distribuzione edge.

Elenca Esportazioni

GET /api/exports

Parametri di query:

Crea Esportazione

POST /api/exports

Corpo:

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

resp = requests.post(
    "https://platform.ultralytics.com/api/exports",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"modelId": "MODEL_ID", "format": "onnx"},
)
export_id = resp.json()["exportId"]

Formati supportati:

Recupera Stato Esportazione

GET /api/exports/{exportId}

Annulla Esportazione

DELETE /api/exports/{exportId}

Traccia Download Esportazione

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

API di Attività

Track e gestisci gli eventi di attività per il tuo account.

Elenca Attività

GET /api/activity

Parametri di query:

Contrassegna Eventi come Visti

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 del Cestino

Gestisci le risorse eliminate temporaneamente (conservazione di 30 giorni).

Elenca Cestino

GET /api/trash

Parametri di query:

Ripristina Elemento

POST /api/trash

Corpo:

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

Elimina Elemento Permanentemente

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

Gestisci crediti, abbonamenti e metodi di pagamento.

Recupera Saldo

GET /api/billing/balance

Parametri di query:

Risposta:

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

Recupera Riepilogo Utilizzo

GET /api/billing/usage-summary

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

Ottieni Transazioni

GET /api/billing/transactions

Restituisce la cronologia delle transazioni (dal più recente al 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'upgrade all'abbonamento Pro.

Corpo:

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

Crea Sessione Portale

POST /api/billing/portal-session

Restituisce l'URL al portale di fatturazione per la gestione degli abbonamenti.

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 di 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 Intento di Configurazione

POST /api/billing/payment-methods/setup

Restituisce un client secret per l'aggiunta di 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

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

Ricalcola Spazio di Archiviazione

POST /api/storage

Attiva un ricalcolo dell'utilizzo dello spazio di archiviazione.

API di caricamento

I caricamenti diretti di file utilizzano un flusso di URL firmati in due fasi.

Ottieni URL di Caricamento Firmato

POST /api/upload/signed-url

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

Caricamento completato

POST /api/upload/complete

Notificare alla piattaforma che un caricamento di 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

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 $API_KEY" \
  "https://platform.ultralytics.com/api/api-keys?keyId=KEY_ID"

API di Team e Membri

Gestisci la collaborazione nello spazio di lavoro con team, membri e inviti.

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 dello spazio di lavoro corrente.

Invita un membro

POST /api/members

Corpo:

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

Aggiorna ruolo 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 Info Invito

GET /api/invites/info

Parametri di query:

Revoca invito

DELETE /api/invites/{inviteId}

Reinvia Invito

POST /api/invites/{inviteId}/resend

Esplora API

Cerca Contenuti Pubblici

GET /api/explore/search

Parametri di query:

Dati della barra laterale

GET /api/explore/sidebar

Restituisce contenuti curati per la barra laterale Esplora.

API Utente e Impostazioni

Ottieni Utente per Nome Utente

GET /api/users

Parametri di query:

Segui o Smetti di Seguire 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, biografia, link social, ecc.).

Icona del profilo

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

Carica o rimuovi l'avatar del profilo.

Onboarding

POST /api/onboarding

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

API GDPR

Endpoint di conformità GDPR per l'esportazione e l'eliminazione dei dati.

Ottieni Stato Job 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"
}

Opzionale per gli spazi di lavoro del team:

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

Codici di errore

Python

Per una più facile integrazione, utilizzare il pacchetto Python di Ultralytics che gestisce automaticamente l'autenticazione, i caricamenti e lo streaming di metriche in tempo reale.

Installazione e configurazione

pip install ultralytics

Verifica l'installazione:

yolo check

Autenticazione

yolo settings api_key=YOUR_API_KEY

export ULTRALYTICS_API_KEY=YOUR_API_KEY

from ultralytics import settings

settings.api_key = "YOUR_API_KEY"

Utilizzo dei dataset della piattaforma

Set di dati di riferimento con ul:// URI:

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

# Train on your Platform dataset
model.train(
    data="ul://your-username/your-dataset",
    epochs=100,
    imgsz=640,
)

Formato URI:

Spingere verso la piattaforma

Invia i risultati a un progetto della piattaforma:

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

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

Cosa si sincronizza:

• Metriche di allenamento (in tempo reale)
• Pesi del modello finale
• Grafici di convalida
• 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 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

Modello di esportazione:

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

Convalida:

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

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

Webhook

I webhook notificano il tuo server degli eventi della Piattaforma tramite callback HTTP POST:

FAQ

Come si paginano risultati di grandi dimensioni?

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

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

Gli endpoint Attività e Cestino supportano anche un page parametro per la paginazione basata su pagina:

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

L'endpoint di ricerca Esplora 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 convenienza che aggiunge funzionalità come lo streaming di metriche in tempo reale e il caricamento automatico dei modelli.

Esistono librerie client API?

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

Come si gestiscono i limiti di frequenza?

Utilizzare il Retry-After header dalla risposta 429 per attendere il tempo corretto:

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 si trova l'ID del mio modello o dataset?

Gli ID delle risorse vengono restituiti quando si creano risorse tramite l'API. È possibile trovarli anche nell'URL della piattaforma:

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

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

📅 Creato 2 mesi fa ✏️ Aggiornato 5 giorni fa

Commenti