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]:::start --> B[Datasets]:::proc
    A --> C[Projects]:::proc
    A --> D[Models]:::proc
    A --> E[Deployments]:::proc
    B -->|train on| D
    C -->|contains| D
    D -->|deploy to| E
    D -->|export| F[Exports]:::proc
    B -->|auto-annotate| B

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff

Link to this sectionAuthentifizierung#

Ressourcen-APIs verwenden eine Authentifizierung per API-Key, einschließlich der Verwaltung von Dataset-Klassen und -Splits, Klonen, Training, Exporten, Bereitstellungen und unterstützten Konto-Abrufen. Öffentliche Endpunkte unterstützen anonymen Zugriff, sofern vermerkt. Browser-exklusive Anwendungsrouten sind ausgenommen.

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:

https://platform.ultralytics.com/api

Link to this sectionRatenbegrenzungen#

Die API erzwingt gleitende, durch Upstash Redis abgesicherte Limits pro API-Schlüssel. Jede Route verwendet die unten stehende passende Kategorie.

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 Platform API-Schlüssel-Ratenlimits, wenn du die Endpunkt-URL direkt aufrufst (zum Beispiel https://predict-abc123.run.app/predict). Der Durchsatz hängt dann von der Konfiguration des bereitgestellten Dienstes ab.

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.

Übergebe username, wenn {datasetId} ein Dataset-Slug statt einer ID ist.

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

Antwort:

{
    "datasetId": "dataset_abc123",
    "slug": "my-dataset",
    "region": "us"
}

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#

POST /api/datasets/{datasetId}/icon
DELETE /api/datasets/{datasetId}/icon

Lade ein WebP-Icon mit bis zu 5 MB als Multipart-Formularfeld image hoch oder entferne das aktuelle Icon.

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 eines öffentlichen, eigenen oder bearbeitbaren Workspace-Datasets mit allen Bildern und Labels.

Optionaler Body (alle Felder sind optional):

{
    "name": "cloned-dataset",
    "slug": "cloned-dataset",
    "description": "My cloned dataset",
    "visibility": "private",
    "license": "AGPL-3.0",
    "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. Dies erfordert Editor-Zugriff oder höher. Die Version erfasst die aktuelle Anzahl an Bildern, Klassen, Annotationen sowie die Aufteilungsverteilung 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. Dies erfordert Editor-Zugriff oder höher.

Request Body:

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

Antwort:

{
    "ok": true
}

Link to this sectionDataset-Version wiederherstellen#

POST /api/datasets/{datasetId}/restore

Stellt die Bilder, Annotationen und Klassen des Datasets aus einer gespeicherten Version wieder her, ohne die Bild-Bytes zu kopieren.

{
    "version": 2
}

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

{
    "sourceClassIds": [2, 4],
    "targetClassId": 1
}

Klassen-IDs sind positionsabhängig, daher ist die Zusammenführung nicht idempotent. Lade das Dataset erneut, bevor du es erneut versuchst.

Klassen löschen:

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

{
    "classIds": [2, 4]
}

Link to this sectionSplits neu verteilen#

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

Ordne Bilder zufällig den Splits Training, Validierung und Test zu. Die Prozentsätze müssen insgesamt 100 ergeben.

{
    "train": 80,
    "val": 20,
    "test": 0
}

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 für ein bestehendes Dataset. Das Ziel-Dataset wird immer als datasetId im JSON-Body übergeben, nicht im URL-Pfad.

Der Request-Body erfordert datasetId sowie genau eines der Felder sessionId (eine Upload-Session eines hochgeladenen Archivs) oder sourceUrl (eine URL zu einem Remote-ZIP, TAR, TAR.GZ, TGZ oder NDJSON). Füge optional targetSplit (train, val oder test) hinzu, um die Split-Struktur des Archivs zu überschreiben.

Bei hochgeladenen Archiven ist die Upload-Sitzung bereits an den Datensatz gebunden, über die assetId, die an POST /api/upload/signed-url übergeben wurde; der Ingest validiert, dass die assetId mit der datasetId im Body übereinstimmt. Optionale classMapping-Einträge ordnen jeden eingehenden Klassennamen einem existierenden nullbasierten Klassenindex, einem wiederzuverwendenden oder neu zu erstellenden Klassennamen oder null zum Überspringen der Klasse zu. Bei Remote-Importen über sourceUrl erstelle den Datensatz zuerst und übergebe dann dessen datasetId an den Ingest.

Body (hochgeladenes Archiv):

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "targetSplit": "train"
}

Body (Remote-Archiv oder NDJSON):

{
    "datasetId": "dataset_abc123",
    "sourceUrl": "https://example.com/my-dataset.zip"
}

Body (späterer Ingest, Import von Labels):

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "car", "background": null }
}

Antwort:

{
    "jobId": "job_abc123",
    "datasetId": "dataset_abc123",
    "status": "queued"
}

graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[Upload archive to signed URL]:::proc
    C --> D[POST /api/upload/complete]:::proc
    D --> E[POST /api/datasets/ingest]:::proc
    E --> F[Process archive]:::proc
    F --> G[Dataset ready]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff

Link to this sectionDataset-Bilder#

Link to this sectionBilder auflisten#

GET /api/datasets/{datasetId}/images

Abfrageparameter:

Link to this sectionAusgewählte Bilder abrufen#

POST /api/datasets/{datasetId}/images

Gibt die gleiche Bildform für bis zu 1.000 bereitgestellte Bild-IDs zurück. Es akzeptiert dieselben URL- und Label-Abfragesteuerungen wie der Listenvorgang.

{
    "imageIds": ["IMAGE_OBJECT_ID"]
}

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, eigenes oder bearbeitbares Workspace-Projekt und dessen Modelle in dein Konto oder deinen Workspace. Ein optionaler JSON-Body akzeptiert Überschreibungen für name, slug, description, visibility, license und Ziel-owner.

Link to this sectionProjekt-Icon#

POST /api/projects/{projectId}/icon
DELETE /api/projects/{projectId}/icon

Lade ein WebP-Icon mit bis zu 5 MB als Multipart-Formularfeld image hoch oder entferne das aktuelle Icon.

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 bis zu 1.000 Modelle mit verwendbaren Gewichten über alle Projekte hinweg für Training und Bereitstellung zurück. Übergebe owner für einen Workspace.

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

Klone ein öffentliches, eigenes oder bearbeitbares Workspace-Modell in eines deiner Projekte.

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

Öffentliche Modelle können ohne Authentifizierung vorhergesagt werden. Private und geteilte Modelle erfordern einen API-Key mit Zugriff auf das übergeordnete Projekt.

Multipart Form:

Gib entweder file oder source an. 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:

Die Antworten enthalten shape, speed, results pro Bild und optional dichte Pixel-Map-Daten (eine semantische Klassen-Map oder eine Tiefen-Map, wobei depth = pixel × max / divisor gilt — divisor 255 für die Standard-8-Bit-Map, 65535 bei bits=12|16), sowie metadata mit Bildanzahl, Funktionslaufzeit, Aufgabe und Service-Versionen. Interne Modellpfade werden niemals zurückgegeben.

{
    "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 sectionTraining API#

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

graph LR
    A[POST /training/start]:::start --> B[Job Created]:::proc
    B --> C{Training}:::decide
    C -->|progress| D[GET /models/id/training]:::proc
    C -->|cancel| E[DELETE /models/id/training]:::error
    C -->|complete| F[Model Ready]:::out
    F --> G[Deploy or Export]:::proc

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef decide fill:#FF9800,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff

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 Status des Trainings-Jobs, Metriken, Fortschritt, Timing, GPU-Details und Fehler zurück. Öffentliche Projekte sind ohne Authentifizierung zugänglich; private und geteilte Projekte erfordern einen API-Key mit Zugriff.

Link to this sectionTraining abbrechen#

DELETE /api/models/{modelId}/training

Beendet die laufende Recheninstanz und markiert den Job als abgebrochen.

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]:::start --> B[Deploying]:::proc
    B --> C[Ready]:::out
    C -->|stop| D[Stopped]:::extern
    D -->|start| C
    C -->|delete| E[Deleted]:::error
    D -->|delete| E
    C -->|predict| F[Inference Results]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff
    classDef extern fill:#607D8B,color:#fff

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

Stoppe die Bereitstellung von Anfragen, indem du die minimale und maximale Anzahl von Instanzen des Dienstes auf Null setzt.

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:

Gib entweder file oder source an. Die Antwort verwendet denselben Bild- und Metadatenvertrag wie die Modellvorhersage und gibt niemals den internen Modellpfad zurück.

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 sectionExport-API#

Konvertiere Modelle für das Edge-Deployment in optimierte Formate wie ONNX, TensorRT, CoreML und LiteRT. 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:

Verwende das format-Argument aus der gemeinsamen Exporttabelle unten. PyTorch ist das Quellformat und kein API-Exportziel.

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

Übergebe den optionalen owner-Abfrageparameter, um Ereignisse in einem Workspace zu markieren.

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
}

Übergebe den optionalen owner-Abfrageparameter, um Workspace-Ereignisse zu archivieren oder wiederherzustellen.

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, deine Plannutzung und deinen Transaktionsverlauf. Siehe Abrechnungsdokumentation.

Die Guthaben- und Transaktionsendpunkte akzeptieren einen optionalen owner-Abfrageparameter mit dem Benutzernamen des Workspace-Eigentümers.

Link to this sectionGuthaben abrufen#

GET /api/billing/balance

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

Transaktionen umfassen kundenorientierte Ledger-Felder wie Betrag, resultierendes Guthaben, Datum, optionalen Modellkontext und Quittungs-URL. Interne Notizen, Stripe-Zahlungs-/Rückerstattungs-IDs und Idempotenz-Schlüssel werden nicht zurückgegeben.

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 sectionCloud-Speicher-Integrationen#

Verbinde und durchsuche schreibgeschützte GCS-, S3- oder Azure Blob-Speicherintegrationen:

GET /api/integrations/buckets
POST /api/integrations/buckets
POST /api/integrations/buckets/discover
GET /api/integrations/buckets/{id}/objects

Alle vier Vorgänge akzeptieren den optionalen owner-Abfrageparameter für einen Workspace. Das Durchsuchen von Objekten akzeptiert zudem den erforderlichen target-Parameter sowie optionale prefix- und Anbieter-cursor-Abfrageparameter. Request-Bodies für Verbindungs- und Erkennungsanfragen verwenden die Anbieter-Anmeldeinformationsschemata in der interaktiven OpenAPI-Referenz; Anmeldeinformationen werden niemals zurückgegeben.

Link to this sectionUpload-API#

Lade Dateien direkt in den Cloud-Speicher hoch, indem du signierte URLs für schnelle, zuverlässige Übertragungen verwendest. Das Abschließen eines Modell-Uploads hängt dessen Gewichte an. Das Abschließen eines Dataset-Archiv-Uploads zeichnet die Sitzung auf; übergebe diese sessionId an POST /api/datasets/ingest, um die Verarbeitung zu starten. Siehe Datendokumentation.

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": "datasets",
    "assetId": "dataset_abc123",
    "filename": "my-dataset.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

Antwort:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.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. Bei Modellen werden dadurch die hochgeladenen Gewichte angehängt. Bei Dataset-Archiven wird dadurch die Upload-Sitzung verifiziert und aufgezeichnet; rufe anschließend POST /api/datasets/ingest auf, um die Dataset-Verarbeitung zu starten.

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

Authentifizierte API-Key-Clients erhalten wichtige Metadaten, niemals entschlüsselte existierende Schlüsselwerte. Ein neu erstellter Schlüssel wird einmal durch POST /api/api-keys zurückgegeben.

Übergebe den optionalen owner-Abfrageparameter, um Schlüssel für einen Workspace zu verwalten, für den du Bearbeiterzugriff hast.

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 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 Team-Workspaces. Siehe Einstellungsdokumentation.

Link to this sectionKontoübersicht#

GET /api/account/summary

Gibt den Plan, das Guthaben, die Ressourcenanzahl und die Team-Workspaces des authentifizierten Kontos zurück.

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 sectionWorkspace-Icon#

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

Lade ein WebP-Profil-/Workspace-Icon mit bis zu 5 MB als Multipart-Formularfeld image hoch oder entferne es. Übergebe optional owner für ein Team-Workspace.

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>=8.4.104"

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, quantize=16)

# Export to TensorRT
model.export(format="engine", imgsz=640, quantize=16)

# Export to CoreML
model.export(format="coreml", imgsz=640)  # use imgsz=224 for classification

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

Die oben dokumentierten öffentlichen REST-Vorgänge sind ohne das Python SDK verfügbar. Das SDK ist ein praktischer Wrapper, der Funktionen wie Echtzeit-Metrik-Streaming und automatische Modell-Uploads hinzufügt. Du kannst den maschinenlesbaren Vertrag interaktiv unter platform.ultralytics.com/api/docs erkunden; Kontoflüsse, die nur über Browsersitzungen laufen, verbleiben in der Platform UI.

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

Verwende das Ultralytics Python-Paket oder stelle direkte HTTP-Anfragen aus einer beliebigen Sprache.

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 RuntimeError("Rate limit exceeded")

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

Ressourcen-IDs werden von Create-, List- und Get-API-Antworten zurückgegeben. Platform-Seiten-URLs verwenden menschenlesbare Slugs, keine Datenbank-IDs:

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

Verwende die Listenendpunkte, um die entsprechende _id für ein Modell, ein Dataset, ein Projekt, ein Deployment oder eine andere Ressource zu finden.