Link to this sectionREST API Referenz#

Ultralytics Platform bietet eine umfassende REST API für den programmgesteuerten Zugriff auf Datensätze, Modelle, Training und Deployments.

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

Link to this sectionAPI-Übersicht#

Die API ist um die zentralen Plattform-Ressourcen herum organisiert:

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

Link to this sectionAuthentifizierung#

Ressourcen-APIs wie Datensätze, Projekte, Modelle, Training, Exporte und Vorhersagen verwenden API-Key-Authentifizierung. Öffentliche Endpunkte (zum Auflisten öffentlicher Datensätze, Projekte und Modelle) unterstützen anonymen Lesezugriff ohne Key. Kontoorientierte Routen – einschließlich Aktivität, Einstellungen, Teams, Abrechnung und GDPR-Abläufe – erfordern derzeit eine authentifizierte Browser-Sitzung und sind nicht per API-Key verfügbar.

Link to this sectionAPI-Key abrufen#

1. Gehe zu Settings > API Keys
2. Klicke auf Create Key
3. Kopiere den generierten Key

Siehe API Keys für detaillierte Anweisungen.

Link to this sectionAutorisierungs-Header#

Füge deinen API-Key in alle Anfragen ein:

Authorization: Bearer YOUR_API_KEY

Link to this sectionBeispiel#

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

Link to this sectionBasis-URL#

Alle API-Endpunkte verwenden:

Link to this sectionRatenbegrenzungen#

Die API erzwingt Ratenbegrenzungen pro API-Key (Sliding Window, unterstützt durch Upstash Redis), um Missbrauch zu verhindern, während rechtmäßige Nutzung uneingeschränkt bleibt. Anonymer Datenverkehr wird zusätzlich durch die Missbrauchskontrollen auf Plattform-Ebene von Vercel geschützt.

Bei Drosselung gibt die API 429 mit Retry-Metadaten zurück:

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

Link to this sectionLimits pro API-Key#

Ratenbegrenzungen werden automatisch basierend auf dem aufgerufenen Endpunkt angewendet. Aufwendige Operationen haben strengere Limits, um Missbrauch zu verhindern, während Standard-CRUD-Operationen sich ein großzügiges Standardlimit teilen:

Jede Kategorie verfügt über einen unabhängigen Zähler pro API-Key. Wenn du beispielsweise 20 Predict-Anfragen stellst, beeinträchtigt dies nicht dein Standard-Limit von 100 Anfragen/Min.

Link to this sectionDedizierte Endpunkte (Unbegrenzt)#

Dedizierte Endpunkte unterliegen keinen API-Key-Ratenbegrenzungen. Wenn du ein Modell auf einem dedizierten Endpunkt bereitstellst, gehen Anfragen an diese Endpunkt-URL (z. B. https://predict-abc123.run.app/predict) direkt an deinen dedizierten Dienst, ohne Ratenbegrenzung durch die Plattform. Du zahlst für die Rechenleistung, daher erhältst du Durchsatz basierend auf deiner Konfiguration des dedizierten Dienstes anstelle der geteilten API-Limits.

Link to this sectionAntwortformat#

Link to this sectionErfolgsantworten#

Antworten geben JSON mit ressourcenspezifischen Feldern zurück:

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

Link to this sectionFehlerantworten#

{
    "error": "Dataset not found"
}

Link to this sectionDatasets API#

Erstelle, durchsuche und verwalte beschriftete Bild-Datasets für das Training von YOLO Modellen. Siehe Datasets-Dokumentation.

Link to this sectionDatasets auflisten#

GET /api/datasets

Abfrageparameter:

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

Antwort:

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

Link to this sectionDataset abrufen#

GET /api/datasets/{datasetId}

Gibt vollständige Dataset-Details zurück, einschließlich Metadaten, Klassennamen und Split-Anzahlen.

Link to this sectionDataset erstellen#

POST /api/datasets

Body:

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

Link to this sectionDataset aktualisieren#

PATCH /api/datasets/{datasetId}

Body (partielle Aktualisierung):

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

Link to this sectionDataset-Icon#

Lade ein Dataset-Icon hoch (Multipart-Formular mit Bilddatei):

POST /api/datasets/{datasetId}/icon

Entferne das Dataset-Icon:

DELETE /api/datasets/{datasetId}/icon

Beide erfordern eine aktive Plattform-Browsersitzung – nicht über einen API-Schlüssel verfügbar.

Link to this sectionDataset löschen#

DELETE /api/datasets/{datasetId}

Löscht das Dataset vorläufig (wird in den Papierkorb verschoben, für 30 Tage wiederherstellbar).

Link to this sectionDataset klonen#

POST /api/datasets/{datasetId}/clone

Erstellt eine Kopie des Datasets mit allen Bildern und Labels. Nur öffentliche, eigene oder bearbeitbare Workspace-Datasets können geklont werden. Erfordert eine aktive Plattform-Browsersitzung – nicht über API-Key verfügbar.

Body (alle Felder optional):

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

Link to this sectionDataset exportieren#

GET /api/datasets/{datasetId}/export

Gibt eine JSON-Antwort mit einer signierten Download-URL für den neuesten Dataset-Export zurück.

Abfrageparameter:

Antwort:

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

Link to this sectionDataset-Version erstellen#

POST /api/datasets/{datasetId}/export

Erstelle einen neuen nummerierten Versions-Snapshot des Datasets. Nur für Eigentümer. Die Version erfasst die aktuelle Bildanzahl, Klassenanzahl, Annotationsanzahl und Split-Verteilung und generiert und speichert dann einen unveränderlichen NDJSON-Export.

Request Body:

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

Alle Felder sind optional. Das Feld description ist ein vom Benutzer bereitgestelltes Label für die Version.

Antwort:

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

Link to this sectionVersionsbeschreibung aktualisieren#

PATCH /api/datasets/{datasetId}/export

Aktualisiere die Beschreibung einer bestehenden Version. Nur für Eigentümer.

Request Body:

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

Antwort:

{
    "ok": true
}

Link to this sectionKlassenstatistiken abrufen#

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

Gibt Klassenverteilung, Standort-Heatmap und Dimensionsstatistiken zurück. Ergebnisse werden für bis zu 5 Minuten zwischengespeichert.

Antwort:

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

Link to this sectionKlassen verwalten#

Klassen zusammenführen (Annotations von Quellklassen einem Ziel zuweisen und dann die Quellen entfernen):

POST /api/datasets/{datasetId}/classes/merge

Klassen löschen:

POST /api/datasets/{datasetId}/classes/delete

Link to this sectionSplits neu verteilen#

POST /api/datasets/{datasetId}/splits/redistribute

Bilder über Train/Val/Test-Splits neu zuweisen. Alle drei erfordern eine aktive Plattform-Browsersitzung – nicht über API-Key verfügbar.

Link to this sectionDataset-Embeddings#

GET /api/datasets/{datasetId}/embeddings
POST /api/datasets/{datasetId}/embeddings
DELETE /api/datasets/{datasetId}/embeddings

GET gibt die aktuelle UMAP-Analysezusammenfassung und den aktiven Jobstatus zurück; POST stellt einen Embeddings-Analysejob in die Warteschlange; DELETE bricht den aktiven Job ab.

Link to this sectionBild-Clustering#

GET /api/datasets/{datasetId}/images/clustering

Gibt das UMAP 2D-Layout und die Metadaten pro Bild für die Clustering-Scatter-Ansicht zurück (paged und rate-limited).

Link to this sectionMit Dataset trainierte Modelle abrufen#

GET /api/datasets/{datasetId}/models

Gibt Modelle zurück, die mit diesem Dataset trainiert wurden.

Antwort:

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

Link to this sectionDataset automatisch annotieren#

POST /api/datasets/{datasetId}/predict

Führe YOLO-Inferenz auf Dataset-Bildern aus, um Annotationen automatisch zu generieren. Verwendet ein ausgewähltes Modell, um Labels für nicht annotierte Bilder vorherzusagen.

Body:

Link to this sectionDataset-Ingest#

POST /api/datasets/ingest

Erstelle einen Dataset-Ingest-Job zur Verarbeitung hochgeladener ZIP- oder TAR-Dateien, einschließlich .tar.gz und .tgz, die Bilder und Labels enthalten.

Der Request-Body erfordert genau eines von sessionId (Upload-Session eines hochgeladenen Archivs) oder sourceUrl (ein Remote-ZIP, TAR, TAR.GZ, TGZ oder NDJSON-URL), plus ein optionales targetSplit (train, val oder test), um die Split-Struktur des Archivs zu überschreiben.

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]

Link to this sectionDataset-Bilder#

Link to this sectionBilder auflisten#

GET /api/datasets/{datasetId}/images

Abfrageparameter:

Link to this sectionSignierte Bild-URLs abrufen#

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

Rufe signierte URLs für eine Charge von Bild-Hashes ab (zur Anzeige im Browser).

Link to this sectionBild löschen#

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

Link to this sectionBild-Labels abrufen#

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

Gibt Annotationen und Klassennamen für ein spezifisches Bild zurück.

Link to this sectionBild-Labels aktualisieren#

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

Body:

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

Link to this sectionMassen-Bildoperationen#

Bilder zwischen Splits (train/val/test) innerhalb eines Datasets verschieben:

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

Bilder massenhaft löschen:

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

Link to this sectionProjekte API#

Organisiere deine Modelle in Projekten. Jedes Modell gehört zu einem Projekt. Siehe Projekte-Dokumentation.

Link to this sectionProjekte auflisten#

GET /api/projects

Abfrageparameter:

Link to this sectionProjekt abrufen#

GET /api/projects/{projectId}

Link to this sectionProjekt erstellen#

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

Link to this sectionProjekt aktualisieren#

PATCH /api/projects/{projectId}

Link to this sectionProjekt löschen#

DELETE /api/projects/{projectId}

Löscht das Projekt vorläufig (wird in den Papierkorb verschoben).

Link to this sectionProjekt klonen#

POST /api/projects/{projectId}/clone

Klont ein öffentliches Projekt (mit all seinen Modellen) in deinen Workspace. Erfordert eine aktive Plattform-Browsersitzung — nicht über API-Key verfügbar.

Link to this sectionProjekt-Icon#

Lade ein Projekt-Icon hoch (Multipart-Formular mit Bilddatei):

POST /api/projects/{projectId}/icon

Entferne das Projekt-Icon:

DELETE /api/projects/{projectId}/icon

Beide erfordern eine aktive Plattform-Browsersitzung – nicht über einen API-Schlüssel verfügbar.

Link to this sectionModels API#

Verwalte trainierte YOLO-Modelle – zeige Metriken an, lade Weights herunter, führe Inferenzen aus und exportiere in andere Formate. Siehe Models-Dokumentation.

Link to this sectionModelle auflisten#

GET /api/models

Abfrageparameter:

Link to this sectionAbgeschlossene Modelle auflisten#

GET /api/models/completed

Gibt Modelle zurück, deren Training abgeschlossen ist (zur Verwendung in Modellauswahlen und bei der Bereitstellung).

Link to this sectionModell abrufen#

GET /api/models/{modelId}

Link to this sectionModell erstellen#

POST /api/models

JSON Body:

Link to this sectionModell aktualisieren#

PATCH /api/models/{modelId}

Link to this sectionModell löschen#

DELETE /api/models/{modelId}

Link to this sectionModelldateien herunterladen#

GET /api/models/{modelId}/files

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

Link to this sectionModell klonen#

POST /api/models/{modelId}/clone

Klonen ein öffentliches Modell in eines deiner Projekte. Erfordert eine aktive Plattform-Browsersitzung – nicht über einen API-Schlüssel verfügbar.

Body:

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

Link to this sectionDownload nachverfolgen#

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

Analysedaten für den Modelldownload nachverfolgen.

Link to this sectionFühre die Inferenz aus.#

POST /api/models/{modelId}/predict

Multipart Form:

Die maximale Upload-Größe beträgt 100 MB.

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

Antwort:

{
    "images": [
        {
            "shape": [1080, 1920],
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1
    }
}

Link to this sectionVorhersage-Token abrufen#

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

Link to this sectionModell aufwärmen#

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

Link to this sectionTraining API#

Starte YOLO-Training auf Cloud-GPUs (24 GPU-Typen von RTX 2000 Ada bis B300) und überwache den Fortschritt in Echtzeit. Siehe Cloud-Training-Dokumentation.

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]

Link to this sectionTraining starten#

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

Link to this sectionGPU-Verfügbarkeit abrufen#

GET /api/training/gpu-availability

Gibt den aktuellen GPU-Lagerstatus zurück (High, Medium, Low oder null), sortiert nach GPU-Typ-ID. Öffentlich, keine Authentifizierung erforderlich; für 5 Minuten zwischengespeichert.

Link to this sectionTrainingsstatus abrufen#

GET /api/models/{modelId}/training

Gibt den aktuellen Trainingsjobstatus, Metriken und den Fortschritt für ein Modell zurück. Öffentliche Projekte sind anonym zugänglich; private Projekte erfordern eine aktive Plattform-Browsersitzung (dieser Pfad akzeptiert keine API-Schlüssel-Authentifizierung).

Link to this sectionTraining abbrechen#

DELETE /api/models/{modelId}/training

Beendet die laufende Compute-Instanz und markiert den Job als abgebrochen. Erfordert eine aktive Plattform-Browsersitzung – nicht über einen API-Schlüssel verfügbar.

Link to this sectionDeployments API#

Stelle Modelle auf dedizierten Inferenz-Endpunkten mit Gesundheitsprüfungen und Überwachung bereit. Neue Deployments nutzen standardmäßig Scale-to-Zero, und die API akzeptiert ein optionales resources-Objekt. Siehe Endpoints-Dokumentation.

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]

Link to this sectionDeployments auflisten#

GET /api/deployments

Abfrageparameter:

Link to this sectionDeployment erstellen#

POST /api/deployments

Body:

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

Erstellt einen dedizierten Inferenz-Endpunkt in der angegebenen Region. Der Endpunkt ist global über eine eindeutige URL zugänglich.

Link to this sectionDeployment abrufen#

GET /api/deployments/{deploymentId}

Link to this sectionDeployment löschen#

DELETE /api/deployments/{deploymentId}

Link to this sectionDeployment starten#

POST /api/deployments/{deploymentId}/start

Ein gestopptes Deployment fortsetzen.

Link to this sectionDeployment stoppen#

POST /api/deployments/{deploymentId}/stop

Ein laufendes Deployment pausieren (stoppt die Abrechnung).

Link to this sectionGesundheitsprüfung#

GET /api/deployments/{deploymentId}/health

Gibt den Gesundheitsstatus des Deployment-Endpunkts zurück.

Link to this sectionInferenz auf Deployment ausführen#

POST /api/deployments/{deploymentId}/predict

Sende ein Bild direkt an einen Deployment-Endpunkt für die Inferenz. Funktional äquivalent zur Modellvorhersage, aber für geringere Latenz über den dedizierten Endpunkt geroutet.

Multipart Form:

Link to this sectionMetriken abrufen#

GET /api/deployments/{deploymentId}/metrics

Gibt Anfrageanzahlen, Latenz- und Fehlerratenmetriken mit Sparkline-Daten zurück.

Abfrageparameter:

Link to this sectionLogs abrufen#

GET /api/deployments/{deploymentId}/logs

Abfrageparameter:

Link to this sectionMonitoring API#

Link to this sectionAggregierte Metriken#

GET /api/monitoring

Gibt aggregierte Metriken über alle Benutzer-Deployments hinweg zurück: Gesamtzahl der Anfragen, aktive Deployments, Fehlerrate und durchschnittliche Latenz.

Link to this sectionExport-API#

Konvertiere Modelle in optimierte Formate wie ONNX, TensorRT, CoreML und TFLite für das Edge-Deployment. Siehe Deploy-Dokumentation.

Link to this sectionExporte auflisten#

GET /api/exports

Abfrageparameter:

Link to this sectionExport erstellen#

POST /api/exports

Body:

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

Unterstützte Formate:

Link to this sectionExport-Status abrufen#

GET /api/exports/{exportId}

Link to this sectionExport abbrechen#

DELETE /api/exports/{exportId}

Link to this sectionExport-Download verfolgen#

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

Link to this sectionAktivitäts-API#

Sieh dir einen Feed der letzten Aktionen in deinem Konto an – Trainingsläufe, Uploads und mehr. Siehe Aktivitäts-Dokumentation.

Link to this sectionAktivitäten auflisten#

GET /api/activity

Abfrageparameter:

Link to this sectionEreignisse als gesehen markieren#

POST /api/activity/mark-seen

Body:

{
    "all": true
}

Oder spezifische IDs übergeben:

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

Link to this sectionEreignisse archivieren#

POST /api/activity/archive

Body:

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

Oder spezifische IDs übergeben:

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

Link to this sectionPapierkorb-API#

Gelöschte Elemente anzeigen und wiederherstellen. Elemente werden nach 30 Tagen endgültig entfernt. Siehe Papierkorb-Dokumentation.

Link to this sectionPapierkorb auflisten#

GET /api/trash

Abfrageparameter:

Link to this sectionElement wiederherstellen#

POST /api/trash

Body:

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

Link to this sectionElement endgültig löschen#

DELETE /api/trash

Body:

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

Link to this sectionPapierkorb leeren#

DELETE /api/trash/empty

Löscht alle Elemente im Papierkorb endgültig.

Link to this sectionAbrechnungs-API#

Überprüfe dein Guthaben, kaufe Credits, sieh dir den Transaktionsverlauf an und konfiguriere die automatische Aufladung. Siehe Abrechnungs-Dokumentation.

Link to this sectionGuthaben abrufen#

GET /api/billing/balance

Abfrageparameter:

Antwort:

{
    "creditsCents": 2500,
    "plan": "free"
}

Link to this sectionNutzungsübersicht abrufen#

GET /api/billing/usage-summary

Gibt Plandetails, Limits und Nutzungsmetriken zurück.

Link to this sectionTransaktionen abrufen#

GET /api/billing/transactions

Gibt den Transaktionsverlauf zurück (neueste zuerst).

Abfrageparameter:

Link to this sectionCheckout-Sitzung erstellen#

POST /api/billing/checkout-session

Body:

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

Erstellt eine Checkout-Sitzung für den Credit-Kauf.

Link to this sectionAbonnement-Checkout erstellen#

POST /api/billing/subscription-checkout

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

Body:

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

Link to this sectionAbonnement kündigen oder fortsetzen#

DELETE /api/billing/subscription-checkout

Kündigt ein Pro-Abonnement standardmäßig zum Ende des Zeitraums. Sende {"resume": true}, um eine bereits geplante Kündigung vor Ende des Abrechnungszeitraums fortzusetzen.

Body:

{
    "resume": true
}

Link to this sectionAutomatische Aufladung#

Füge automatisch Credits hinzu, wenn das Guthaben unter einen Schwellenwert fällt.

Link to this sectionAuto-Aufladungskonfiguration abrufen#

GET /api/billing/auto-topup

Abfrageparameter:

Link to this sectionAuto-Aufladungskonfiguration aktualisieren#

PATCH /api/billing/auto-topup

Body:

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

Link to this sectionZahlungsmethoden#

Link to this sectionZahlungsmethoden auflisten#

GET /api/billing/payment-methods

Link to this sectionSetup-Intent erstellen#

POST /api/billing/payment-methods/setup

Gibt ein Client-Secret zum Hinzufügen einer neuen Zahlungsmethode zurück.

Link to this sectionStandard-Zahlungsmethode festlegen#

POST /api/billing/payment-methods/default

Body:

{
    "paymentMethodId": "pm_123"
}

Link to this sectionAbrechnungsinformationen aktualisieren#

PATCH /api/billing/payment-methods

Body:

{
    "name": "Jane Doe",
    "address": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
    }
}

Link to this sectionZahlungsmethode löschen#

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

Link to this sectionSpeicher-API#

Überprüfe deine Speichernutzungsaufschlüsselung nach Kategorie (Datensätze, Modelle, Exporte) und sieh dir deine größten Elemente an.

Link to this sectionSpeicherinformationen abrufen#

GET /api/storage

Abfrageparameter:

Antwort:

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

Link to this sectionUpload-API#

Lade Dateien direkt in den Cloud-Speicher hoch, indem du signierte URLs für schnelle, zuverlässige Übertragungen verwendest. Verwendet einen zweistufigen Prozess: Erhalte eine signierte URL, dann lade die Datei hoch. Siehe Daten-Dokumentation.

Link to this sectionSignierte Upload-URL abrufen#

POST /api/upload/signed-url

Fordere eine signierte URL an, um eine Datei direkt in den Cloud-Speicher hochzuladen. Die signierte URL umgeht den API-Server für große Dateiübertragungen.

Body:

{
    "assetType": "images",
    "assetId": "abc123",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "totalBytes": 5242880
}

Antwort:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "gcsPath": "gs://bucket/users/user123/images/abc123/my-image.jpg",
    "downloadUrl": "https://cdn.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

Link to this sectionUpload abschließen#

POST /api/upload/complete

Benachrichtige die Plattform, dass ein Datei-Upload abgeschlossen ist, damit die Verarbeitung beginnen kann.

Body:

{
    "sessionId": "session_abc123",
    "checksum": "<optional sha-256 hex>"
}

Link to this sectionIntegrations-API#

Importiere Datasets von Drittanbietern. Siehe Integrations-Dokumentation.

Link to this sectionRoboflow-Importvorschau#

POST /api/integrations/roboflow/preview

Löse einen Roboflow API-Key in einen Bulk-Import-Plan auf: Workspace-Informationen, welche Projekte neu importiert würden, Anzahl der bereits importierten Versionen (übersprungen) und nicht unterstützte Projekttypen. Der Roboflow API-Key wird im Body übergeben und nicht gespeichert.

Link to this sectionImport von Roboflow#

POST /api/integrations/roboflow/import

Stelle Dataset-Ingest-Jobs in die Warteschlange, um die ausgewählten Roboflow-Projekte in deinen Workspace zu importieren. Erfordert Speicherplatz, und jedes Dataset muss innerhalb des Import-Größenlimits deines Plans liegen.

Link to this sectionAPI-Keys API#

Verwalte deine API-Keys für den programmatischen Zugriff. Siehe API-Keys Dokumentation.

Link to this sectionAPI-Keys auflisten#

GET /api/api-keys

Link to this sectionAPI-Key erstellen#

POST /api/api-keys

Body:

{
    "name": "training-server"
}

Link to this sectionAPI-Key löschen#

DELETE /api/api-keys

Abfrageparameter:

Beispiel:

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

Link to this sectionTeams & Mitglieder API#

Erstelle Team-Arbeitsbereiche, lade Mitglieder ein und verwalte Rollen für die Zusammenarbeit. Siehe Teams-Dokumentation.

Link to this sectionTeams auflisten#

GET /api/teams

Link to this sectionTeam erstellen#

POST /api/teams/create

Body:

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

Link to this sectionMitglieder auflisten#

GET /api/members

Gibt Mitglieder des aktuellen Arbeitsbereichs zurück.

Link to this sectionMitglied einladen#

POST /api/members

Body:

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

Link to this sectionMitgliedsrolle aktualisieren#

PATCH /api/members/{userId}

Link to this sectionMitglied entfernen#

DELETE /api/members/{userId}

Link to this sectionEigentümerschaft übertragen#

POST /api/members/transfer-ownership

Link to this sectionEinladungen#

Link to this sectionEinladung akzeptieren#

POST /api/invites/accept

Link to this sectionEinladungsinformationen abrufen#

GET /api/invites/info

Abfrageparameter:

Link to this sectionEinladung widerrufen#

DELETE /api/invites/{inviteId}

Link to this sectionEinladung erneut senden#

POST /api/invites/{inviteId}/resend

Link to this sectionExplore API#

Suche und durchstöbere öffentliche Datensätze und Projekte, die von der Community geteilt wurden. Siehe Explore-Dokumentation.

Link to this sectionÖffentliche Inhalte durchsuchen#

GET /api/explore/search

Abfrageparameter:

Link to this sectionSidebar-Daten#

GET /api/explore/sidebar

Gibt kuratierte Inhalte für die Explore-Sidebar zurück.

Link to this sectionBenutzer- & Einstellungs-APIs#

Verwalte dein Profil, API-Keys, Speichernutzung und Datenschutz-Einstellungen. Siehe Einstellungen-Dokumentation.

Link to this sectionBenutzer nach Benutzername abrufen#

GET /api/users

Abfrageparameter:

Link to this sectionBenutzer folgen oder entfolgen#

PATCH /api/users

Body:

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

Link to this sectionBenutzernamen-Verfügbarkeit prüfen#

GET /api/username/check

Abfrageparameter:

Link to this sectionEinstellungen#

GET /api/settings
POST /api/settings

Benutzerprofileinstellungen abrufen oder aktualisieren (Anzeigename, Bio, soziale Links, etc.).

Link to this sectionProfilbild#

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

Profil-Avatar hochladen oder entfernen.

Link to this sectionOnboarding#

POST /api/onboarding

Onboarding-Prozess abschließen (Datenregion, Benutzername festlegen).

Link to this sectionGDPR API#

Fordere einen Export all deiner Daten an oder lösche dein Konto dauerhaft. Siehe Einstellungen-Dokumentation.

Link to this sectionGDPR-Jobstatus abrufen#

GET /api/gdpr

Abfrageparameter:

Gibt den Jobstatus zurück. Für abgeschlossene Export-Jobs enthält die Antwort eine downloadUrl.

Link to this sectionExport- oder Löschvorgang starten#

POST /api/gdpr

Body:

{
    "action": "export"
}

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

Optional für Team-Arbeitsbereiche:

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

Link to this sectionFehlercodes#

Link to this sectionPython-Integration#

Für eine einfachere Integration nutze das Ultralytics Python-Paket, das Authentifizierung, Uploads und das Streaming von Echtzeit-Metriken automatisch übernimmt.

Link to this sectionInstallation & Einrichtung#

pip install ultralytics

Installation überprüfen:

yolo check

Link to this sectionAuthentifizierung#

yolo settings api_key=YOUR_API_KEY

Link to this sectionPlattform-Datensätze verwenden#

Referenziere Datensätze mit ul:// URIs:

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

URI-Format:

Link to this sectionPush an die Plattform#

Ergebnisse an ein Plattform-Projekt senden:

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

Was synchronisiert wird:

• Trainingsmetriken (Echtzeit)
• Finale Modellgewichte
• Validierungsdiagramme
• Konsolenausgabe
• Systemmetriken

Link to this sectionAPI-Beispiele#

Lade ein Modell von der Plattform:

# Your own model
model = YOLO("ul://username/project/model-name")

# Official model
model = YOLO("ul://ultralytics/yolo26/yolo26n")

Inferenz ausführen:

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

Modell exportieren:

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

Validierung:

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

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

Link to this sectionWebhooks#

Die Plattform nutzt interne Webhooks, um Echtzeit-Trainingsmetriken aus dem ultralytics Python SDK (ausgeführt auf Cloud-GPUs oder entfernten/lokalen Maschinen) an die Plattform zurückzustreamen — Loss pro Epoche, mAP, Systemstatistiken und Abschlussstatus. Diese Webhooks werden über den HMAC webhookSecret authentifiziert, der pro Trainingsjob bereitgestellt wird, und sind nicht für die Nutzung durch Benutzeranwendungen gedacht.

Link to this sectionFAQ#

Link to this sectionWie paginiere ich große Ergebnisse?#

Die meisten Endpunkte verwenden einen limit-Parameter, um zu steuern, wie viele Ergebnisse pro Anfrage zurückgegeben werden:

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

Die Aktivitäts- und Papierkorb-Endpunkte unterstützen zusätzlich einen page-Parameter für seitenbasierte Paginierung:

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

Der Explore-Search-Endpunkt verwendet offset anstelle von page, mit einer festen Seitengröße von 20:

curl "https://platform.ultralytics.com/api/explore/search?type=datasets&offset=20&sort=stars"

Link to this sectionKann ich die API ohne SDK nutzen?#

Ja, alle Funktionalitäten sind über REST verfügbar. Das Python SDK ist ein praktischer Wrapper, der Funktionen wie Echtzeit-Metrik-Streaming und automatische Modell-Uploads hinzufügt. Du kannst auch alle Endpunkte interaktiv unter platform.ultralytics.com/api/docs erkunden.

Link to this sectionGibt es API-Client-Bibliotheken?#

Derzeit verwendest du das Ultralytics Python-Paket oder tätigst direkte HTTP-Anfragen. Offizielle Client-Bibliotheken für andere Sprachen sind geplant.

Link to this sectionWie gehe ich mit Ratenbegrenzungen um?#

Nutze den Retry-After-Header aus der 429-Antwort, um die richtige Zeit zu warten:

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

Link to this sectionWie finde ich meine Modell- oder Datensatz-ID?#

Ressourcen-IDs werden zurückgegeben, wenn du Ressourcen über die API erstellst. Du kannst sie auch in der Plattform-URL finden:

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

Verwende die Listen-Endpunkte, um nach Namen zu suchen oder nach Projekten zu filtern.