REST API Referenz#

Ultralytics Platform bietet eine umfassende REST API für den programmatischen Zugriff auf Datasets, Modelle, Trainings und Deployments.

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

API-Ü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

Authentifizierung#

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.

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

Autorisierungs-Header#

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

Authorization: Bearer YOUR_API_KEY

Beispiel#

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

Basis-URL#

Alle API-Endpunkte verwenden:

https://platform.ultralytics.com/api

Ratenbegrenzungen#

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

Wenn die API gedrosselt wird, gibt sie 429 mit Wiederholungsmetadaten zurück:

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

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

Dedizierte Endpunkte (Unbegrenzt)#

Dedizierte Endpunkte unterliegen keinen Platform API-key-Ratenbegrenzungen, 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.

Antwortformat#

Erfolgsantworten#

Antworten geben JSON mit ressourcenspezifischen Feldern zurück:

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

Fehlerantworten#

{
    "error": "Dataset not found"
}

Datasets API#

Erstelle, durchsuche und verwalte mit Labels versehene Bilddatasets zum Trainieren von YOLO-Modellen. Siehe Datasets-Dokumentation.

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

Dataset abrufen#

GET /api/datasets/{datasetId}

Gibt Dataset-Details zurück, einschließlich Klassennamen, Split-Zahlen und anderer von Platform verwalteter Eigenschaften. Benutzerdefinierte Metadaten werden separat vom folgenden Metadaten-Endpunkt geladen.

Übergebe username, wenn {datasetId} ein Dataset-Slug und keine ID ist.

Dataset erstellen#

POST /api/datasets

Body:

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

Antwort:

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

Dataset aktualisieren#

PATCH /api/datasets/{datasetId}

Body (partielle Aktualisierung):

{
    "name": "Updated Name",
    "description": "New description",
    "metadata": { "location": "factory-2", "reviewed": true },
    "visibility": "public"
}

Sende ein leeres metadata-Objekt ({}), um benutzerdefinierte Metadaten zu löschen. Das serialisierte Metadatenobjekt ist auf 500.000 Zeichen begrenzt, und jeder Top-Level-Schlüssel ist auf 128 Zeichen begrenzt.

Dataset-Metadaten abrufen#

GET /api/datasets/{datasetId}/metadata

Gibt das benutzerdefinierte Metadatenobjekt und einen kuratierten Satz schreibgeschützter, von Ultralytics verwalteter Feld/Wert-Paare zurück. Benutzerdefinierte Metadaten werden in normalen Dataset-Nutzdaten absichtlich weggelassen. Authentifizierung und Dataset-Arbeitsbereichszugriff sind erforderlich.

Dataset-Icon#

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

Lade ein WebP-Symbol von bis zu 5 MB als Multipart-Formulardatenfeld image hoch oder entferne das aktuelle Symbol.

Dataset löschen#

DELETE /api/datasets/{datasetId}

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

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

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

Dataset-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=..."
}

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

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

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

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

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

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

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

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

Dataset 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:

Dataset-Ingest#

POST /api/datasets/ingest

Erstelle einen Dataset-Ingest-Job für ein bestehendes Dataset. Das Zieldataset wird immer als datasetId im JSON-Body übergeben, nicht im URL-Pfad.

Der Request-Body erfordert datasetId plus genau eines aus sessionId (eine Upload-Sitzung eines hochgeladenen Archivs) oder sourceUrl (eine entfernte ZIP-, TAR-, TAR.GZ-, TGZ- oder NDJSON-URL). Füge optional targetSplit (train, val oder test) hinzu, um die Split-Struktur des Archivs zu überschreiben. Um benutzerdefinierte Metadaten anzuhängen, verwende imageMetadata, geschlüsselt nach dem exakten archivrelativen Pfad jedes Bildes oder dem NDJSON-Wert file.

Bei hochgeladenen Archiven ist die Upload-Sitzung bereits durch das an POST /api/upload/signed-url übergebene assetId an das Dataset gebunden; Ingest validiert, dass assetId mit dem Body datasetId übereinstimmt. Optionale classMapping-Einträge ordnen jeden eingehenden Klassennamen einem bestehenden nulllbasierten Klassenindex, einem wiederzuverwendenden oder zu erstellenden Klassennamen oder null zum Überspringen der Klasse zu. Für entfernte sourceUrl-Importe erstelle zuerst das Dataset und übergebe dann dessen datasetId an Ingest.

Body (hochgeladenes Archiv):

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

Body (ein oder mehrere Bilder mit Metadaten):

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "imageMetadata": {
        "airbus-wing.jpg": { "aircraft": { "family": "A350" }, "inspectionStatus": "reviewed" },
        "images/tail.jpg": { "aircraft": { "family": "A320" }, "inspectionSeverity": 2 }
    }
}

Lokale Bilder verwenden den bestehenden Archiv-Upload-Ablauf, unabhängig davon, ob das Archiv ein Bild oder viele enthält. Der Schlüssel muss dem normalisierten Pfad innerhalb des Archivs einschließlich Ordnern entsprechen. Bei NDJSON-Importen kann jeder Bildeintrag stattdessen ein eigenes metadata-Objekt enthalten. Datensatzlokales metadata hat Vorrang vor einem übereinstimmenden imageMetadata-Eintrag.

Metadaten sind JSON und unterstützen verschachtelte Werte. Archivpfade sind auf 1.024 Zeichen begrenzt, Top-Level-Metadatenschlüssel auf 128 Zeichen und jedes Metadatenobjekt auf 500.000 serialisierte Zeichen. Die vollständige imageMetadata-Map oder die kombinierten effektiven Metadaten über einen NDJSON-Import hinweg sind ebenfalls auf 500.000 serialisierte Zeichen begrenzt. Diese Einschränkungen sind im interaktiven OpenAPI-Schema enthalten.

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
dataset_id = "dataset_abc123"
image_path = Path("airbus-wing.jpg")

archive = io.BytesIO()
with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as zf:
    zf.write(image_path, image_path.name)
data = archive.getvalue()

signed = requests.post(
    f"{api}/upload/signed-url",
    headers=headers,
    json={
        "assetType": "datasets",
        "assetId": dataset_id,
        "filename": "images.zip",
        "contentType": "application/zip",
        "totalBytes": len(data),
    },
)
signed.raise_for_status()
upload = signed.json()

requests.put(upload["uploadUrl"], headers={"Content-Type": "application/zip"}, data=data).raise_for_status()
requests.post(
    f"{api}/upload/complete",
    headers=headers,
    json={"sessionId": upload["sessionId"]},
).raise_for_status()

ingest = requests.post(
    f"{api}/datasets/ingest",
    headers=headers,
    json={
        "datasetId": dataset_id,
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

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

Dataset-Bilder#

Bilder auflisten#

GET /api/datasets/{datasetId}/images

Abfrageparameter:

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

Signierte Bild-URLs abrufen#

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

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

Bild löschen#

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

Bild-Labels abrufen#

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

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

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

Massen-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

Projekte API#

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

Projekte auflisten#

GET /api/projects

Abfrageparameter:

Projekt abrufen#

GET /api/projects/{projectId}

Projekt 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",
    "metadata": {"department": "manufacturing", "cost_center": "cv-01"}
  }' \
  https://platform.ultralytics.com/api/projects

Projekt aktualisieren#

PATCH /api/projects/{projectId}

Body (partielle Aktualisierung):

{
    "metadata": { "department": "research", "program": "inspection" }
}

Sende ein leeres metadata-Objekt ({}), um es zu löschen. Projekt-Metadaten verwenden dieselben Limits für Top-Level-Schlüssel (128 Zeichen) und serialisierte Objekte (500.000 Zeichen) wie Dataset-Metadaten.

Projekt-Metadaten abrufen#

GET /api/projects/{projectId}/metadata

Gibt das benutzerdefinierte Metadatenobjekt und schreibgeschützte, von Ultralytics verwaltete Feld/Wert-Paare zurück. Authentifizierung und Projekt-Arbeitsbereichszugriff sind erforderlich.

Projekt löschen#

DELETE /api/projects/{projectId}

Löscht das Projekt logisch (wird in den Papierkorb verschoben).

Projekt klonen#

POST /api/projects/{projectId}/clone

Klonet ein öffentliches, eigenes oder bearbeitbares Workspace-Projekt und dessen Modelle in deinen Account oder Workspace. Ein optionaler JSON-Body akzeptiert Überschreibungen für name, slug, description, visibility, license und das Ziel owner.

Projekt-Icon#

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

Lade ein WebP-Symbol von bis zu 5 MB als Multipart-Formulardatenfeld image hoch oder entferne das aktuelle Symbol.

Models API#

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

Modelle auflisten#

GET /api/models

Abfrageparameter:

Abgeschlossene Modelle auflisten#

GET /api/models/completed

Gibt bis zu 1.000 Modelle mit verwendbaren Weights über alle Projekte hinweg für Training und Deployment zurück. Übergebe owner für einen Workspace.

Modell abrufen#

GET /api/models/{modelId}

Modell erstellen#

POST /api/models

JSON Body:

Modell aktualisieren#

PATCH /api/models/{modelId}

Body (partielle Aktualisierung):

{
    "metadata": { "release": "candidate-3", "reviewed": true }
}

Sende ein leeres metadata-Objekt ({}), um es zu löschen. Benutzerdefinierte Modell-Metadaten sind von trainingsbezogenen Modellinformationen, Umgebungsdetails und Trainingsargumenten getrennt und verwenden dieselben Limits für serialisierte Objekte und Top-Level-Schlüssel wie Dataset-Metadaten.

Modell-Metadaten abrufen#

GET /api/models/{modelId}/metadata

Gibt das benutzerdefinierte Metadatenobjekt und schreibgeschützte, von Ultralytics verwaltete Feld/Wert-Paare zurück. Authentifizierung und Modell-Arbeitsbereichszugriff sind erforderlich.

Modell löschen#

DELETE /api/models/{modelId}

Modelldateien herunterladen#

GET /api/models/{modelId}/files

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

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

Download nachverfolgen#

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

Analysedaten für den Modelldownload nachverfolgen.

Fü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:

Stelle entweder file oder source bereit. 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:

Antworten enthalten pro Bild shape, speed, results und optionale dichte Pixel-Map-Daten (eine semantische Klassen-Map oder eine Tiefen-Map, bei der depth = pixel × max / divisor – Teiler 255 für die standardmäßige 8-Bit-Map, 65535 mit bits=12|16), plus metadata mit Bildanzahl, Funktionszeitmessung, Aufgabe und Dienstversionen. 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
    }
}

Training API#

Starte das YOLO-Training auf Cloud-GPUs (26 GPU-Typen von RTX 2000 Ada bis B300) und überwache den Fortschritt in Echtzeit. Siehe 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

Training 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

GPU-Verfügbarkeit abrufen#

GET /api/training/gpu-availability

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

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

Training abbrechen#

DELETE /api/models/{modelId}/training

Beendet die laufende Recheninstanz und markiert den Job als abgebrochen.

Deployments API#

Deploye Modelle auf dedizierte Inferenz-Endpunkte mit Integritätsprüfungen und Monitoring. Neue Deployments verwenden standardmäßig Skalierung auf Null, 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

Deployments auflisten#

GET /api/deployments

Abfrageparameter:

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

Deployment abrufen#

GET /api/deployments/{deploymentId}

Deployment löschen#

DELETE /api/deployments/{deploymentId}

Deployment starten#

POST /api/deployments/{deploymentId}/start

Ein gestopptes Deployment fortsetzen.

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

Gesundheitsprüfung#

GET /api/deployments/{deploymentId}/health

Gibt den Gesundheitsstatus des Deployment-Endpunkts zurück.

Inferenz 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:

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

Metriken abrufen#

GET /api/deployments/{deploymentId}/metrics

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

Abfrageparameter:

Logs abrufen#

GET /api/deployments/{deploymentId}/logs

Abfrageparameter:

Export-API#

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

Exporte auflisten#

GET /api/exports

Abfrageparameter:

Export 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 Argument format aus der gemeinsamen Exporttabelle unten. PyTorch ist das Quellformat und kein API-Exportziel.

Export-Status abrufen#

GET /api/exports/{exportId}

Export abbrechen#

DELETE /api/exports/{exportId}

Export-Download verfolgen#

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

Aktivitäts-API#

Zeige einen Feed aktueller Aktionen in deinem Account an – Trainingsläufe, Uploads und mehr. Siehe Activity-Dokumentation.

Aktivitäten auflisten#

GET /api/activity

Abfrageparameter:

Ereignisse 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 Abfrageparameter owner, um Ereignisse in einem Workspace zu markieren.

Ereignisse 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 Abfrageparameter owner, um Workspace-Ereignisse zu archivieren oder wiederherzustellen.

Papierkorb-API#

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

Papierkorb auflisten#

GET /api/trash

Abfrageparameter:

Element wiederherstellen#

POST /api/trash

Body:

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

Element endgültig löschen#

DELETE /api/trash

Body:

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

Papierkorb leeren#

DELETE /api/trash/empty

Löscht alle Elemente im Papierkorb endgültig.

Abrechnungs-API#

Überprüfe dein Guthaben, die Tarifnutzung und den Transaktionsverlauf. Siehe Billing-Dokumentation.

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

Guthaben abrufen#

GET /api/billing/balance

Antwort:

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

Nutzungsübersicht abrufen#

GET /api/billing/usage-summary

Gibt Plandetails, Limits und Nutzungsmetriken zurück.

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

Speicher-API#

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

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

Cloud-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 Operationen akzeptieren den optionalen Abfrageparameter owner für einen Workspace. Die Objektdurchsuchung akzeptiert zudem den erforderlichen Abfrageparameter target plus optionale Abfrageparameter prefix und Anbieter cursor. Request-Bodies für Verbindungen und Erkennung verwenden die Anmeldeinformationen-Schemata des Anbieters in der interaktiven OpenAPI-Referenz; Anmeldeinformationen werden niemals zurückgegeben.

Upload-API#

Lade Dateien mit signierten URLs direkt in den Cloud-Speicher hoch, um schnelle und zuverlässige Transfers zu gewährleisten. Das Abschließen eines Modell-Uploads hängt seine Weights an. Das Abschließen des Uploads eines Dataset-Archivs protokolliert die Sitzung; übergebe dieses sessionId an POST /api/datasets/ingest, um die Verarbeitung zu starten. Siehe Data-Dokumentation.

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

Upload abschließen#

POST /api/upload/complete

Benachrichtige die Plattform, dass ein Datei-Upload abgeschlossen ist. Bei Modellen hängt dies die hochgeladenen Weights an. Bei Dataset-Archiven verifiziert und protokolliert dies die Upload-Sitzung; rufe danach POST /api/datasets/ingest auf, um die Dataset-Verarbeitung zu starten.

Body:

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

Integrations-API#

Importiere Datasets von Diensten Dritter. Siehe Integrations-Dokumentation.

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

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

API-Keys API#

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

API-Keys auflisten#

GET /api/api-keys

Über API-Keys authentifizierte Clients erhalten Key-Metadaten, niemals entschlüsselte bestehende Key-Werte. Ein neu erstellter Key wird einmal von POST /api/api-keys zurückgegeben.

Übergebe den optionalen Abfrageparameter owner, um Keys für einen Workspace zu verwalten, in dem du Editor-Zugriff hast.

API-Key erstellen#

POST /api/api-keys

Body:

{
    "name": "training-server"
}

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

Teams & Mitglieder API#

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

Teams auflisten#

GET /api/teams

Team erstellen#

POST /api/teams/create

Body:

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

Mitglieder auflisten#

GET /api/members

Gibt Mitglieder des aktuellen Arbeitsbereichs zurück.

Mitglied einladen#

POST /api/members

Body:

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

Mitgliedsrolle aktualisieren#

PATCH /api/members/{userId}

Mitglied entfernen#

DELETE /api/members/{userId}

Eigentümerschaft übertragen#

POST /api/members/transfer-ownership

Explore API#

Durchsuche und entdecke öffentliche Datasets und Projekte, die von der Community geteilt wurden. Siehe Explore-Dokumentation.

Öffentliche Inhalte durchsuchen#

GET /api/explore/search

Abfrageparameter:

Sidebar-Daten#

GET /api/explore/sidebar

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

Benutzer- & Einstellungs-APIs#

Verwalte dein Profil, deine API-Keys, Speichernutzung und Team-Workspaces. Siehe Settings-Dokumentation.

Kontoübersicht#

GET /api/account/summary

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

Benutzer nach Benutzername abrufen#

GET /api/users

Abfrageparameter:

Benutzer folgen oder entfolgen#

PATCH /api/users

Body:

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

Benutzernamen-Verfügbarkeit prüfen#

GET /api/username/check

Abfrageparameter:

Einstellungen#

GET /api/settings
POST /api/settings

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

Workspace-Icon#

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

Lade ein WebP-Profil-/Workspace-Symbol von bis zu 5 MB als Multipart-Formulardatenfeld image hoch oder entferne es. Übergebe optional owner für einen Team-Workspace.

Python-Integration#

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

Installation & Einrichtung#

pip install "ultralytics>=8.4.104"

Installation überprüfen:

yolo check

Authentifizierung#

yolo login YOUR_API_KEY

Plattform-Datensätze verwenden#

Referenziere Datasets 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:

Push 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

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

FAQ#

Wie 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 ebenfalls einen page-Parameter für die seitenbasierte Paginierung:

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

Der Endpunkt „Explore Search“ verwendet anstelle von page den Parameter offset mit einer festen Seitengröße von 20:

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

Kann ich die API ohne SDK nutzen?#

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

Gibt es API-Client-Bibliotheken?#

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

Wie gehe ich mit Ratenbegrenzungen um?#

Verwende den Retry-After-Header aus der 429-Antwort, um die richtige Wartezeit einzuhalten:

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

Wie 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 Listen-Endpunkte, um die entsprechende _id für ein Modell, einen Datensatz, ein Projekt, eine Bereitstellung oder eine andere Ressource zu finden.