Vai al contenuto

REST API

Ultralytics offre REST API completa REST API l'accesso programmatico a set di dati, modelli, formazione e implementazioni.

Avvio rapido

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

# Run inference on a model
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.jpg" \
  https://platform.ultralytics.com/api/models/MODEL_ID/predict

Autenticazione

Tutte le richieste API richiedono l'autenticazione tramite chiave API.

Ottieni chiave API

  1. Vai su Impostazioni > Chiavi API
  2. Fai clic su Crea chiave
  3. Copia la chiave generata

Per istruzioni dettagliate, consultare Chiavi API.

Intestazione 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

URL di base

Tutti gli endpoint API utilizzano:

https://platform.ultralytics.com/api

Limiti di velocità

PianoRichieste/MinutoRichieste/giorno
Gratuito601,000
Pro30050,000
ImpresaPersonalizzatoPersonalizzato

Le intestazioni relative al limite di velocità sono incluse nelle risposte:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1640000000

Formato di risposta

Tutte le risposte sono in formato JSON:

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

Risposte di errore

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid dataset ID",
    "details": { ... }
  }
}

API dei set di dati

Elenca i dataset

GET /api/datasets

Parametri di query:

ParametroTipoDescrizione
pageintNumero di pagina (impostazione predefinita: 1)
limitintElementi per pagina (impostazione predefinita: 20)
taskstringaFiltra per tipo di attività

Risposta:

{
    "success": true,
    "data": [
        {
            "id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "visibility": "private",
            "createdAt": "2024-01-15T10:00:00Z"
        }
    ]
}

Ottieni il set di dati

GET /api/datasets/{datasetId}

Crea set di dati

POST /api/datasets

Corpo:

{
    "name": "my-dataset",
    "task": "detect",
    "description": "A custom detection dataset"
}

Elimina dataset

DELETE /api/datasets/{datasetId}

Esporta set di dati

POST /api/datasets/{datasetId}/export

Restituisce l'URL di download in formato NDJSON.

API dei progetti

Elenco progetti

GET /api/projects

Ottieni il progetto

GET /api/projects/{projectId}

Crea progetto

POST /api/projects

Corpo:

{
    "name": "my-project",
    "description": "Detection experiments"
}

Elimina progetto

DELETE /api/projects/{projectId}

API dei modelli

Elenco modelli

GET /api/models

Parametri di query:

ParametroTipoDescrizione
projectIdstringaFiltra per progetto
taskstringaFiltra per tipo di attività

Ottieni il modello

GET /api/models/{modelId}

Carica modello

POST /api/models

Modulo multiparte:

CampoTipoDescrizione
filefileModello file .pt
projectIdstringaProgetto target
namestringaNome del modello

Elimina modello

DELETE /api/models/{modelId}

Scarica il modello

GET /api/models/{modelId}/files

Restituisce gli URL di download firmati per i file modello.

Esegui inferenza

POST /api/models/{modelId}/predict

Modulo multiparte:

CampoTipoDescrizione
filefileFile immagine
confgalleggiareSoglia di confidenza
iougalleggiareIoU

Risposta:

{
    "success": true,
    "predictions": [
        {
            "class": "person",
            "confidence": 0.92,
            "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
        }
    ]
}

API di formazione

Avvia l'addestramento

POST /api/training/start

Corpo:

{
    "modelId": "model_abc123",
    "datasetId": "dataset_xyz789",
    "epochs": 100,
    "imageSize": 640,
    "gpuType": "rtx-4090"
}

Ottieni lo stato di allenamento

GET /api/models/{modelId}/training

Annulla formazione

DELETE /api/models/{modelId}/training

API di distribuzione

Elenco delle distribuzioni

GET /api/deployments

Parametri di query:

ParametroTipoDescrizione
modelIdstringaFiltra per modello

Crea distribuzione

POST /api/deployments

Corpo:

{
    "modelId": "model_abc123",
    "region": "us-central1",
    "minInstances": 0,
    "maxInstances": 10
}

Ottieni la distribuzione

GET /api/deployments/{deploymentId}

Avvia distribuzione

POST /api/deployments/{deploymentId}/start

Interrompi distribuzione

POST /api/deployments/{deploymentId}/stop

Elimina distribuzione

DELETE /api/deployments/{deploymentId}

Ottieni metriche

GET /api/deployments/{deploymentId}/metrics

Ottieni i registri

GET /api/deployments/{deploymentId}/logs

Parametri di query:

ParametroTipoDescrizione
severitystringaINFO, AVVISO, ERRORE
limitintNumero di voci

API di esportazione

Elenco esportazioni

GET /api/exports

Crea esportazione

POST /api/exports

Corpo:

{
    "modelId": "model_abc123",
    "format": "onnx"
}

Formati supportati:

onnx, torchscript, openvino, tensorrt, coreml, tflite, saved_model, graphdef, paddle, ncnn, edgetpu, tfjs, mnn, rknn, imx, axelera, executorch

Ottieni lo stato dell'esportazione

GET /api/exports/{exportId}

API Attività

Traccia e gestisci gli eventi relativi alle attività del tuo account.

Elenco attività

GET /api/activity

Parametri di query:

ParametroTipoDescrizione
startDatestringaFiltra per data (ISO)
endDatestringaFiltro per data (ISO)
searchstringaCerca nei messaggi degli eventi

Contrassegna eventi visti

POST /api/activity/mark-seen

Archivio eventi

POST /api/activity/archive

API dei rifiuti

Gestisci le risorse eliminate in modo temporaneo (conservazione per 30 giorni).

Elenco cestino

GET /api/trash

Ripristina elemento

POST /api/trash

Corpo:

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

Svuota cestino

POST /api/trash/empty

Elimina definitivamente tutti gli elementi nel cestino.

API di fatturazione

Gestisci crediti e abbonamenti.

Ottieni equilibrio

GET /api/billing/balance

Risposta:

{
    "success": true,
    "data": {
        "cashBalance": 5000000,
        "creditBalance": 20000000,
        "reservedAmount": 0,
        "totalBalance": 25000000
    }
}

Micro-USD

Tutti gli importi sono espressi in micro-USD (1.000.000 = 1,00 $) per una contabilità precisa.

Ottieni il riepilogo dell'utilizzo

GET /api/billing/usage-summary

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

Crea sessione di checkout

POST /api/billing/checkout-session

Corpo:

{
    "amount": 25
}

Crea una sessione di pagamento Stripe per acquisti con carta di credito (da 5 a 1000 dollari).

Crea checkout abbonamento

POST /api/billing/subscription-checkout

Crea una sessione di checkout Stripe per l'abbonamento Pro.

Crea sessione portale

POST /api/billing/portal-session

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

Ottieni la cronologia dei pagamenti

GET /api/billing/payments

Restituisce l'elenco delle transazioni di pagamento da Stripe.

API di archiviazione

Ottieni informazioni sull'archiviazione

GET /api/storage

Risposta:

{
    "success": true,
    "data": {
        "used": 1073741824,
        "limit": 107374182400,
        "percentage": 1.0
    }
}

API GDPR

Endpoint conformi al GDPR per l'esportazione e la cancellazione dei dati.

Esporta/Elimina dati account

POST /api/gdpr

Corpo:

{
    "action": "export"
}
AzioneDescrizione
exportScarica tutti i dati dell'account
deleteElimina account e tutti i dati

Azione irreversibile

La cancellazione dell'account è definitiva e non può essere annullata. Tutti i dati, i modelli e le distribuzioni saranno cancellati.

Chiavi API API

Elenco chiavi API

GET /api/api-keys

Crea chiave API

POST /api/api-keys

Corpo:

{
    "name": "training-server",
    "scopes": ["training", "models"]
}

Elimina chiave API

DELETE /api/api-keys/{keyId}

Codici di errore

CodiceDescrizione
UNAUTHORIZEDChiave API non valida o mancante
FORBIDDENAutorizzazioni insufficienti
NOT_FOUNDRisorsa non trovata
VALIDATION_ERRORDati della richiesta non validi
RATE_LIMITEDTroppe richieste
INTERNAL_ERRORErrore del server

Supporto SDK

Per una più facile integrazione, utilizza ilPython Ultralytics .

Requisiti relativi alla versione del pacchetto

L'integrazione con la piattaforma richiede ultralytics>= 8.4.0. Le versioni precedenti NON funzionano con la piattaforma.

pip install "ultralytics>=8.4.0"

import os

from ultralytics import YOLO

# Set API key
os.environ["ULTRALYTICS_API_KEY"] = "ul_your_key"

# Train with Platform integration
model = YOLO("yolo11n.pt")
model.train(data="ul://username/datasets/my-dataset", project="username/my-project", name="experiment-1", epochs=100)

Webhook

I webhook notificano al tuo server gli eventi della piattaforma:

EventoDescrizione
training.startedInizio del lavoro di formazione
training.epochEpoca completata
training.completedFormazione completata
training.failedFormazione non riuscita
export.completedPronto per l'esportazione

La configurazione dei webhook è disponibile nei piani Enterprise.

FAQ

Come posso impaginare risultati di grandi dimensioni?

Usa page e limit parametri:

GET /api/datasets?page=2 &
limit=50

Posso usare l'API senza un SDK?

Sì, tutte le funzionalità sono disponibili tramite REST. L'SDK è un wrapper di comodità.

Esistono librerie client API?

Attualmente, utilizza ilPython Ultralytics o effettua richieste HTTP dirette. Sono in programma librerie client ufficiali per altri linguaggi.

Come gestisco i limiti di velocità?

Implementare il backoff esponenziale:

import time


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


📅 Creato 0 giorni fa ✏️ Aggiornato 0 giorni fa
glenn-jocher

Commenti