REST-API-Referenz#

Ultralytics Platform bietet eine REST API für den programmgesteuerten Zugriff auf Datensätze, Bilder, Projekte, Modelle, Training, Exporte und Bereitstellungen.

# List the datasets owned by a workspace
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/datasets/YOUR_USERNAME

API-Übersicht#

Die API ist nach den zentralen Ressourcen der Platform gegliedert:

Authentifizierung#

Für die meisten Endpunkte ist ein API-Schlüssel erforderlich. Endpunkte, die öffentliche Inhalte bereitstellen – etwa das Lesen eines öffentlichen Datensatzes, Projekts oder Modells, das Auflisten öffentlicher Datensatzbilder, das Ausführen von Inferenz mit einem öffentlichen Modell oder die Suche unter „Entdecken“ – akzeptieren auch anonyme Anfragen und liefern mit einem Schlüssel einfach mehr Ergebnisse.

API-Schlüssel abrufen#

1. Gehe zu Settings > API Keys
2. Klicke auf Add Key, belasse Ultralytics als Anbieter, gib einen Namen ein und klicke auf Create Key
3. Kopiere den generierten Schlüssel

Eine ausführliche Anleitung findest du unter API-Schlüssel.

Autorisierungsheader#

Füge deinen API-Schlüssel als Bearer-Token hinzu:

Authorization: Bearer YOUR_API_KEY

Beispiel#

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

Basis-URL#

Für alle API-Endpunkte gilt:

https://platform.ultralytics.com/api

Ressourcenpfade#

Die meisten Ressourcen werden über dieselben lesbaren Namen angesprochen, die auch in den URLs der Platform erscheinen, nicht über Datenbank-IDs:

• {owner} ist ein persönlicher Benutzername oder der Bezeichner eines Teamarbeitsbereichs: 4–32 Zeichen, Kleinbuchstaben und Ziffern, mit einzelnen Bindestrichen zwischen den Abschnitten.
• {dataset}, {project}, {model} und {deployment} folgen demselben Muster aus Kleinbuchstaben und Bindestrichen und dürfen bis zu 128 Zeichen lang sein.
• {imageId}, {exportId} und {agentId} sind hexadezimale IDs mit 24 Zeichen, die von der API zurückgegeben werden.
• Wenn du eine Ressource über PATCH umbenennst, ändern sich der Anzeigename name und der URL-Name gemeinsam. Die Antwort gibt den aktuellen URL-Namen zurück, damit du ihm weiterhin folgen kannst.

Ratenbegrenzungen#

Die API setzt für jeden API-Schlüssel gleitende Zeitfensterlimits durch. Jede Route fällt in eine Kategorie, und jede Kategorie hat einen unabhängigen Zähler. Daher verbrauchen 20 Vorhersageanfragen nicht dein Standardkontingent.

Nur im Browser verfügbare Platform-Routen wie der Checkout für die Abrechnung und die Teamverwaltung haben eigene Limits, die nicht für Datenverkehr mit API-Schlüsseln gelten.

Bei einer Drosselung gibt die API 429 zusammen mit Headern und einem JSON-Body zurück:

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

{
    "error": "Rate limit exceeded, wait 12s",
    "retryAfter": 12,
    "resetAt": "2026-02-21T12:34:56.000Z"
}

Dedizierte Endpoints (unbegrenzt)#

Dedizierte Endpoints unterliegen nicht den Ratenlimits der Platform-API-Schlüssel, wenn du den serviceUrl des Deployments direkt aufrufst (zum Beispiel https://predict-abc123.run.app/predict). Der Durchsatz hängt dann von der Konfiguration des bereitgestellten Dienstes ab.

Antwortformat#

Erfolgreiche Antworten#

Antworten sind JSON-Objekte mit ressourcenspezifischen Feldern. Es gibt keinen allgemeinen Umschlag: Listen-Endpoints geben eine benannte Sammlung zurück, meist zusammen mit Zählerständen, und Änderungsoperationen geben die geänderten Kennungen zurück.

{
    "datasets": [{ "id": "65f1c0a2b3d4e5f601234567", "owner": "acme-vision", "dataset": "warehouse" }],
    "total": 1,
    "region": "us"
}

Ressourcenlisten, Antworten auf Erstellungs- und Klonvorgänge sowie einige Lesezugriffe wie Deployments, Speicher und Papierkorb enthalten ebenfalls region (us, eu oder ap), die Speicherregion für diesen Workspace.

Fehlerantworten#

Jede Fehlerantwort ist ein JSON-Objekt mit einer error-Meldung:

{
    "error": "Dataset not found"
}

Seitennummerierung#

Der Stil der Paginierung hängt von der Sammlung ab:

Datasets API#

Erstelle, durchsuche und verwalte annotierte Bilddatensätze für das Training von YOLO-Modellen. Siehe die Dokumentation zu Datensätzen.

Datensätze auflisten#

GET /api/datasets/{owner}

Python SDK: client.datasets.list(owner)

Gibt die öffentlichen Datensätze des Besitzers sowie private Datensätze zurück, wenn dein Schlüssel Zugriff auf diesen Workspace hat.

Abfrageparameter:

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

Antwort:

{
    "datasets": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "owner": "acme-vision",
            "dataset": "warehouse",
            "name": "Warehouse",
            "task": "detect",
            "visibility": "private",
            "imageCount": 1000,
            "classCount": 2,
            "classNames": ["person", "forklift"],
            "splits": { "train": 800, "val": 200, "test": 0, "labeled": 1000 },
            "annotationCount": 5400,
            "starCount": 3,
            "isStarred": false,
            "status": "ready",
            "createdAt": "2026-01-15T10:00:00Z",
            "updatedAt": "2026-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

Datensatz abrufen#

GET /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.retrieve(owner, dataset)

Gibt das vollständige Datensatzobjekt unter einem dataset-Schlüssel zurück, einschließlich classNames, splits, versions, source und des benutzerdefinierten metadata-Objekts. Während ein Import von mindestens 10.000 Bildern verarbeitet wird, erhalten Bearbeiter außerdem processingProgress mit stage, percent und, falls bekannt, processed, total und objects (gescannte Cloud-Objekte).

Datensatz erstellen#

POST /api/datasets

Python SDK: client.datasets.create(dataset=..., name=...)

Body:

{
    "dataset": "warehouse",
    "name": "Warehouse",
    "task": "detect",
    "description": "Forklift and pedestrian safety dataset",
    "classNames": ["person", "forklift"],
    "visibility": "private",
    "metadata": { "location": "factory-1", "reviewed": true },
    "owner": "acme-vision"
}

Ein dataset-Slug, der im Workspace bereits existiert, auch im Papierkorb, führt zu 409.

Antwort (201):

{
    "id": "65f1c0a2b3d4e5f601234567",
    "owner": "acme-vision",
    "dataset": "warehouse",
    "region": "us"
}

Datensatz aktualisieren#

PATCH /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.update(owner, dataset)

Body (Teilaktualisierung):

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

Zulässige Felder: name, description, visibility, metadata, tags, classNames, classColors, format, task, license, iconColor, iconLetter, starred, blurFaces, kptSkeletonId (weist einem Pose-Datensatz eine Pose-Skelettvorlage zu) und initializeClassNames (bei der Aktualisierung wird 409 zurückgegeben, sofern der Datensatz bereits Klassen oder Annotationen enthält). Sende ein leeres metadata-Objekt ({}), um benutzerdefinierte Metadaten zu löschen. Metadatenschlüssel dürfen höchstens 128 Zeichen und das serialisierte Objekt höchstens 500.000 Zeichen umfassen.

Antwort:

{
    "success": true,
    "dataset": "warehouse-safety"
}

Beim Umbenennen ändert sich der URL-Name. Verwende daher für nachfolgende Requests den zurückgegebenen Wert dataset.

Datensatz löschen#

DELETE /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.delete(owner, dataset)

Verschiebt den Datensatz in den Papierkorb, wo er 30 Tage lang wiederhergestellt werden kann.

Datensatz klonen#

POST /api/datasets/{owner}/{dataset}/clone

Python SDK: client.datasets.clone(owner, dataset)

Kopiert einen zugänglichen Datensatz samt Bildern und Labels in deinen persönlichen Workspace oder einen Team-Workspace.

Optionaler Body (alle Felder optional):

{
    "dataset": "warehouse-copy",
    "name": "Warehouse Copy",
    "description": "Cloned for experimentation",
    "visibility": "private",
    "license": "CC-BY-4.0",
    "owner": "acme-vision"
}

Antwort (201): id, owner, dataset, name, imageCount, classCount und region. Datensätze, die auf einer verbundenen Speicherquelle basieren, geben 409 zurück, da ihre Dateien nicht kopiert werden.

Datensatzexport herunterladen#

GET /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.export(owner, dataset)

Gibt eine signierte NDJSON-Download-URL zurück. Lasse v weg, um den aktuellen Stand des Datensatzes zu exportieren. Wenn sich seit der Erstellung nichts geändert hat, wird der zwischengespeicherte Export wiederverwendet.

Abfrageparameter:

Antwort:

{
    "downloadUrl": "https://storage.googleapis.com/...&signature=...",
    "cached": true
}

Wenn du eine bestimmte Version anforderst, werden downloadUrl und version statt cached zurückgegeben.

Datensatzversion erstellen#

POST /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.create_export(owner, dataset)

Erstellt eine unveränderliche, nummerierte Version des Datensatzes. Erfordert Bearbeitungszugriff. Setze download auf false, um die Version zu speichern, ohne einen NDJSON-Download vorzubereiten; in diesem Fall wird downloadUrl weggelassen. Das SDK akzeptiert download von ultralytics-platform>=0.1.73.

Body (optional):

{
    "description": "Added 500 training images",
    "download": true
}

Antwort:

{
    "version": 3,
    "downloadUrl": "https://storage.googleapis.com/...&signature=...",
    "reused": false
}

reused ist true, wenn der Datensatz mit einer vorhandenen Version übereinstimmt, zum Beispiel direkt nach der Wiederherstellung. Stattdessen wird diese Version zurückgegeben und ihre Beschreibung aktualisiert, wenn du eine sendest.

Versionsbeschreibung aktualisieren#

PATCH /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.update_export(owner, dataset, version=..., description=...)

Body:

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

Antwort: {"ok": true}

Datensatzversion wiederherstellen#

POST /api/datasets/{owner}/{dataset}/restore

Python SDK: client.datasets.restore(owner, dataset, version=...)

Stellt Bilder, Annotationen und Klassen aus einer gespeicherten Version wieder her, ohne die Bilddaten zu kopieren.

Body:

{
    "version": 2
}

Antwort: {"version": 2, "imageCount": 1000}

Datensatzversionen vergleichen#

GET /api/datasets/{owner}/{dataset}/versions/compare?base={from}&head={to}

Python SDK: client.datasets.compare(owner, dataset, base=1, head=2) (ultralytics-platform>=0.1.73)

Antwort (gekürzt):

{
    "summary": { "added": 0, "removed": 1, "modified": 1, "moved": 1, "labelsAdded": 1, "labelsRemoved": 2 },
    "items": [
        {
            "hash": "b5c605c133f84c3024af7e652b135501",
            "name": "000000000042",
            "change": "moved",
            "base": { "split": "val", "labelCount": 1 },
            "head": { "split": "test", "labelCount": 1 }
        }
    ]
}

summary erscheint nur auf der ersten Seite und enthält die exakten Gesamtzahlen sowie ein header, das hinzugefügte, entfernte oder umbenannte Klassen und andere abweichende Datensatzfelder aufführt. change jedes Elements ist added, removed, modified (mit dem geänderten fields) oder moved (Split geändert); labelsRemoved enthält die Labels entfernter Bilder. Wenn nextCursor vorhanden ist, übergib es als cursor für die nächste Seite. Mit hash lautet die Antwort versions: das Bild, wie es in jeder Version gespeichert ist, mit seinen Labels und einem signierten imageUrl. Beide Reihenfolgen funktionieren; wenn du base und head vertauschst, wird ein entferntes Bild als hinzugefügt gemeldet. Für Vergleiche gilt das standardmäßige Ratenlimit. Requests ohne hash sind außerdem auf 10 pro Minute und Nutzer-Datensatz-Kombination begrenzt, unabhängig davon, welcher API-Schlüssel sie sendet.

Datasetstatistiken abrufen#

GET /api/datasets/{owner}/{dataset}/class-stats

Python SDK: client.datasets.class_stats(owner, dataset)

Gibt Annotationszahlen pro Klasse, Bild- und Annotationshistogramme sowie Heatmaps zurück. Große Datensätze werden stichprobenartig ausgewertet. In diesem Fall gibt sampleSize an, wie viele Bilder berücksichtigt wurden.

Antwort (gekürzt):

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120, "size": 1 }],
        "heightHistogram": [{ "bin": 480, "count": 95, "size": 1 }],
        "pointsHistogram": [{ "bin": 4, "count": 200, "size": 1 }],
        "formatDistribution": { "jpg": 900, "png": 100 },
        "fileSizeHistogram": [{ "bin": 250000, "count": 300, "size": 50000 }],
        "objectsPerImageHistogram": [{ "bin": 5, "count": 210, "size": 1 }],
        "bboxWidthHistogram": [{ "bin": 120, "count": 340, "size": 20 }],
        "bboxHeightHistogram": [{ "bin": 90, "count": 300, "size": 20 }]
    },
    "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", "forklift"],
    "cached": true,
    "sampleSize": null
}

Klassen verwalten#

Klassen zusammenführen (Annotationen einer Zielklasse zuweisen und anschließend die Quellklassen entfernen):

POST /api/datasets/{owner}/{dataset}/classes/merge

Python SDK: client.datasets.merge_classes(owner, dataset, source_class_ids=..., target_class_id=...)

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

Klassen löschen (ihre Annotationen werden gelöscht und die IDs der übrigen Klassen rücken nach):

POST /api/datasets/{owner}/{dataset}/classes/delete

Python SDK: client.datasets.delete_classes(owner, dataset, class_ids=...)

{
    "classIds": [2, 4]
}

Beide Vorgänge geben success, die aktualisierten classNames und classColors sowie eine Zusammenfassung der Änderungen zurück (mergedClassIds und targetClassId oder deletedClassIds und deletedAnnotations).

Datensatzaufteilungen neu verteilen#

POST /api/datasets/{owner}/{dataset}/splits/redistribute

Python SDK: client.datasets.redistribute_splits(owner, dataset, train=..., val=..., test=...)

Weist Bilder nach dem Zufallsprinzip den Aufteilungen neu zu. Die drei Prozentangaben müssen zusammen 100 ergeben.

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

Antwort: success, die resultierenden Anzahlen von splits und modified (Anzahl der verschobenen Bilder).

Datensatz-Embeddings#

GET /api/datasets/{owner}/{dataset}/embeddings
POST /api/datasets/{owner}/{dataset}/embeddings
DELETE /api/datasets/{owner}/{dataset}/embeddings

Python SDK: client.datasets.embeddings(owner, dataset), client.datasets.create_embeddings(owner, dataset), client.datasets.delete_embeddings(owner, dataset)

GET gibt die Analysezusammenfassung zurück (analyzedAt, embeddingsCount, latestImageAt, activeJob). POST stellt eine Embedding-Analyse in die Warteschlange und gibt 202 mit einem jobId zurück. DELETE bricht den aktiven Auftrag ab und gibt die ID des abgebrochenen Auftrags oder null zurück.

Bildclusterung#

GET /api/datasets/{owner}/{dataset}/images/clustering

Python SDK: client.datasets.clustering(owner, dataset)

Gibt das UMAP-2D-Layout einer abgeschlossenen Analyse zurück, paginiert mit offset und limit (Standardwert und Maximum: 50.000). Jeder Eintrag enthält id, umapX, umapY, cluster, split, classIds, width, height, bytes, labelCount, labeled und missing. cluster bezeichnet die visuelle Insel des Punkts, nach Größe sortiert (0 = größte, -1 = verstreut), oder null bei Layouts, die vor der Einführung der Clusterung analysiert wurden.

Auf einem Datensatz trainierte Modelle auflisten#

GET /api/datasets/{owner}/{dataset}/models

Python SDK: client.datasets.models(owner, dataset)

Antwort:

{
    "models": [
        {
            "id": "65f1c0a2b3d4e5f601234599",
            "owner": "acme-vision",
            "project": "inspection",
            "model": "v3",
            "name": "v3",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "metrics": { "mAP50": 0.85, "mAP50-95": 0.72, "precision": 0.88, "recall": 0.81 },
            "startedAt": "2026-01-14T22:00:00Z",
            "completedAt": "2026-01-15T10:00:00Z",
            "createdAt": "2026-01-14T21:55:00Z"
        }
    ],
    "count": 1
}

Datensatzbilder auflisten#

GET /api/datasets/{owner}/{dataset}/images

Python SDK: client.datasets.images(owner, dataset)

Abfrageparameter:

Antwort:

{
    "images": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "hash": "9f2c1d4b6a8e0f3c5d7b9a1e2f4c6d8b",
            "ext": "jpg",
            "name": "aisle-04",
            "thumbnailUrl": "https://storage.googleapis.com/...&signature=...",
            "width": 1920,
            "height": 1080,
            "split": "train",
            "labelCount": 6,
            "bytes": 284213,
            "error": null
        }
    ],
    "total": 1000,
    "hasMore": true,
    "classes": ["person", "forklift"],
    "errorCount": 0,
    "nextCursor": "65f1c0a2b3d4e5f601234567"
}

Ausgewählte Bilder abrufen#

POST /api/datasets/{owner}/{dataset}/images

Python SDK: client.datasets.selected_images(owner, dataset, image_ids=...)

Gibt für bis zu 1.000 angegebene Bild-IDs dieselbe Bildstruktur zurück und akzeptiert dieselben Filter- und URL-Abfrageparameter wie der Auflistungsendpunkt.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}

Bilder kopieren oder verschieben#

POST /api/datasets/{owner}/{dataset}/images/adopt

Python SDK: client.datasets.adopt_images(owner, dataset, image_ids=..., release=...) (ultralytics-platform>=0.1.50)

Kopiert bis zu 1.000 Bilder aus anderen Datensätzen in diesen Datensatz – wie es die Funktion Kopieren und Einfügen der App tut – und gibt die Anzahl adopted zurück.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"],
    "release": false,
    "classMapping": { "person": 0, "vase": null }
}

Wenn du release oder classMapping festlegst, bleiben Beschriftungen und Aufteilungen aus Datensätzen erhalten, die du bearbeiten kannst: release: false kopiert Bilder und release: true verschiebt sie aus ihrem Quelldatensatz. Wenn du beide Felder weglässt, werden unbeschriftete train-Bilder importiert. Das gilt auch beim Kopieren aus einer schreibgeschützten Quelle. Beim Verschieben aus einer schreibgeschützten Quelle wird 403 zurückgegeben. Vorhandene Bilder werden übersprungen. Wenn Beschriftungen und Aufteilungen beibehalten werden, wird auf Duplikate innerhalb der Zielaufteilung geprüft. Klassen werden anhand ihres Namens abgeglichen; bei Namen mit mehr als zwei Zeichen wird die Groß- und Kleinschreibung ignoriert. 422 gibt die Quellklassen zurück, für die es in unmatchedClasses keine Übereinstimmung gibt. classMapping ordnet jede Klasse einem Klassenindex oder einem neuen Klassennamen zu oder verwirft ihre Beschriftungen mit null. 409 bedeutet, dass es sich beim Ziel um einen verbundenen Datensatz handelt oder eine Quelle beziehungsweise ein Ziel gerade ausgelastet ist. Wenn Beschriftungen und Aufteilungen beibehalten werden, geben auch inkompatible Aufgaben, Bildkanäle, Poseneinstellungen oder Tiefenskalen 409 zurück – selbst bei Bildern ohne Beschriftungen.

Datensatzdaten importieren#

POST /api/datasets/{owner}/{dataset}/ingest

Python SDK: client.datasets.ingest(owner, dataset, body=...)

Verarbeitet einen abgeschlossenen Upload, ein entferntes Archiv oder eine verbundene Speicherquelle und fügt die Daten einem vorhandenen Datensatz hinzu. Gib genau eine Quelle an:

Uploadsitzungen sind über assetId, das an POST /api/upload/signed-url übergeben wird, an einen Datensatz gebunden. Beim Import wird eine Sitzung abgelehnt, die zu einem anderen Datensatz gehört.

Textkörper (hochgeladenes Archiv):

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

Textkörper (entferntes Archiv oder NDJSON):

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

Textkörper (Bezeichnungen bei einem späteren Import einlesen):

{
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "forklift", "background": null }
}

Textkörper (Metadaten für einzelne Bilder hinzufügen):

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

Metadatenschlüssel müssen dem normalisierten Pfad innerhalb des Archivs einschließlich der Ordner entsprechen. Bei NDJSON-Importen kann jeder Datensatz sein eigenes Objekt metadata enthalten, das Vorrang vor einem passenden Eintrag in imageMetadata hat. Archivpfade dürfen höchstens 1.024 Zeichen lang sein, Metadatenschlüssel der obersten Ebene höchstens 128 Zeichen und jedes Metadatenobjekt sowie die gesamte Zuordnung imageMetadata höchstens 500.000 serialisierte Zeichen umfassen.

Antwort (201):

{
    "jobId": "65f1c0a2b3d4e5f6012345aa",
    "status": "queued"
}

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
owner, dataset = "acme-vision", "warehouse"
dataset_id = "65f1c0a2b3d4e5f601234567"  # id returned by POST /api/datasets
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()

headers_put = {"Content-Type": "application/zip", **upload.get("headers", {})}
requests.put(upload["uploadUrl"], headers=headers_put, 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/{owner}/{dataset}/ingest",
    headers=headers,
    json={
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

Bilder-API#

Datensatzbilder anhand ihrer 24-stelligen Bild-ID prüfen, annotieren, verschieben und löschen. Weitere Informationen findest du in der Dokumentation zu Annotationen.

Bild abrufen#

GET /api/images/{imageId}

Python SDK: client.images.retrieve(image_id)

Gibt metadata (benutzerdefinierte Angaben), properties (Dateiname, Hash, Abmessungen, Aufteilung, Anzahlen, Zeitstempel), labels und classNames des Datensatzes zurück.

Bild aktualisieren#

PATCH /api/images/{imageId}

Python SDK: client.images.update(image_id, body=...)

Ersetzt entweder die Annotationen oder die benutzerdefinierten Metadaten – sende eine der beiden Strukturen, nicht beide.

Textkörper (Annotationen):

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

Textkörper (Metadaten):

{
    "metadata": { "location": "strasbourg", "reviewed": true }
}

Bild löschen#

DELETE /api/images/{imageId}

Python SDK: client.images.delete(image_id)

Löscht ein Bild und seine Annotationen dauerhaft.

Bild automatisch annotieren#

POST /api/images/{imageId}/predict

Python SDK: client.images.predict(image_id, model_id=...)

Führt das Modell auf dem Bild aus und gibt vorhergesagte Annotationen zurück. Diese werden nicht gespeichert – schreibe die Ergebnisse mit PATCH /api/images/{imageId} zurück, wenn du damit zufrieden bist.

Antwort: success, predictions (Annotationsobjekte), confidences (indexgleiche Konfidenzwerte, bei Modellen mit Klassenabfrage leer), modelUsed, inferenceTime; bei Modellen mit Klassenabfrage partial (true, wenn die abgeschnittene Ausgabe eines generativen Modells nur vollständige Rahmen enthielt); bei kostenpflichtigen Anbietermodellen optional cost (geschätzte Anbieterkosten in USD, die über deinen Anbieterschlüssel abgerechnet werden; entfällt, wenn keine Schätzung verfügbar ist). Gibt ein YOLO-Modell Klassen zurück, die nicht zum Datensatz passen, wird 422 zurückgegeben. Dasselbe gilt für ein Modell mit Klassenabfrage bei einem Datensatz ohne Erkennungsaufgabe oder mit einer Klassenzahl außerhalb von 1–200 sowie für ein kostenpflichtiges Anbietermodell ohne im Arbeitsbereich des Datensatzes unter Einstellungen > API-Schlüssel gespeicherten Anbieterschlüssel (code: missing_provider_api_key). Ein Anbieterfehler enthält die Meldung des Anbieters: 422, wenn der Anbieter 400, 401, 403 oder 404 zurückgibt (abgelehnter Schlüssel, abgelehntes Modell oder abgelehnte Anfrage), 429 bei Erreichen des Ratenlimits und 503 bei allen anderen Anbieterfehlern. Tiefendatensätze geben 400 zurück. Dasselbe gilt für Datensätze auf verbundenem Speicher oder mit mehr als 3 Bildkanälen: Sie geben 409 zurück.

Ähnliche Bilder finden#

GET /api/images/{imageId}/similar

Python SDK: client.images.find_similar_images(image_id)

Gibt bis zu 24 visuell ähnliche images aus öffentlichen Datensätzen sowie aus deinen eigenen und Team-Datensätzen zurück. Zu jedem gehören score (0–1), ein signiertes thumbnailUrl und die Quelle dataset (owner, dataset, license). Bilder, die bereits im Quelldatensatz vorhanden sind, und Kopien des Abfragebilds werden ausgeschlossen. Erfordert einen API-Schlüssel mit Lesezugriff auf das Bild. Ein Bild, für das noch kein Embedding erstellt wurde, wird zuerst eingebettet; 503 bedeutet, dass dieser Vorgang fehlgeschlagen ist – versuche es erneut.

Datensatz automatisch annotieren#

POST /api/datasets/{owner}/{dataset}/predict/batch

Python SDK: client.datasets.create_batch(owner, dataset, body={...}) (ultralytics-platform>=0.1.57)

Speichert eine Datensatzversion, stellt anschließend einen Auftrag in die Warteschlange, der die nicht annotierten Bilder des Datensatzes mit dem Modell beschriftet, und gibt 202 zurück. Der Textkörper akzeptiert dieselben Felder modelId, confidence, iou und classMapping wie der Endpunkt für einzelne Bilder sowie includeAnnotated (Standardwert false), um auch bereits beschriftete Bilder zu annotieren. Ein Modell mit Klassenabfrage erkennt die Datensatzklassen ohne Konfidenzwerte. Für ein kostenpflichtiges Anbietermodell ist ein im Arbeitsbereich des Datensatzes unter Einstellungen > API-Schlüssel gespeicherter Anbieterschlüssel erforderlich (422, code: missing_provider_api_key, bevor der Auftrag angenommen wird). Vorhandene Bezeichnungen werden nie geändert, und der Auftrag wird für die tatsächlich verarbeiteten Bilder abgerechnet. 402 bedeutet, dass das Guthaben die Kostenschätzung nicht abdeckt; 409 bedeutet, dass der Datensatz noch nicht bereit ist, keine Bilder mehr zu annotieren sind oder bereits ein Auftrag läuft. 422 bedeutet, dass der Datensatz keine Klassen hat oder dass ein Modell mit Klassenabfrage für einen Datensatz ohne Erkennungsaufgabe oder mit einer Klassenzahl außerhalb von 1–200 verwendet wird: Erstelle die Klassen über den Klassenendpunkt, bevor du diesen Endpunkt aufrufst. Genau das macht der Schritt „Klassen zuordnen“ in der App, bevor er einen Auftrag startet.

GET unter demselben Pfad (client.datasets.batch(owner, dataset)) gibt den laufenden Auftrag samt Fortschritt oder bis zu seiner Ausblendung den letzten abgeschlossenen Auftrag zurück. Dessen results enthält partialImages, wenn beim Auftrag eines generativen Modells aufgrund einer abgeschnittenen Ausgabe nur vollständige Rahmen übernommen wurden. DELETE (client.datasets.delete_batch(owner, dataset)) bricht einen laufenden Auftrag ab oder schließt die Abrechnung ab und blendet die Zusammenfassung des abgeschlossenen Auftrags aus.

Derselbe Endpunkt verwischt Gesichter mit "operation": "blur", confidence (Standardwert 0.25) und boxScale (0.5–1.5, Standardwert 1); imageId beschränkt den Auftrag auf ein Bild. Es wird keine Version erstellt und keine Bezeichnung geändert. Sende "preview": true, um bis zu sechs Bilder ohne Änderungen zu verarbeiten. Sende anschließend den zurückgegebenen Wert jobId als previewJobId mit denselben Einstellungen, um die Änderungen anzuwenden. Eine angewendete Vorschau kann nicht erneut verwendet werden; in diesem Fall wird 409 zurückgegeben. Solange eine Vorschau aussteht, kannst du ihre ID als previewJobId an DELETE übergeben, um sie zu verwerfen.

{ "operation": "blur", "confidence": 0.25, "boxScale": 1, "preview": true }

Bilder gesammelt verschieben#

PATCH /api/images/bulk

Python SDK: client.images.update_bulk(image_ids=..., split=...)

Verschiebt bis zu 1.000 Bilder aus einem Datensatz in eine andere Aufteilung.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"],
    "split": "val",
    "conflictPolicy": "skip"
}

Bei Konflikten mit Dateinamen oder Inhalten wird 409 zurückgegeben, bis du eine für den gesamten Stapel geltende Option conflictPolicy auswählst: skip, keep_both oder replace. Die Antwort enthält modifiedCount, skippedCount und targetSplit.

Bilder gesammelt löschen#

DELETE /api/images/bulk

Python SDK: client.images.delete_bulk(image_ids=...)

{
    "imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}

Löscht bis zu 1.000 Bilder aus einem einzelnen Datensatz und gibt deletedCount und deletedImageIds zurück.

Signierte Bild-URLs abrufen#

POST /api/images/urls

Python SDK: client.images.urls(image_ids=...)

Gibt temporäre signierte URLs für bis zu 100 Bild-IDs aus einem Datensatz zurück.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"]
}

Antwort: urls, thumbnails und depths (Vorschauen der Tiefenziele für zugeordnete Tiefenbilder), jeweils nach Bild-ID zugeordnet.

Projekt-API#

Organisiere deine Modelle in Projekten. Jedes Modell gehört zu genau einem Projekt. Weitere Informationen findest du in der Projektdokumentation.

Projekte auflisten#

GET /api/projects/{owner}

Python SDK: client.projects.list(owner)

Abfrageparameter:

Projekt abrufen#

GET /api/projects/{owner}/{project}

Python SDK: client.projects.retrieve(owner, project)

Gibt das Objekt project, ein Array models mit Zusammenfassungen pro Modell (Status, Metriken, Epochen, Gewichte, Trainingsargumente) und isOwner zurück. Übergib search (max. 200 Zeichen), um models nach Modellnamen oder Metadaten zu filtern.

Projekt erstellen#

POST /api/projects

Python SDK: client.projects.create(project=..., name=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "inspection",
    "name": "Inspection",
    "description": "Detection experiments",
    "metadata": {"department": "manufacturing", "cost_center": "cv-01"}
  }' \
  https://platform.ultralytics.com/api/projects

Antwort (201): id, owner, project, region.

Ein project-Slug, der im Workspace bereits existiert, auch im Papierkorb, führt zu 409.

Projekt aktualisieren#

PATCH /api/projects/{owner}/{project}

Python SDK: client.projects.update(owner, project)

Akzeptierte Felder: name, description, visibility, metadata, tags, license, archived, iconColor, iconLetter, viewPreferences und starred.

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

Sende ein leeres Objekt metadata ({}), um es zu leeren. Für Projektmetadaten gelten dieselben Beschränkungen wie für Dataset-Metadaten: maximal 128 Zeichen für den Schlüssel und 500.000 Zeichen für das serialisierte Objekt.

Projekt löschen#

DELETE /api/projects/{owner}/{project}

Python SDK: client.projects.delete(owner, project)

Verschiebt das Projekt und seine Modelle in den Papierkorb, gibt cascadedModels zurück und löscht alle zugehörigen Deployments endgültig. Beim Wiederherstellen des Projekts werden die Deployments nicht wiederhergestellt. 502 bedeutet, dass die Bereinigung der Deployments noch nicht abgeschlossen ist; die Modelle bleiben im Papierkorb, bis die Bereinigung erfolgreich abgeschlossen ist.

Projekt klonen#

POST /api/projects/{owner}/{project}/clone

Python SDK: client.projects.clone(owner, project)

Klont ein zugängliches Projekt und dessen abgeschlossene Modelle. Der optionale Body akzeptiert project, name, description, visibility, license und ein Ziel-owner.

Modelle-API#

Verwalte trainierte YOLO-Modelle — sieh dir Metriken an, lade Gewichte herunter, führe Inferenz aus und überwache das Training. Weitere Informationen findest du in der Dokumentation zu Modellen.

Modelle in einem Projekt auflisten#

GET /api/models/{owner}/{project}

Python SDK: client.models.list(owner, project)

Abfrageparameter:

Modell abrufen#

GET /api/models/{owner}/{project}/{model}

Python SDK: client.models.retrieve(owner, project, model)

Abfrageparameter:

Die Standardantwort enthält das Objekt model — Status, Aufgabe, Metriken, trainArgs, trainResults, classNames, computeCost, metadata und mehr — sowie isOwner.

Modell erstellen#

POST /api/models

Python SDK: client.models.create(body=...)

Erstellt einen nicht trainierten Modelleintrag, dem du Gewichte zuweisen oder den du trainieren kannst.

Antwort (201): id, owner, project, model, region.

Modell aktualisieren#

PATCH /api/models/{owner}/{project}/{model}

Python SDK: client.models.update(owner, project, model)

Zu den akzeptierten Feldern gehören name, description, color, metadata, status, license, datasetSlug, trainArgs, trainResults, epochs, bestEpoch, bestFitness, version, trainingError und starred. Wenn du ausschließlich projectId übergibst, verschiebt das Modell in ein anderes Projekt desselben Eigentümers. Die Antwort enthält slug des Modells im Zielprojekt, renamed: true, wenn dieser Slug dort bereits vergeben ist, und 409, solange das Modell noch trainiert wird.

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

Benutzerdefinierte metadata-Felder sind von trainingsverwalteten Feldern wie trainArgs, environment und trainResults getrennt und unterliegen denselben Größenbeschränkungen wie Dataset-Metadaten.

Modell löschen#

DELETE /api/models/{owner}/{project}/{model}

Python SDK: client.models.delete(owner, project, model)

Verschiebt das Modell für 30 Tage in den Papierkorb und löscht endgültig jedes Deployment, das es verwendet, einschließlich ausstehender Ersetzungen. Beim Wiederherstellen des Modells werden die Deployments nicht wiederhergestellt.

Modelldateien herunterladen#

GET /api/models/{owner}/{project}/{model}/files

Python SDK: client.models.files(owner, project, model)

Gibt kurzzeitig gültige signierte URLs für die Modellgewichte zurück.

{
    "files": [
        {
            "name": "best.pt",
            "size": 6534127,
            "downloadUrl": "https://storage.googleapis.com/...&signature=..."
        }
    ]
}

Bilder finden, die den schlechtesten Validierungsbildern ähneln#

GET /api/models/{owner}/{project}/{model}/similar-images

Python SDK: client.models.find_similar_training_images(owner, project, model)

Gibt bis zu 100 images zurück, im selben Format wie Ähnliche Bilder finden. Die Bilder ähneln den Validierungsbildern, bei denen dieser Trainingslauf die schlechtesten Ergebnisse erzielt hat. Bilder, die bereits im Trainingsdatensatz enthalten sind, werden ausgeschlossen. Übergib hashes (kommagetrennt, bis zu 100), um eine Teilmenge dieser schlechtesten Bilder als Suchgrundlage zu verwenden. Erfordert einen API-Schlüssel mit Zugriff auf den Workspace des Modells. Die Liste ist leer, wenn für den Lauf keine Ergebnisse pro Bild gespeichert wurden. 404 bedeutet außerdem, dass die schlechtesten Bilder noch nicht eingebettet wurden: Führe zuerst Dataset-Einbettungen für den Trainingsdatensatz aus.

Modell klonen#

POST /api/models/{owner}/{project}/{model}/clone

Python SDK: client.models.clone(owner, project, model, project_body=...)

Kopiert ein zugängliches Modell in ein vorhandenes Projekt.

{
    "owner": "acme-vision",
    "project": "inspection",
    "model": "v3-copy",
    "name": "V3 Copy",
    "description": "Cloned from a public model"
}

Inferenz ausführen#

POST /api/models/{owner}/{project}/{model}/predict

Python SDK: client.models.predict(owner, project, model, body=...)

Öffentliche Modelle können ohne Authentifizierung für Vorhersagen verwendet werden. Für private und freigegebene Modelle ist ein API-Schlüssel mit Zugriff auf das übergeordnete Projekt erforderlich.

Multipart-Formular:

Gib entweder file oder source an. Tiefenmodelle akzeptieren außerdem bits (8, 12 oder 16), um die PNG- Quantisierung der Tiefenkarte auszuwählen. Anfragen, die die Eingabegrenzwerte des Dienstes überschreiten, geben 413 zurück.

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.jpg" \
  -F "conf=0.5" \
  https://platform.ultralytics.com/api/models/acme-vision/inspection/v3/predict

Antwort:

Jeder Eintrag in images enthält shape, speed, results und bei Aufgaben mit dichter Vorhersage eine PNG-Nutzlast in semantic_mask oder depth (Tiefenwerte sind pixel × max / divisor; der Divisor beträgt 255 für die standardmäßige 8-Bit-Karte und 65535, wenn bits den Wert 12 oder 16 hat). Das Objekt metadata enthält die Anzahl der Bilder, die Klassennamen des Modells, Funktionslaufzeiten, die Aufgabe und die Versionen des Dienstes. Interne Modellpfade werden niemals zurückgegeben.

{
    "images": [
        {
            "shape": [1080, 1920],
            "speed": { "preprocess": 2.1, "inference": 12.4, "postprocess": 1.3 },
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1,
        "classNames": ["person", "forklift"],
        "functionTimeAlive": 184.2,
        "functionTimeCall": 0.31,
        "task": "detect",
        "version": { "ultralytics": "8.4.120" }
    }
}

Trainingsfortschritt prüfen#

GET /api/models/{owner}/{project}/{model}/training

Python SDK: client.models.training(owner, project, model)

Gibt job mit Status, Epochenfortschritt, Zeitangaben, Rechenressourcendetails, Trainingsargumenten, Epochenmetriken und sicheren Fehlerdetails zurück oder null, wenn das Modell noch nie trainiert wurde. Modelle in öffentlichen Projekten können ohne Authentifizierung ausgelesen werden.

Training abbrechen#

DELETE /api/models/{owner}/{project}/{model}/training

Python SDK: client.models.delete_training(owner, project, model)

Beendet die laufende Recheninstanz und kennzeichnet den Auftrag als abgebrochen. Gibt 409 zurück, wenn das Training nicht mehr läuft.

Trainings-API#

Starte das YOLO-Training auf Cloud-GPUs und überwache den Fortschritt in Echtzeit. Weitere Informationen findest du in der Dokumentation zum Cloud-Training.

GPU-Verfügbarkeit abrufen#

GET /api/training/gpu-availability

Python SDK: client.training.gpu_availability()

Gibt den aktuellen Verfügbarkeitsstatus nach GPU-ID zurück. Öffentlich und ohne Authentifizierung verfügbar. Übergib managed=true, um verwaltete Trainingskapazitäten einzubeziehen; dafür ist ein API-Schlüssel erforderlich.

Training starten#

POST /api/training/start

Python SDK: client.training.start(model_id=..., train_args=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "65f1c0a2b3d4e5f601234599",
    "gpuType": "rtx-4090",
    "trainArgs": {
      "model": "yolo26n.pt",
      "data": "ul://acme-vision/datasets/warehouse",
      "epochs": 100,
      "imgsz": 640,
      "batch": 16
    }
  }' \
  https://platform.ultralytics.com/api/training/start

Antwort:

{
    "modelId": "65f1c0a2b3d4e5f601234599",
    "status": "starting",
    "gpuType": "rtx-4090",
    "estimatedCost": { "pricePerHour": 0.69, "gpuMemoryGb": 24 },
    "billing": {
        "estimatedCostCents": 138,
        "estimatedCostDisplay": "$1.38",
        "balanceCents": 2500
    }
}

Das Training gibt 402 zurück, wenn dein Guthaben zu niedrig ist, und 503, wenn für die angeforderte GPU keine Kapazität verfügbar ist.

Exports-API#

Konvertiere Modelle in optimierte Formate wie ONNX, TensorRT, CoreML und LiteRT für den Einsatz auf Edge-Geräten. Weitere Informationen findest du in der Dokumentation zur Bereitstellung.

Exporte auflisten#

GET /api/models/{owner}/{project}/{model}/exports

Python SDK: client.exports.list(owner, project, model)

Abfrageparameter:

Export erstellen#

POST /api/models/{owner}/{project}/{model}/exports

Python SDK: client.exports.create(owner, project, model, format=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "onnx", "args": {"imgsz": 640, "quantize": 16}}' \
  https://platform.ultralytics.com/api/models/acme-vision/inspection/v3/exports

Jedes Format berücksichtigt nur die Optionen in der Spalte Argumente der nachstehenden Exporttabelle: Ein Wert ungleich dem Standard für batch, dynamic, opset, simplify, workspace oder optimize, den ein Format nicht unterstützt, gibt 400 zurück. imx-Exporte sind ausschließlich mit INT8 verfügbar und werden für Detektions-, Segmentierungs-, Klassifizierungs- und Posemodelle unterstützt; YOLO26-Modelle und YOLOv8- oder YOLO11-Größen außer nano geben 400 zurück.

Antwort (201): id, format, status (queued oder running), region und bei TensorRT-Exporten gpuType. Ein gleichwertiger Export, der bereits läuft, gibt 409 zurück.

Unterstützte Formate:

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

nms=None gibt standardmäßig Rohdaten für die externe NMS aus. Lege nms=False fest, um einen verfügbaren Kopf ohne NMS auszuwählen; nicht unterstützte Formate greifen auf ihren nativen Ausgabepfad zurück. Die obigen Einträge nms kennzeichnen Formate, die NMS mit nms=True integrieren können.

Exportstatus abrufen#

GET /api/models/{owner}/{project}/{model}/exports/{exportId}

Python SDK: client.exports.retrieve(owner, project, model, export_id)

Gibt das Objekt export mit status, format, args, gpuType (nur TensorRT), Zeitstempeln und — nach Abschluss — einem Objekt file mit size, downloadUrl und downloadFilename zurück.

Export abbrechen oder löschen#

DELETE /api/models/{owner}/{project}/{model}/exports/{exportId}

Python SDK: client.exports.delete(owner, project, model, export_id)

Bricht einen laufenden Export ab oder löscht einen abgeschlossenen Export samt Datei. Die Antwort gibt an, was geschehen ist:

{
    "success": true,
    "action": "cancelled"
}

Deployments-API#

Stelle Modelle auf dedizierten Inferenzendpunkten mit Zustandsprüfungen und Überwachung bereit. Weitere Informationen findest du in der Dokumentation zu Endpunkten.

Deployments auflisten#

GET /api/deployments/{owner}

Python SDK: client.deployments.list(owner)

Abfrageparameter:

Anonyme Aufrufer müssen nach einem öffentlichen Modell filtern; zum Auflisten eines gesamten Workspaces ist eine Authentifizierung erforderlich.

Deployment erstellen#

POST /api/deployments/{owner}

Python SDK: client.deployments.create(owner, project=..., model=..., deployment=..., name=..., region=...)

Body:

{
    "project": "inspection",
    "model": "v3",
    "deployment": "edge-1",
    "name": "Edge 1",
    "region": "us-central1"
}

Antwort (201): id, deployment, status (creating), message und region.

Deployment abrufen#

GET /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.retrieve(owner, deployment)

Gibt das Objekt deployment mit status, statusMessage, region, serviceUrl, resources und dem benutzerdefinierten metadata zurück. Für den Inhaber werden außerdem camera und cameraApplying zurückgegeben.

Deployment aktualisieren#

PATCH /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.update(owner, deployment, body=...)

Sende einen dieser Bodys:

{ "name": "Edge 1 (primary)" }

Beim Umbenennen wird der Wert deployment in der URL durch einen aus dem neuen Namen gebildeten Slug ersetzt, der als deployment zurückgegeben wird. Der alte Pfad gibt 404 zurück, und serviceUrl bleibt unverändert. Ein leeres Objekt metadata löscht benutzerdefinierte Metadaten. Beim Ersetzen wird eine neue Revision bereitgestellt, während Bereitstellungs-ID, Region und Endpunkt-URL erhalten bleiben. Schlägt die Bereitstellung fehl, bleibt die vorhandene Revision aktiv. Das Ersatzmodell muss vollständig trainiert sein und Gewichte haben, auf die dein Schlüssel zugreifen kann. Mit der Kameraaktion wird eine RTSP- oder RTSPS-Kamera gespeichert, auf der ein bereiter Endpunkt mit benutzerdefinierten Ressourcen weiterhin Inferenz ausführt (siehe Hintergrundkamera). "url": null entfernt die Kamera ebenso wie das Zurücksetzen der Endpunktgröße auf die Standardgröße. Wird eine Kamera auf einem Endpunkt in Standardgröße gespeichert, wird 403 zurückgegeben. Während eine Kameraänderung angewendet wird, gibt sie 202 mit status ready zurück. Rufe die Bereitstellung wiederholt ab, bis cameraApplying nicht mehr true ist, und prüfe dann camera. Bei einer fehlgeschlagenen Änderung bleibt die vorherige Kamera erhalten und statusMessage wird gesetzt. Abgeschlossene Vorgänge geben 200 mit status ready oder stopped zurück. Bei anderen Vorgängen, deren Bereitstellung noch läuft, werden 202 mit deploying oder stopping zurückgegeben.

Deployment löschen#

DELETE /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.delete(owner, deployment)

Entfernt den Inferenzendpunkt dauerhaft.

Zustandsprüfung#

GET /api/deployments/{owner}/{deployment}/health

Python SDK: client.deployments.health(owner, deployment)

Sendet eine Ping-Anfrage an den Endpunkt und wärmt ihn auf; zurückgegeben werden healthy, latencyMs und der Upstream-status-Code.

Inferenz für ein Deployment ausführen#

POST /api/deployments/{owner}/{deployment}/predict

Python SDK: client.deployments.predict(owner, deployment, body=...)

Leitet ein Bild oder Video über den dedizierten Endpunkt. Die Verträge für Anfrage und Antwort entsprechen denen der Modellinferenz. Kamerastreams werden nicht weitergeleitet. Sende sie wie unter Live-Kamerainferenz beschrieben an die Endpunkt-URL.

Multipart-Formular:

Metriken abrufen#

GET /api/deployments/{owner}/{deployment}/metrics

Python SDK: client.deployments.metrics(owner, deployment)

Abfrageparameter:

Die vollständige Antwort enthält summary (Anzahl der Anfragen insgesamt, Fehlerrate, durchschnittliche Latenz sowie p50/p95/p99-Latenz) und timeSeries (Anfragen, Fehler, Latenz, CPU, Arbeitsspeicher, Anzahl der Instanzen). Die Sparkline-Antwort gibt requests24h (stündliche Anzahl der Anfragen; Stunden ohne Anfragen werden ausgelassen), totalRequests, errorRate und avgLatencyMs zurück (den Durchschnitt der stündlichen P95-Latenzen). Mit view=overview enthält summary totalRequests, errorRate und p95LatencyMs, und timeSeries enthält requests, errors und latencyP95.

Protokolle abrufen#

GET /api/deployments/{owner}/{deployment}/logs

Python SDK: client.deployments.logs(owner, deployment)

Abfrageparameter:

Agents-API#

Speichere und verwalte Agents-Workflows. Die API speichert Agentendefinitionen; Ausführungen werden auf der Agents-Arbeitsfläche gestartet, wo https://platform.ultralytics.com/agents?workflow={id} einen gespeicherten Agent öffnet. Für die Python-SDK-Methoden ist ultralytics-platform>=0.1.74 erforderlich.

Jeder Vorgang akzeptiert optional den Abfrageparameter owner mit dem Benutzernamen eines Arbeitsbereichs, dem du angehörst (Standard: dein eigener). Zum Auflisten ist Betrachterzugriff erforderlich; zum Speichern und Löschen ist Bearbeiterzugriff erforderlich.

Agents auflisten#

GET /api/workflows

Python SDK: client.agents.list()

Die Antwort listet bis zu 100 Agents unter workflows auf, sortiert nach dem Zeitpunkt der letzten Aktualisierung, und enthält für jeden id, username, name, version, createdAt und updatedAt. Wenn du ein id anforderst, wird außerdem graph des Agents zurückgegeben.

Agent speichern#

PUT /api/workflows

Python SDK: client.agents.save(name=..., graph=..., version=...)

Sende version: 0, um einen Agent zu erstellen. Um einen Agent zu aktualisieren, sende dessen id und das version, das bei deiner letzten Auflistung oder Speicherung zurückgegeben wurde; ein veraltetes version gibt 409 zurück. Liste den Agent daher erneut auf und versuche es noch einmal. Ein Graph, dessen Verbindungen einen Zyklus bilden oder einem Block mehr als eine Eingabe zuweisen, gibt 400 zurück.

from ultralytics_platform import Platform

def block(node_id, kind, x, config):
    return {
        "id": node_id,
        "type": "agent",
        "position": {"x": x, "y": 0},
        "data": {"label": kind, "type": kind, "config": config},
    }

graph = {
    "nodes": [
        block("images", "Dataset", 0, {"dataset": "official:coco8", "split": "val", "maxInputs": 2}),
        block("yolo", "YOLO", 220, {"model": "ul://ultralytics/yolo26/yolo26n", "task": "detect"}),
        block("output", "Output", 440, {}),
    ],
    "edges": [{"id": "e1", "source": "images", "target": "yolo"}, {"id": "e2", "source": "yolo", "target": "output"}],
    "templateId": "",
}

with Platform() as client:
    saved = client.agents.save(name="Detect COCO8", graph=graph, version=0)
    print(saved["id"], saved["version"], saved["errors"])

Die Antwort enthält den Agent id, sein neues version und errors: Blöcke, die auf der Arbeitsfläche markiert würden, etwa ein Dataset-Block, für den kein Dataset ausgewählt ist. Der Agent wird in jedem Fall gespeichert. Unter openapi.json findest du alle Blocktypen und ihre Konfiguration.

Agent löschen#

DELETE /api/workflows?id={id}

Python SDK: client.agents.delete(id=...)

Löscht den Agent und bricht seine aktiven Ausführungen ab. Gelöschte Agents erscheinen nicht im Papierkorb und können nicht wiederhergestellt werden.

Papierkorb-API#

Zeige, stelle wieder her und lösche endgültig soft-gelöschte Projekte, Datasets und Modelle. Elemente werden nach 30 Tagen automatisch endgültig gelöscht. Siehe Dokumentation zum Papierkorb.

Papierkorb auflisten#

GET /api/trash

Python SDK: client.lifecycle.trash()

Abfrageparameter:

Die Antwort enthält items (jeweils mit daysRemaining), total, page, limit, totalPages und ein summary mit Gesamtzahlen nach Typ. Mit id werden stattdessen resources zurückgegeben: die betroffenen Modelle und Deployments, die endgültig gelöscht würden.

Element wiederherstellen#

POST /api/trash

Python SDK: client.lifecycle.restore(id=..., type=...)

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

Beim Wiederherstellen eines Projekts werden auch die Modelle wiederhergestellt, die zusammen mit dem Projekt in den Papierkorb verschoben wurden; sie werden unter restoredModels aufgeführt.

Endgültig löschen#

DELETE /api/trash

Python SDK: client.lifecycle.delete_trash(body=...)

Ein Element löschen:

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

Oder den gesamten Papierkorb leeren:

{
    "all": true
}

Die Antwort enthält deletedCount sowie gegebenenfalls cascadedModels und survivingDeployments.

Upload-API#

Lade Dateien mithilfe signierter URLs direkt in den Cloud-Speicher hoch. Wenn du den Upload eines Modells abschließt, werden dessen Gewichte angehängt; beim Abschließen des Uploads eines Dataset-Archivs wird dieses überprüft. Anschließend übergibst du die Sitzung an Dataset-Ingest, wodurch auch der Upload selbst abgeschlossen wird, falls du diesen Schritt überspringst. Siehe Datendokumentation.

Signierte Upload-URL abrufen#

POST /api/upload/signed-url

Python SDK: client.upload.signed_url(body=...)

Body:

{
    "assetType": "datasets",
    "assetId": "65f1c0a2b3d4e5f601234567",
    "filename": "warehouse.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

Antwort:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.googleapis.com/...&signature=...",
    "expiresAt": "2026-02-22T12:00:00Z",
    "headers": { "x-goog-if-generation-match": "0" }
}

Lade die Datei mit einer PUT-Anfrage an uploadUrl hoch. Verwende dabei denselben Content-Type, den du angegeben hast, sowie alle Header, die unter headers zurückgegeben wurden. Dataset-Upload-URLs sind 12 Stunden gültig und erlauben nur das erstmalige Erstellen: Eine zweite PUT-Anfrage an dieselbe URL gibt 412 zurück, und eine PUT-Anfrage ohne die zurückgegebenen Header gibt 400 zurück.

Upload abschließen#

POST /api/upload/complete

Python SDK: client.upload.complete(session_id=...)

{
    "sessionId": "session_abc123",
    "md5": "<optional md5 hex>"
}

Antwort: success und ein file-Objekt mit size und contentType. Bei Modellen werden dadurch die Gewichte angehängt; bei Dataset-Archiven rufst du als Nächstes Ingest auf, um die Verarbeitung zu starten.

Wenn md5 angegeben ist, wird der Wert mit dem gespeicherten Objekt abgeglichen. Bei einer Abweichung wird 400 zurückgegeben; bei einer noch nicht abgeschlossenen Sitzung wird außerdem die hochgeladene Datei gelöscht und die Sitzung bleibt unvollständig. Fordere daher eine neue signierte URL an und lade die Datei erneut hoch. Eine abgeschlossene Dataset-Sitzung kann erneut abgeschlossen werden, solange das Archiv vorhanden ist. Werden jedoch gleichzeitig Abschlüsse mit unterschiedlichen Prüfsummen angefordert, wird 409 zurückgegeben; Modellsitzungen werden beim Abschließen entfernt. checksum wird als Metadatum der Modelldatei gespeichert und nicht überprüft.

API für Speicherintegrationen#

Verbinde schreibgeschützte Konten für Google Cloud Storage, Amazon S3 oder Azure Blob Storage und durchsuche sie als Dataset-Quellen. Siehe Dokumentation zu Integrationen.

Zum Ermitteln und Verbinden von Speicherorten sind Administratorzugriff auf den Arbeitsbereich und ein Pro- oder Enterprise-Tarif erforderlich (andernfalls 403); zum Auflisten von Integrationen und Durchsuchen von Objekten ist Bearbeiterzugriff erforderlich.

Integrationen auflisten#

GET /api/integrations/buckets

Python SDK: client.storage_integrations.list()

Gibt integrations zurück, jeweils mit id, provider, credentialIdentity, targets und createdAt. Zugangsdaten werden niemals zurückgegeben.

Speicherorte ermitteln#

POST /api/integrations/buckets/discover

Python SDK: client.storage_integrations.discover(body=...)

Listet die Buckets oder Container auf, auf die mit den angegebenen Zugangsdaten zugegriffen werden kann, ohne diese zu speichern.

{
    "provider": "gcs",
    "credentials": {
        "client_email": "svc@project.iam.gserviceaccount.com",
        "private_key": "-----BEGIN PRIVATE KEY-----\n...",
        "project_id": "my-project"
    }
}

Antwort: {"targets": ["my-bucket", "another-bucket"]}

Speicher verbinden#

POST /api/integrations/buckets

Python SDK: client.storage_integrations.create(body=...)

Dieselben Zugangsdatenformate wie beim Ermitteln, zusätzlich mit dem erforderlichen Array targets mit 1 bis 50 Bucket- oder Containernamen. Gibt 201 mit der gespeicherten Integration zurück. Temporäre S3-Zugangsdaten (ASIA-Zugriffsschlüssel) werden abgelehnt.

Objekte durchsuchen#

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

Python SDK: client.storage_integrations.objects(id, target=...)

Abfrageparameter:

Gibt entries zurück (jedes kind ist folder oder file) sowie optional ein cursor für die nächste Seite.

Speicherverbindung trennen#

DELETE /api/integrations/buckets/{id}

Python SDK: client.storage_integrations.delete(id)

Entfernt die gespeicherten Zugangsdaten, ohne Daten beim Anbieter zu löschen. Verbundene Datasets bleiben sichtbar, ihre Dateien sind jedoch nicht verfügbar, bis dasselbe Speicherkonto erneut verbunden wird. Erfordert Administratorzugriff auf den Arbeitsbereich.

API für Dataset-Importe#

Importiere Datasets aus Diensten von Drittanbietern. Siehe Roboflow-Integration.

Roboflow-Import in der Vorschau anzeigen#

POST /api/integrations/roboflow/preview

Python SDK: client.datasets.preview_roboflow(api_key=...)

Löst einen Roboflow-API-Schlüssel in einen Importplan auf: Arbeitsbereichsdetails, newDatasets, die importiert würden, Anzahl der bereits importierten (skippedCount), versionslosen, nicht unterstützten und nicht aufgelösten Projekte, bytesTotal sowie dein verbleibender Speicherplatz storage. Der Roboflow-API-Schlüssel wird aus dem Anforderungstext gelesen und nicht gespeichert.

{
    "apiKey": "ROBOFLOW_API_KEY"
}

Aus Roboflow importieren#

POST /api/integrations/roboflow/import

Python SDK: client.datasets.import_roboflow(api_key=..., items=...)

Stellt Ingest-Aufträge für bis zu 500 ausgewählte Roboflow-Projektversionen in die Warteschlange und verwendet dabei die von der Vorschau zurückgegebenen Elemente.

{
    "apiKey": "ROBOFLOW_API_KEY",
    "items": [
        {
            "workspace": "my-workspace",
            "projectId": "warehouse-safety",
            "projectName": "Warehouse Safety",
            "projectType": "object-detection",
            "latestVersion": 4
        }
    ]
}

Antwort (201): Arrays imported, failed und skipped. Für Importe ist ausreichend Speicherplatz erforderlich, und jedes Dataset muss innerhalb der für deinen Tarif geltenden Größenbeschränkung pro Import liegen.

Konto-API#

Sieh dir dein Platform-Konto, deine Schlüssel, deinen Speicher und deine öffentlichen Profile an. Siehe Dokumentation zu den Einstellungen.

Kontoübersicht#

GET /api/account/summary

Python SDK: client.account.summary()

Gibt den Tarif, das Guthaben und die Ressourcenanzahl für den Arbeitsbereich zurück, für den der Schlüssel ausgestellt wurde.

{
    "username": "acme-vision",
    "name": "Acme Vision",
    "accountType": "team",
    "plan": "pro",
    "creditsCents": 2500,
    "counts": { "projects": 4, "datasets": 7, "models": 21 },
    "teams": []
}

API-Schlüssel auflisten#

GET /api/api-keys

Python SDK: client.account.api_keys()

Gibt keys mit keyId, name, keyPrefix und createdAt für den Arbeitsbereich des Schlüssels zurück. Bei Anfragen mit API-Schlüsselauthentifizierung werden nur Metadaten zurückgegeben; die vollständigen Schlüsselwerte sind für den Arbeitsbereichseigentümer unter Einstellungen > API-Schlüssel in der Platform-Benutzeroberfläche sichtbar. Dort werden Schlüssel auch erstellt und widerrufen.

Speichernutzung prüfen#

GET /api/storage

Python SDK: client.account.storage()

Abfrageparameter:

Antwort:

{
    "tier": "pro",
    "usage": {
        "storage": { "current": 1073741824, "limit": 536870912000, "percent": 0 },
        "datasets": { "current": 2, "limit": -1, "percent": 0 },
        "models": { "current": 4, "limit": 500, "percent": 1 }
    },
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "65f1c0a2b3d4e5f601234567",
                "name": "Warehouse",
                "slug": "warehouse",
                "sizeBytes": 536870912,
                "type": "dataset"
            }
        ]
    },
    "region": "us",
    "username": "acme-vision",
    "updatedAt": "2026-01-15T10:00:00Z"
}

usage gibt die Anzahl für projects, datasets, models, images, annotations und deployments sowie die Byteanzahl für storage zurück. Ein limit mit dem Wert -1 bedeutet unbegrenzt; percent ist der ganzzahlige Prozentsatz des Limits.

Öffentliches Benutzerprofil abrufen#

GET /api/users

Python SDK: client.account.profile(username=...)

Abfrageparameter:

Gibt das öffentliche Profil user mit followerCount und bei authentifizierten Aufrufern mit isFollowed zurück.

Benutzer folgen oder nicht mehr folgen#

PATCH /api/users

Python SDK: client.account.follow(username=..., followed=...)

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

Antwort: followed und das aktualisierte followerCount.

Abrechnungs-API#

Prüfe deine Tarifnutzung und dein Guthabenkonto. Weitere Informationen findest du in der Abrechnungsdokumentation.

Tarif und Nutzung anzeigen#

GET /api/billing/usage-summary

Python SDK: client.billing.usage_summary()

Gibt plan (ID, Status, Abrechnungszeitraum, Ende des Zeitraums), metrics (Speicherlimit und -nutzung), trainingCredit, features, creditsCents und die Anzahl der Plätze zurück.

Transaktionen anzeigen#

GET /api/billing/transactions

Python SDK: client.billing.transactions()

Abfrageparameter:

Jede Transaktion enthält id, type (z. B. purchase, training, monthly_grant oder refund), amountCents, balanceAfter, createdAt, ein optionales receiptUrl sowie Modellkontext für Trainingsgebühren. Interne Abrechnungsdetails werden niemals zurückgegeben.

Explore-API#

Durchsuche öffentliche, von der Community geteilte Projekte und Datensätze oder suche nach Bildern anhand ihres Inhalts. Weitere Informationen findest du in der Dokumentation zu „Entdecken“.

Öffentliche Inhalte durchsuchen#

GET /api/explore/search

Python SDK: client.explore.search()

Abfrageparameter:

Antwort: projects, datasets und hasMore. type=images gibt seine Übereinstimmungen stattdessen in images zurück, beginnend mit der besten Übereinstimmung. Jede enthält die zugehörige Quelle dataset und einen Ähnlichkeitswert zwischen 0 und 1 score. Dafür ist q erforderlich. Durchsucht werden öffentliche Datensätze sowie deine eigenen Datensätze und Teamdatensätze, wenn du einen API-Schlüssel mitsendest.

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

Python-SDK#

ultralytics-platform ist ein typisierter Python-Client, der aus dem OpenAPI-Vertrag generiert wurde und für jeden Endpunkt eine Methode bereitstellt (client.datasets.list, client.models.predict, client.exports.create, ...). Jede Methode nimmt Pfadparameter als Positionsargumente und andere Eingaben als Schlüsselwortargumente entgegen, außerdem optionale request-spezifische timeout und extra_headers.

pip install "ultralytics-platform>=0.1.45" # Python 3.11+

from ultralytics_platform import Platform

with Platform() as client:  # liest ULTRALYTICS_API_KEY oder den mit yolo login gespeicherten Schlüssel
    dataset = client.datasets.retrieve("acme-vision", "warehouse")
    images = client.datasets.images("acme-vision", "warehouse", limit=10)
    export = client.exports.create("acme-vision", "inspection", "v3", format="onnx")

AsyncPlatform stellt denselben Ressourcenbaum für async/await-Code bereit. Nicht erfolgreiche Antworten lösen APIError mit status_code, body und geparstem json aus; bei Verbindungsfehlern wird APIConnectionError ausgelöst. Das vollständige README findest du im SDK-Repository.

Python-Integration#

Verwende für Trainings- und Inferenzabläufe das Ultralytics-Python-Paket. Es übernimmt Authentifizierung, Uploads und das Streaming von Metriken in Echtzeit automatisch. Ab Python 3.11 installiert pip install ultralytics auch das ultralytics-platform-SDK. Wenn model.train(project=...) auf Platform verweist, streamen die Trainings-Callbacks Ereignisse über client.training.metrics() des SDK und fordern URLs zum Hochladen von Checkpoints über client.models.upload_checkpoint() an, also die Vorgänge POST /api/webhooks/training/metrics und POST /api/webhooks/models/upload im OpenAPI-Dokument. Du musst also nichts selbst aufrufen.

Installation und Einrichtung#

Die Platform-Integration erfordert Python>=3.11 und ultralytics>=8.4.120:

pip install "ultralytics>=8.4.120"

Installation überprüfen:

yolo check

Authentifizierung#

yolo login YOUR_API_KEY

Datensätze auf der Plattform verwenden#

Verweise auf Datensätze mit ul://-URIs:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Auf deinem Platform-Datensatz trainieren
model.train(
    data="ul://your-username/datasets/your-dataset",
    epochs=100,
    imgsz=640,
)

URI-Format:

An Platform übermitteln#

Ergebnisse an ein Platform-Projekt senden:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Ergebnisse werden automatisch mit Platform synchronisiert
model.train(
    data="coco8.yaml",
    epochs=100,
    project="your-username/my-project",
    name="experiment-1",
)

Synchronisierte Daten:

• Trainingsmetriken (in Echtzeit)
• Gewichte des fertigen Modells
• Validierungsdiagramme
• Konsolenausgabe
• Systemmetriken
• Trainingsargumente und Hostumgebung (Hostname, Betriebssystem, Python, Hardware, Git-Commit, Befehlszeile)

API-Beispiele#

Ein Modell von Platform laden:

# Dein eigenes Modell
model = YOLO("ul://username/project/model-name")

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

Inferenz ausführen:

results = model("image.jpg")

# Auf Ergebnisse zugreifen
for r in results:
    boxes = r.boxes  # Erkennungsrahmen
    masks = r.masks  # Segmentierungsmasken
    keypoints = r.keypoints  # Posenschlüsselpunkte
    probs = r.probs  # Klassifizierungswahrscheinlichkeiten

Modell exportieren:

# Nach ONNX exportieren
model.export(format="onnx", imgsz=640, quantize=16)

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

# In CoreML exportieren
model.export(format="coreml", imgsz=640)  # für die Klassifizierung imgsz=224 verwenden

Validierung:

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

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

Häufig gestellte Fragen#