REST-API-Referenz#

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

# 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 um die zentralen Ressourcen der Platform organisiert:

graph LR
    A[API Key]:::start --> B[Datasets]:::proc
    A --> C[Projects]:::proc
    B -->|images| G[Images]:::proc
    C -->|contains| D[Models]:::proc
    B -->|train on| D
    D -->|deploy| E[Deployments]:::proc
    D -->|export| F[Exports]:::proc

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

Authentifizierung#

Die meisten Endpunkte erfordern einen API-Schlüssel. 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 ebenfalls anonyme Anfragen und liefern bei Angabe eines Schlüssels einfach mehr Ergebnisse zurück.

API-Schlüssel abrufen#

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

Ausführliche Anweisungen findest du unter API-Schlüssel.

Autorisierungs-Header#

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

Authorization: Bearer YOUR_API_KEY

Beispiel#

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

Basis-URL#

Alle API-Endpunkte verwenden:

https://platform.ultralytics.com/api

Ressourcenpfade#

Ressourcen werden anhand derselben lesbaren Namen angesprochen, die in den Platform-URLs erscheinen, nicht anhand von Datenbank-IDs:

• {owner} ist ein persönlicher Benutzername oder die Kennung eines Teamarbeitsbereichs: 4–32 Zeichen, kleingeschrieben, alphanumerisch und mit einzelnen Bindestrichen zwischen den Segmenten.
• {dataset}, {project}, {model} und {deployment} folgen demselben Muster aus Kleinbuchstaben und Bindestrichen und können bis zu 128 Zeichen lang sein.
• {imageId} und {exportId} sind 24 Zeichen lange hexadezimale IDs, die von der API zurückgegeben werden.
• Wenn du eine Ressource über PATCH umbenennst, werden der Anzeigename name und der URL-Name gemeinsam geändert. Die Antwort enthält den aktuellen URL-Namen, damit du ihm weiterhin folgen kannst.

Ratenlimits#

Die API setzt für jeden API-Schlüssel Limits in gleitenden Zeitfenstern durch. Jede Route gehört zu einer Kategorie, und jede Kategorie hat einen unabhängigen Zähler. 20 Vorhersageanfragen verbrauchen daher nicht dein Standardkontingent.

Routen der Platform, die nur im Browser verwendet werden, etwa der Bezahlvorgang 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",
    "retryAfter": 12,
    "resetAt": "2026-02-21T12:34:56.000Z"
}

Dedizierte Endpunkte (unbegrenzt)#

Für dedizierte Endpunkte gelten keine Ratenlimits der Platform-API-Schlüssel, wenn du den eigenen serviceUrl-Endpunkt der Bereitstellung 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 keine allgemeine Hülle: Listenendpunkte geben eine benannte Sammlung zusammen mit Zählwerten zurück, und Änderungsoperationen geben die geänderten IDs zurück.

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

Antworten mit Daten enthalten außerdem region (us, eu oder ap), die Speicherregion für diesen Arbeitsbereich.

Fehlerantworten#

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

{
    "error": "Dataset not found"
}

Seitennavigation#

Der Seitenumbruch 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 diesen Arbeitsbereich anzeigen darf.

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 Schlüssel dataset zurück, einschließlich classNames, splits, versions, source und des benutzerdefinierten Objekts metadata.

Datensatz erstellen#

POST /api/datasets

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

Textkörper:

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

Die Antwort gibt den tatsächlich erstellten dataset-Slug zurück, lies diesen also vor dem Hochladen aus, es sei denn, du setzt requireExactSlug.

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)

Textkörper (partielle Aktualisierung):

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

Akzeptierte Felder: name, description, visibility, metadata, tags, classNames, classColors, format, task, license, iconColor, iconLetter und starred. Sende ein leeres metadata-Objekt ({}), um benutzerdefinierte Metadaten zu löschen. Metadatenschlüssel sind auf 128 Zeichen und das serialisierte Objekt auf 500.000 Zeichen begrenzt.

Antwort:

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

Durch die Umbenennung ändert sich der URL-Name. Verwende daher für nachfolgende Anfragen 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 einschließlich seiner Bilder und Labels in deinen persönlichen Arbeitsbereich oder einen Teamarbeitsbereich.

Optionaler Textkörper (alle Felder sind 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 eine verbundene Speicherquelle zugreifen, 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. Lass v weg, um den aktuellen Stand des Datensatzes zu exportieren und den zwischengespeicherten Export wiederzuverwenden, wenn sich seit seiner Erstellung nichts geändert hat.

Abfrageparameter:

Antwort:

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

Beim Anfordern einer bestimmten Version werden downloadUrl und version anstelle von cached zurückgegeben.

Datensatzversion erstellen#

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

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

Erstellt einen unveränderlichen nummerierten Snapshot des Datensatzes und speichert dessen NDJSON-Export. Editorzugriff ist erforderlich.

Textkörper (optional):

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

Antwort:

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

reused ist true, wenn der Datensatz seit der vorherigen Version unverändert ist und stattdessen dieser Snapshot zurückgegeben wurde.

Versionsbeschreibung aktualisieren#

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

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

Textkörper:

{
    "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=...)

Erstellt Bilder, Annotationen und Klassen aus einer gespeicherten Version neu, ohne Bilddaten zu kopieren.

Textkörper:

{
    "version": 2
}

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

Datensatzstatistiken abrufen#

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

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

Gibt klassenweise Annotationszahlen, Histogramme von Bildern und Annotationen sowie Heatmaps zurück. Große Datensätze werden stichprobenartig verarbeitet; in diesem Fall gibt sampleSize an, wie viele Bilder beigetragen haben.

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 verbleibenden Klassen nach unten verschoben):

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 Werte classNames und classColors sowie eine Zusammenfassung der Änderungen zurück (mergedClassIds und targetClassId oder deletedClassIds und deletedAnnotations).

Aufteilungen neu verteilen#

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

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

Weist Bilder zufällig auf die Aufteilungen neu zu. Die drei Prozentsätze müssen zusammen 100 ergeben.

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

Antwort: success, die resultierenden Anzahlen 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 Zusammenfassung der Analyse 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 die UMAP-2D-Anordnung einer abgeschlossenen Analyse zurück, mit Seitenumbruch über offset und limit (Standard und Maximum: 50.000). Jeder Eintrag enthält id, umapX, umapY, split, classIds, width, height, bytes, labelCount und missing.

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.jpg",
            "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 bereitgestellte Bild-IDs dieselbe Bildstruktur zurück und akzeptiert dieselben Filter- und URL-Abfrageparameter wie die Listenoperation.

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

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 zu einem vorhandenen Datensatz. Gib genau eine Quelle an:

Upload-Sitzungen werden durch die an POST /api/upload/signed-url übergebene assetId an einen Datensatz gebunden, und der Import lehnt eine Sitzung ab, die zu einem anderen Datensatz gehört.

Body (hochgeladenes Archiv):

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

Body (entferntes Archiv oder NDJSON):

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

Body (Import von Labels bei einem späteren Import):

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

Body (Anhängen bildbezogener Metadaten):

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

Metadatenschlüssel müssen mit dem normalisierten Pfad innerhalb des Archivs einschließlich der Ordner übereinstimmen. Bei NDJSON-Importen kann jeder Datensatz ein eigenes Objekt metadata enthalten, das Vorrang vor einem übereinstimmenden Eintrag in imageMetadata hat. Archivpfade sind auf 1.024 Zeichen, Metadatenschlüssel der obersten Ebene auf 128 Zeichen und jedes Metadatenobjekt sowie die gesamte Map imageMetadata auf 500.000 serialisierte Zeichen begrenzt.

Antwort (201):

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

graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[PUT archive to signed URL]:::proc
    C --> D[POST /api/upload/complete]:::proc
    D --> E["POST /api/datasets/{owner}/{dataset}/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

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

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/{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#

Untersuche, annotiere, verschiebe und lösche Datensatzbilder anhand ihrer 24-stelligen Bild-ID. Siehe die Dokumentation zu Annotationen.

Bild abrufen#

GET /api/images/{imageId}

Python SDK: client.images.retrieve(image_id)

Gibt das Objekt metadata (benutzerdefiniert, vom Benutzer definiert), das Objekt 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.

Body (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] }
    ]
}

Body (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 YOLO-Inferenz auf dem Bild aus und gibt vorhergesagte Annotationen zurück. Sie werden nicht gespeichert – schreibe die Ergebnisse mit PATCH /api/images/{imageId} zurück, sobald du mit ihnen zufrieden bist.

Antwort: success, predictions (Annotationsobjekte), modelUsed und inferenceTime. Ein Modell, dessen Klassen nicht mit dem Datensatz übereinstimmen, gibt 422 zurück.

Dataset automatisch annotieren#

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

Python SDK: client.datasets.create_batch(owner, dataset, model_id=...)

Speichert eine Dataset-Version, reiht dann einen Durchlauf in die Warteschlange ein, der die unbeschrifteten Bilder des Datasets mit dem Modell beschriftet und 202 zurückgibt. Der Body übernimmt dieselben Felder modelId, confidence und iou wie der Endpunkt für einzelne Bilder sowie includeAnnotated (Standard false), um auch Bilder zu annotieren, die bereits Beschriftungen haben, und ein optionales classMapping-Array, das den Dataset-Klassenindex für jede Modellklasse angibt, oder null, um dies zu überspringen. Bestehende Beschriftungen werden niemals geändert, und der Durchlauf wird für die tatsächlich verarbeiteten Bilder abgerechnet. 402 bedeutet, dass das Guthaben die Schätzung nicht abdecken kann, 409, dass das Dataset nicht bereit ist, keine zu annotierenden Bilder mehr übrig hat oder bereits ein Durchlauf ausgeführt wird, und 422, dass das Dataset keine Klassen hat: Erstelle sie mit dem Klassen-Endpunkt, bevor du diesen Endpunkt aufrufst, was der Schritt „Klassen zuordnen“ der App tut, bevor er einen Durchlauf startet.

GET unter demselben Pfad (client.datasets.batch(owner, dataset)) gibt den laufenden Durchlauf und dessen Fortschritt zurück oder den letzten abgeschlossenen Durchlauf, bis dieser verworfen wird; DELETE (client.datasets.delete_batch(owner, dataset)) bricht einen laufenden Durchlauf ab oder regelt die Abrechnung und verwirft die abgeschlossene Zusammenfassung.

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

Konflikte von Dateinamen oder Inhalten geben 409 zurück, bis du eine für alle Bilder geltende conflictPolicy aus skip, keep_both oder replace auswählst. 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 und thumbnails, beide nach Bild-ID verschlüsselt.

Projekte-API#

Organisiere deine Modelle in Projekten. Jedes Modell gehört zu genau einem Projekt. Siehe die 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.

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.

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 löschen. Für Projektmetadaten gelten dieselben Beschränkungen von 128 Zeichen pro Schlüssel und 500.000 Zeichen für serialisierte Objekte wie für Datensatzmetadaten.

Projekt löschen#

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

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

Verschiebt das Projekt und seine Modelle in den Papierkorb und gibt cascadedModels zurück.

Projekt klonen#

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

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

Klont ein zugängliches Projekt und seine abgeschlossenen Modelle. Der optionale Body akzeptiert project, name, description, visibility, license und ein Ziel in owner.

Modelle-API#

Verwalte trainierte YOLO-Modelle – zeige Metriken an, lade Gewichte herunter, führe Inferenz aus und überwache das Training. Siehe die Modelldokumentation.

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 weitere – sowie isOwner.

Modell erstellen#

POST /api/models

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

Erstellt einen nicht trainierten Modelldatensatz, 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)

Akzeptierte Felder umfassen name, description, color, metadata, status, license, datasetSlug, trainArgs, trainResults, epochs, bestEpoch, bestFitness, version, trainingError und starred. Das alleinige Übergeben von projectId verschiebt das Modell in ein anderes Projekt desselben Eigentümers; die Antwort gibt den slug des Modells im Ziel, renamed: true, wenn dieser Slug dort bereits vergeben war, und 409 zurück, während das Modell noch trainiert.

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

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

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.

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 Gewichte des Modells zurück.

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

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 Eingabelimits 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, mit dem Divisor 255 für die standardmäßige 8-Bit-Karte und 65535, wenn bits 12 oder 16 ist). Das Objekt metadata enthält die Bildanzahl, Funktionslaufzeiten, Aufgabe und Dienstversionen. Interne Modellpfade werden nie 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,
        "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, Rechendetails, Trainingsargumenten, Epochenmetriken und sicheren Fehlerdetails zurück oder null, wenn das Modell noch nie trainiert wurde. Modelle in öffentlichen Projekten können ohne Authentifizierung gelesen werden.

Training abbrechen#

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

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

Beendet die laufende Recheninstanz und markiert den Auftrag als abgebrochen. Gibt 409 zurück, wenn das Training nicht mehr aktiv ist.

Trainings-API#

Starte YOLO-Training auf Cloud-GPUs und überwache den Fortschritt in Echtzeit. Siehe die Dokumentation zum Cloud-Training.

graph LR
    A[POST /api/training/start]:::start --> B[Job Created]:::proc
    B --> C{Training}:::decide
    C -->|progress| D[GET .../training]:::proc
    C -->|cancel| E[DELETE .../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

GPU-Verfügbarkeit abrufen#

GET /api/training/gpu-availability

Python SDK: client.training.gpu_availability()

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

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 für die Bereitstellung am Rand in optimierte Formate wie ONNX, TensorRT, CoreML und LiteRT. Siehe die 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

Antwort (201): id, format, status (queued oder running), gpuType, region. 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 Exportziel der API.

nms=None verwendet standardmäßig Rohausgaben für externes NMS. Setze nms=False, um einen verfügbaren NMS-freien Kopf auszuwählen; nicht unterstützte Formate greifen auf ihren nativen Ausgabepfad zurück. Die Einträge nms oben identifizieren Formate, die NMS mit nms=True einbetten 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, Zeitstempeln und — nach Abschluss — einem file- Objekt 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 aktiven Export ab oder löscht einen abgeschlossenen Export samt Datei. Die Antwort gibt an, welcher Vorgang ausgeführt wurde:

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

Bereitstellungs-API#

Stelle Modelle an dedizierten Inferenzendpunkten mit Zustandsprüfungen und Überwachung bereit. Siehe die Dokumentation zu Endpunkten.

graph LR
    A[Create]:::start --> B[Deploying]:::proc
    B --> C[Ready]:::out
    C -->|action stop| D[Stopped]:::extern
    C -->|action replace| B
    D -->|action 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

Bereitstellungen 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 Arbeitsbereichs ist eine Authentifizierung erforderlich.

Bereitstellung erstellen#

POST /api/deployments/{owner}

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

Textkörper:

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

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

Bereitstellung abrufen#

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

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

Gibt das Objekt deployment mit status, statusMessage, region, serviceUrl und resources zurück.

Bereitstellung starten, stoppen oder ersetzen#

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

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

Ein einzelnes Feld action wählt den Vorgang aus:

{ "action": "start" }

Beim Ersetzen wird eine neue Revision ausgerollt, wobei Bereitstellungs-ID, Region und Endpunkt-URL erhalten bleiben; falls der Rollout fehlschlägt, bleibt die bestehende Revision aktiv. Das Ersatzmodell muss ein abgeschlossenes Modell sein, auf dessen Gewichte dein Schlüssel zugreifen kann. Abgeschlossene Vorgänge geben 200 mit status, ready oder stopped zurück; Vorgänge, deren Rollout noch läuft, geben 202 mit deploying oder stopping zurück.

Bereitstellung löschen#

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

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

Entfernt den Inferenzendpunkt dauerhaft.

Integritätsprüfung#

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

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

Sendet Ping-Anfragen an den Endpunkt und wärmt ihn auf. Dabei werden healthy, latencyMs und der Code status des vorgelagerten Dienstes zurückgegeben.

Inferenz mit einer Bereitstellung 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 der Modellinferenz.

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, Fehlerrate sowie durchschnittliche und p50/p95/p99-Latenz) und timeSeries (Anfragen, Fehler, Latenz, CPU, Arbeitsspeicher und Instanzanzahl). Die Sparkline-Antwort gibt requests24h, totalRequests, errorRate und avgLatencyMs zurück.

Protokolle abrufen#

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

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

Abfrageparameter:

Papierkorb-API#

Zeige vorläufig gelöschte Projekte, Datasets und Modelle an, stelle sie wieder her oder lösche sie dauerhaft. Elemente werden nach 30 Tagen automatisch endgültig gelöscht. Siehe die 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 Summen nach Typ.

Element wiederherstellen#

POST /api/trash

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

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

Beim Wiederherstellen eines Projekts werden auch die damit in den Papierkorb verschobenen Modelle wiederhergestellt; sie werden als restoredModels gemeldet.

Dauerhaft 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 gibt deletedCount sowie gegebenenfalls cascadedModels und survivingDeployments zurück.

Upload-API#

Lade Dateien mithilfe signierter URLs direkt in den Cloud-Speicher hoch. Beim Abschließen eines Modell-Uploads werden die Gewichte verknüpft; beim Abschließen des Uploads eines Dataset-Archivs wird die Sitzung gespeichert, die du anschließend an den Dataset-Import übergibst. Siehe die Dokumentation zu Daten.

Signierte Upload-URL abrufen#

POST /api/upload/signed-url

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

Textkörper:

{
    "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, unter Verwendung desselben Content-Type, den du deklariert hast, und jedes in headers zurückgegebenen Headers. Dataset-Upload-URLs sind 12 Stunden lang gültig und nur für die Erstellung bestimmt: Ein zweiter PUT an dieselbe URL gibt 412 zurück, und ein PUT 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 verknüpft; bei Dataset-Archiven rufst du als Nächstes ingest auf, um die Verarbeitung zu starten.

Wenn md5 angegeben wird, wird dieser mit dem gespeicherten Objekt abgeglichen. Eine Abweichung gibt 400 zurück; bei einer noch nicht abgeschlossenen Sitzung wird außerdem die hochgeladene Datei gelöscht und die Sitzung unvollständig belassen, fordere also eine neue signierte URL an und lade erneut hoch. Eine abgeschlossene Dataset-Sitzung kann erneut abgeschlossen werden, solange ihr Archiv existiert, aber konkurrierende Abschlüsse mit unterschiedlichen Digests geben 409 zurück; Modellsitzungen werden bei Abschluss entfernt. checksum wird als Modelldatei-Metadaten 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 die Dokumentation zu Integrationen.

Integrationen auflisten#

GET /api/integrations/buckets

Python SDK: client.storage_integrations.list()

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

Standorte ermitteln#

POST /api/integrations/buckets/discover

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

Listet die Buckets oder Container auf, die mit den angegebenen Anmeldedaten lesbar sind, ohne sie 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 Anmeldedatenstrukturen wie bei der Ermittlung sowie ein erforderliches Array targets mit 1 bis 50 Bucket- oder Containernamen. Gibt 201 mit der gespeicherten Integration zurück. Temporäre S3-Anmeldedaten (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 cursor für die nächste Seite.

Speicherverbindung trennen#

DELETE /api/integrations/buckets/{id}

Python SDK: client.storage_integrations.delete(id)

Entfernt die gespeicherten Anmeldedaten, ohne Daten beim Anbieter zu löschen. Verbundene Datensätze bleiben sichtbar, aber ihre Dateien bleiben nicht verfügbar, bis dasselbe Speicherkonto erneut verbunden wird. Erfordert Administratorzugriff auf den Arbeitsbereich.

API zum Importieren von Datensätzen#

Importiere Datensätze 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: Arbeitsbereichdetails, newDatasets, die importiert würden, Anzahlen der übersprungenen, nicht unterstützten und nicht aufgelösten Projekte, bytesTotal sowie dein verbleibender storage-Spielraum. Der Roboflow-API-Schlüssel wird aus dem Textkörper 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 Aufnahmeaufträge für bis zu 500 ausgewählte Roboflow-Projektversionen in die Warteschlange und verwendet dabei die im Vorschaufenster 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 jeder Datensatz muss in das Größenlimit pro Import deines Tarifs passen.

Konto-API#

Untersuche dein Platform-Konto, deine Schlüssel, deinen Speicher und öffentliche Profile. Siehe die 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, der den Schlüssel ausgestellt hat.

{
    "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. Mit API-Schlüsseln authentifizierte Anfragen erhalten nur Metadaten; vollständige Schlüsselwerte werden dem Arbeitsbereichsinhaber unter Settings > API Keys in der Platform-Oberfläche angezeigt. 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": 107374182400, "percent": 1.0 },
        "datasets": { "current": 536870912, "limit": 107374182400, "percent": 0.5 }
    },
    "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"
}

Öffentliches Benutzerprofil abrufen#

GET /api/users

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

Abfrageparameter:

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

Einem 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 die Tarifnutzung und dein Gutschriftsbuch. Siehe die Abrechnungsdokumentation.

Tarif und Nutzung anzeigen#

GET /api/billing/usage-summary

Python SDK: client.billing.usage_summary()

Gibt plan (ID, Status, Abrechnungszyklus, Periodenende), metrics (Speicherlimit und Nutzung), trainingCredit, features, creditsCents sowie Sitzplatzanzahlen 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, optional receiptUrl sowie Modellkontext für Trainingsgebühren. Interne Abrechnungsdetails werden niemals zurückgegeben.

API erkunden#

Durchsuche öffentliche Projekte und Datensätze, die von der Community geteilt werden. Siehe die Dokumentation zum Erkunden.

Öffentliche Inhalte durchsuchen#

GET /api/explore/search

Python SDK: client.explore.search()

Abfrageparameter:

Antwort: projects, datasets und hasMore.

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, mit einer Methode pro Endpunkt (client.datasets.list, client.models.predict, client.exports.create, ...). Jede Methode akzeptiert Pfadparameter in ihrer Reihenfolge, andere Eingaben als Schlüsselwortargumente und optionale timeout und extra_headers pro Anfrage.

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

from ultralytics_platform import Platform

with Platform() as client:  # reads ULTRALYTICS_API_KEY or the key saved by yolo login
    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 für async/await-Code denselben Ressourcenbaum bereit. Nicht erfolgreiche Antworten lösen APIError mit status_code, body und geparstem json aus, und Verbindungsfehler lösen APIConnectionError aus. Im SDK-Repository findest du die vollständige README.

Python-Integration#

Für Trainings- und Inferenz-Workflows verwendest du das Ultralytics Python-Paket, das Authentifizierung, Uploads und Echtzeit-Metrik-Streaming automatisch übernimmt. Unter Python 3.11+ installiert pip install ultralytics zudem das ultralytics-platform SDK. Wenn model.train(project=...) auf die Plattform ausgerichtet ist, streamen die Trainings-Callbacks Ereignisse über das client.training.metrics() des SDKs und fordern Checkpoint-Upload-URLs über client.models.upload_checkpoint(), die POST /api/webhooks/training/metrics und POST /api/webhooks/models/upload Operationen im OpenAPI-Dokument an, sodass du selbst nichts aufrufen musst.

Installation und Einrichtung#

Für die Plattformintegration sind Python>=3.11 und ultralytics>=8.4.120 erforderlich:

pip install "ultralytics>=8.4.120"

Installation überprüfen:

yolo check

Authentifizierung#

yolo login YOUR_API_KEY

Platform-Datasets verwenden#

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

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:

Auf Platform übertragen#

Sende Ergebnisse an ein Platform-Projekt:

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 (in Echtzeit)
• Gewichte des finalen Modells
• Validierungsdiagramme
• Konsolenausgabe
• Systemmetriken
• Trainingsargumente und Host-Umgebung (Hostname, Betriebssystem, Python, Hardware, Git-Commit, Befehlszeile)

API-Beispiele#

Modell aus Platform laden:

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