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 (elenco di set di dati, progetti e modelli pubblici) supportano l'accesso in lettura anonimo senza 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 velocità a due livelli per proteggere dagli abusi, mantenendo al contempo illimitato l'utilizzo legittimo:

• 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 viene limitata, l'API restituisce 429 con metadati di riprova:

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

Limiti per chiave API

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

Ogni categoria ha un contatore indipendente per chiave API. Ad esempio, effettuare 20 richieste di previsione non influisce sulla tua quota predefinita di 100 richieste al minuto.

Endpoint dedicati (illimitati)

Endpoint dedicati sono non soggetto ai limiti di frequenza delle chiavi APIQuando si distribuisce un modello su un endpoint dedicato, le richieste all'URL di tale endpoint (ad esempio, https://predict-abc123.run.app/predict) vai direttamente al tuo servizio dedicato senza limitazioni di velocità dalla piattaforma. Paghi 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 delle risorse:

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

Risposte di Errore

{
    "error": "Invalid dataset ID"
}

API dei Dataset

Gestisci raccolte di immagini etichettate per l'addestramento 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 set di dati, 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 set di dati

PATCH /api/datasets/{datasetId}

Corpo (aggiornamento parziale):

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

Elimina dataset

DELETE /api/datasets/{datasetId}

Elimina in modo non definitivo il set di dati (spostato nel cestino, recuperabile per 30 giorni).

Clona Dataset

POST /api/datasets/{datasetId}/clone

Crea una copia del set di dati con tutte le immagini e le etichette. Solo i set di dati pubblici possono essere clonati.

Corpo (tutti i campi sono 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 il file di esportazione del set di dati.

Risposta:

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

Ottieni statistiche sulla classe

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

Restituisce la distribuzione delle classi, la mappa termica della posizione e le statistiche dimensionali. I risultati vengono 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 set di dati.

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 set di dati

POST /api/datasets/{datasetId}/predict

Esegui YOLO sulle immagini del set di dati per generare automaticamente le annotazioni. Utilizza un modello selezionato per prevedere le etichette per le immagini non annotate.

Corpo:

Acquisizione dei dati

POST /api/datasets/ingest

Crea un processo di acquisizione dei dati 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 set di dati

Elenco immagini

GET /api/datasets/{datasetId}/images

Parametri di query:

Ottieni URL delle immagini firmate

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

Ottieni URL firmati per un batch di hash di immagini (da visualizzare nel browser).

Elimina immagine

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

Ottieni etichette immagine

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

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

Aggiorna etichette immagini

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 le divisioni (train/val/test) all'interno di un set di dati:

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

Eliminazione di immagini in blocco:

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

API dei Progetti

Gestisci gli spazi di lavoro di formazione 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"]

Aggiornamento progetto

PATCH /api/projects/{projectId}

Elimina progetto

DELETE /api/projects/{projectId}

Elimina temporaneamente il progetto (spostato nel cestino).

Progetto Clone

POST /api/projects/{projectId}/clone

Icona del progetto

Carica l'icona del progetto (modulo multiparte 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:

Elenco modelli completati

GET /api/models/completed

Restituisce i modelli che hanno completato l'addestramento (da utilizzare nei selettori di modelli e nell'implementazione).

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

GET /api/models/{modelId}/files

Restituisce URL di download firmati per i file del modello.

Modello clone

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

Scarica traccia

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

Monitorare le analisi relative al 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 Predict

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

Ottieni un token a breve durata per richieste di previsione diretta. Il token bypassa il proxy API per un'inferenza a bassa latenza dalle applicazioni lato client.

Modello di riscaldamento

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

Precaricare un modello per una prima inferenza più rapida. Richiamare questa funzione prima di eseguire le previsioni per evitare ritardi nella richiesta iniziale.

API di Addestramento

Avvia, monitora e annulla i processi di formazione 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 attuale del processo di addestramento, le metriche e lo stato di avanzamento di 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 una distribuzione interrotta.

Ferma Distribuzione

POST /api/deployments/{deploymentId}/stop

Sospendi una distribuzione in corso (interrompe la fatturazione).

Controllo dello stato

GET /api/deployments/{deploymentId}/health

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

Esegui inferenza sulla distribuzione

POST /api/deployments/{deploymentId}/predict

Invia un'immagine direttamente a un endpoint di distribuzione per l'inferenza. Funzionalmente equivalente alla previsione del modello, ma instradato attraverso l'endpoint dedicato per una minore latenza.

Formato Multipart:

Recupera Metriche

GET /api/deployments/{deploymentId}/metrics

Restituisce il conteggio delle richieste, la latenza e le metriche relative al 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 relative a tutte le distribuzioni degli utenti: richieste totali, distribuzioni attive, tasso di errore e latenza media.

API di Esportazione

Converti i modelli in formati ottimizzati per l'implementazione 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 Esporta Scarica

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 passare ID specifici:

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

Archivia Eventi

POST /api/activity/archive

Corpo:

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

Oppure passare 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 definitivamente l'elemento

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 (la più recente per prima).

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 a credito.

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

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 ricarica automatica

PATCH /api/billing/auto-topup

Corpo:

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

Metodi di pagamento

Elenco dei metodi di pagamento

GET /api/billing/payment-methods

Crea intento di configurazione

POST /api/billing/payment-methods/setup

Restituisce un segreto client 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

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 lo spazio di archiviazione

POST /api/storage

Avvia un ricalcolo dell'utilizzo dello spazio di archiviazione.

API di caricamento

Il caricamento diretto dei file utilizza un flusso URL firmato in due fasi.

Ottieni URL di caricamento firmato

POST /api/upload/signed-url

Richiedi un URL firmato per caricare un file direttamente sul cloud storage. L'URL firmato bypassa il server API per il trasferimento 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 completo

POST /api/upload/complete

Notifica alla piattaforma che il caricamento del file è stato completato, in modo che 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 Team e membri

Gestisci la collaborazione nell'area di lavoro con team, membri e inviti.

Elenco squadre

GET /api/teams

Crea team

POST /api/teams/create

Corpo:

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

Elenco membri

GET /api/members

Restituisce i membri dell'area 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}

Trasferimento di proprietà

POST /api/members/transfer-ownership

Inviti

Accetta invito

POST /api/invites/accept

Ottieni informazioni sull'invito

GET /api/invites/info

Parametri di query:

Revoca invito

DELETE /api/invites/{inviteId}

Invia nuovamente l'invito

POST /api/invites/{inviteId}/resend

Esplora l'API

Cerca contenuti pubblici

GET /api/explore/search

Parametri di query:

Dati della barra laterale

GET /api/explore/sidebar

Restituisce contenuti selezionati 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 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, biografia, link social, ecc.).

Icona 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 lo stato di lavoro GDPR

GET /api/gdpr

Parametri di query:

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

Avvia esportazione o elimina flusso

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, utilizza ilPython 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

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 al tuo server gli 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 il numero di risultati restituiti per ogni richiesta:

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

Gli endpoint Activity e Trash supportano anche un page parametro per l'impaginazione basata sulle pagine:

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

L'endpoint Explore Search utilizza offset invece di page, con una dimensione fissa della pagina 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. Python è un wrapper di comodità 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 intestazione dalla risposta 429 per attendere il tempo necessario:

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 posso trovare l'ID del mio modello o set di dati?

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

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

Utilizza gli endpoint dell'elenco per effettuare ricerche per nome o filtrare per progetto.

📅 Creato 1 mese fa ✏️ Aggiornato 4 giorni fa

Commenti