Zum Inhalt springen

REST API

Ultralytics bietet eine umfassende REST API den programmatischen Zugriff auf Datensätze, Modelle, Schulungen und Bereitstellungen.

Schnellstart

# 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

Authentifizierung

Alle API-Anfragen erfordern eine Authentifizierung über einen API-Schlüssel.

API-Schlüssel abrufen

  1. Gehen Sie zu Einstellungen > API-Schlüssel
  2. Klicken Sie auf „Schlüssel erstellen“
  3. Kopieren Sie den generierten Schlüssel.

Ausführliche Anweisungen finden Sie unter API-Schlüssel.

Autorisierungs-Header

Fügen Sie Ihren API-Schlüssel in alle Anfragen ein:

Authorization: Bearer ul_your_api_key_here

Beispiel

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

Basis-URL

Alle API-Endpunkte verwenden:

https://platform.ultralytics.com/api

Ratenbegrenzungen

PlanAnfragen/MinuteAnfragen/Tag
Kostenlos601,000
Pro30050,000
UnternehmenBenutzerdefiniertBenutzerdefiniert

Rate-Limit-Header sind in den Antworten enthalten:

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

Antwortformat

Alle Antworten sind JSON:

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

Fehlerantworten

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

Datensätze-API

Datensätze auflisten

GET /api/datasets

Abfrageparameter:

ParameterTypBeschreibung
pageintSeitenzahl (Standard: 1)
limitintElemente pro Seite (Standard: 20)
taskZeichenfolgeNach Aufgabentyp filtern

Antwort:

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

Datensatz abrufen

GET /api/datasets/{datasetId}

Datensatz erstellen

POST /api/datasets

Körper:

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

Datensatz löschen

DELETE /api/datasets/{datasetId}

Datensatz exportieren

POST /api/datasets/{datasetId}/export

Gibt die Download-URL im NDJSON-Format zurück.

Projekte-API

Projekte auflisten

GET /api/projects

Projekt abrufen

GET /api/projects/{projectId}

Projekt erstellen

POST /api/projects

Körper:

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

Projekt löschen

DELETE /api/projects/{projectId}

Modelle-API

Modelle auflisten

GET /api/models

Abfrageparameter:

ParameterTypBeschreibung
projectIdZeichenfolgeNach Projekt filtern
taskZeichenfolgeNach Aufgabentyp filtern

Modell erhalten

GET /api/models/{modelId}

Modell hochladen

POST /api/models

Mehrteiliges Formular:

FeldTypBeschreibung
fileDatei definiertModell .pt-Datei
projectIdZeichenfolgeZielprojekt
nameZeichenfolgeModellname

Modell löschen

DELETE /api/models/{modelId}

Modell herunterladen

GET /api/models/{modelId}/files

Gibt signierte Download-URLs für Modelldateien zurück.

Inferenz ausführen

POST /api/models/{modelId}/predict

Mehrteiliges Formular:

FeldTypBeschreibung
fileDatei definiertBilddatei
confSchwimmerKonfidenzschwelle
iouSchwimmerIoU

Antwort:

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

Schulungs-API

Training starten

POST /api/training/start

Körper:

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

Trainingsstatus abrufen

GET /api/models/{modelId}/training

Training abbrechen

DELETE /api/models/{modelId}/training

Bereitstellungs-API

Liste der Bereitstellungen

GET /api/deployments

Abfrageparameter:

ParameterTypBeschreibung
modelIdZeichenfolgeNach Modell filtern

Bereitstellung erstellen

POST /api/deployments

Körper:

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

Bereitstellung erhalten

GET /api/deployments/{deploymentId}

Bereitstellung starten

POST /api/deployments/{deploymentId}/start

Bereitstellung stoppen

POST /api/deployments/{deploymentId}/stop

Bereitstellung löschen

DELETE /api/deployments/{deploymentId}

Metriken abrufen

GET /api/deployments/{deploymentId}/metrics

Protokolle abrufen

GET /api/deployments/{deploymentId}/logs

Abfrageparameter:

ParameterTypBeschreibung
severityZeichenfolgeINFO, WARNUNG, FEHLER
limitintAnzahl der Einträge

Export-API

Liste exportieren

GET /api/exports

Export erstellen

POST /api/exports

Körper:

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

Unterstützte Formate:

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

Exportstatus abrufen

GET /api/exports/{exportId}

Aktivitäts-API

Verfolgen und verwalten Sie Aktivitätsereignisse für Ihr Konto.

Aktivität auflisten

GET /api/activity

Abfrageparameter:

ParameterTypBeschreibung
startDateZeichenfolgeFilter nach Datum (ISO)
endDateZeichenfolgeFilter bis heute (ISO)
searchZeichenfolgeSuche in Ereignismeldungen

Gesehene Ereignisse markieren

POST /api/activity/mark-seen

Archiv Veranstaltungen

POST /api/activity/archive

Müll-API

Vorläufig gelöschte Ressourcen verwalten (30 Tage Aufbewahrungsfrist).

Liste Papierkorb

GET /api/trash

Element wiederherstellen

POST /api/trash

Körper:

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

Papierkorb leeren

POST /api/trash/empty

Löscht alle Elemente im Papierkorb dauerhaft.

Abrechnungs-API

Verwalten Sie Credits und Abonnements.

Balance finden

GET /api/billing/balance

Antwort:

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

Mikro-USD

Alle Beträge sind zur genauen Abrechnung in Mikro-USD angegeben (1.000.000 = 1,00 $).

Nutzungsübersicht abrufen

GET /api/billing/usage-summary

Gibt Details zum Tarif, Limits und Nutzungsmetriken zurück.

Checkout-Sitzung erstellen

POST /api/billing/checkout-session

Körper:

{
    "amount": 25
}

Erstellt eine Stripe-Checkout-Sitzung für Kreditkäufe (5 bis 1000 US-Dollar).

Abonnement-Kasse erstellen

POST /api/billing/subscription-checkout

Erstellt eine Stripe-Checkout-Sitzung für das Pro-Abonnement.

Portal-Sitzung erstellen

POST /api/billing/portal-session

Gibt die URL zum Stripe-Abrechnungsportal für die Verwaltung von Abonnements zurück.

Zahlungsverlauf abrufen

GET /api/billing/payments

Gibt eine Liste der Zahlungsvorgänge von Stripe zurück.

Speicher-API

Speicherinformationen abrufen

GET /api/storage

Antwort:

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

DSGVO-API

DSGVO-konforme Endpunkte für Datenexport und -löschung.

Exportieren/Löschen von Kontodaten

POST /api/gdpr

Körper:

{
    "action": "export"
}
AktionBeschreibung
exportAlle Kontodaten herunterladen
deleteKonto und alle Daten löschen

Unumkehrbare Handlung

Die Löschung des Kontos ist endgültig und kann nicht rückgängig gemacht werden. Alle Daten, Modelle und Bereitstellungen werden gelöscht.

API-Schlüssel API

API-Schlüssel auflisten

GET /api/api-keys

API-Schlüssel erstellen

POST /api/api-keys

Körper:

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

API-Schlüssel löschen

DELETE /api/api-keys/{keyId}

Fehlercodes

CodeBeschreibung
UNAUTHORIZEDUngültiger oder fehlender API-Schlüssel
FORBIDDENUnzureichende Berechtigungen
NOT_FOUNDRessource nicht gefunden
VALIDATION_ERRORUngültige Anforderungsdaten
RATE_LIMITEDZu viele Anfragen
INTERNAL_ERRORServerfehler

SDK-Unterstützung

Verwenden Sie für eine einfachere Integration das Ultralytics Python .

Anforderungen an die Paketversion

Für die Plattformintegration ist ultralytics>= 8.4.0 erforderlich. Niedrigere Versionen funktionieren NICHT mit der Plattform.

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)

Webhooks

Webhooks benachrichtigen Ihren Server über Plattformereignisse:

VeranstaltungBeschreibung
training.startedAusbildung begonnen
training.epochEpoche abgeschlossen
training.completedTraining beendet
training.failedTraining fehlgeschlagen
export.completedExportbereit

Die Einrichtung von Webhooks ist in den Enterprise-Tarifen verfügbar.

FAQ

Wie kann ich umfangreiche Ergebnisse paginieren?

Verwenden Sie page und limit Parameter:

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

Kann ich die API ohne SDK verwenden?

Ja, alle Funktionen sind über REST verfügbar. Das SDK ist ein praktischer Wrapper.

Gibt es API-Client-Bibliotheken?

Derzeit verwenden Sie das Ultralytics Python oder stellen direkte HTTP-Anfragen. Offizielle Client-Bibliotheken für andere Sprachen sind in Planung.

Wie gehe ich mit Ratenbeschränkungen um?

Exponentielles Backoff implementieren:

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


📅 Erstellt vor 0 Tagen ✏️ Aktualisiert vor 0 Tagen
glenn-jocher

Kommentare