REST API Referenz#

Ultralytics Platform bietet eine REST-API für den programmatischen Zugriff auf Datasets, Bilder, Projekte, Modelle, Training, Exporte und Deployments.

# 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 Platform-Ressourcen herum 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 – wie das Lesen eines öffentlichen Datasets, Projekts oder Modells, das Auflisten öffentlicher Dataset-Bilder, das Ausführen von Inferenz auf einem öffentlichen Modell oder das Durchsuchen von Explore – akzeptieren auch anonyme Anfragen und geben bei Angabe eines Schlüssels einfach mehr zurück.

Einen API-Schlüssel abrufen#

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

Siehe API Keys für detaillierte Anweisungen.

Autorisierungs-Header#

Füge deinen API-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 über dieselben menschenlesbaren Namen angesprochen, die in Platform-URLs vorkommen, nicht über Datenbank-IDs:

• {owner} ist ein persönlicher Benutzername oder ein Team-Workspace-Handle: 4–32 Zeichen, Kleinbuchstaben und Zahlen mit einzelnen Bindestrichen zwischen den Segmenten.
• {dataset}, {project}, {model} und {deployment} folgen demselben Muster mit Kleinbuchstaben und Bindestrichen, bis zu 128 Zeichen.
• {imageId} und {exportId} sind 24-stellige Hexadezimal-IDs, die von der API zurückgegeben werden.
• Das Umbenennen einer Ressource über PATCH ändert den Anzeigewert name und den URL-Namen gemeinsam, und die Antwort gibt den aktuellen URL-Namen zurück, damit du ihm weiterhin folgen kannst.

Ratenbegrenzungen#

Die API erzwingt Gleitfenster-Limits pro API-Schlüssel. Jede Route fällt in eine Kategorie, und jede Kategorie hat einen unabhängigen Zähler, sodass 20 Vorhersageanfragen dein Standardkontingent nicht verbrauchen.

Platform-Routen, die nur für den Browser bestimmt sind, wie z. B. Abrechnungs-Checkout und Teamverwaltung, haben eigene Limits, die für den API-Schlüssel-Datenverkehr nicht gelten.

Wenn die API gedrosselt wird, gibt sie 429 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)#

Dedicated endpoints unterliegen keinen Platform-API-Schlüssel-Ratenlimits, wenn du das eigene 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#

Erfolgsantworten#

Antworten sind JSON-Objekte mit ressourcenspezifischen Feldern. Es gibt keinen generischen Umschlag: Listen-Endpunkte geben eine benannte Sammlung zusammen mit Zählungen zurück, und Mutationen geben die geänderten Identifikatoren zurück.

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

Datenhaltige Antworten enthalten auch 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"
}

Paginierung#

Der Paginierungsstil hängt von der Sammlung ab:

Datasets API#

Erstelle, durchsuche und verwalte beschriftete Bild-Datasets zum Trainieren von YOLO-Modellen. Siehe Datasets documentation.

Datasets auflisten#

GET /api/datasets/{owner}

Python SDK: client.datasets.list(owner)

Gibt die öffentlichen Datasets des Besitzers sowie private Datasets zurück, wenn dein Schlüssel diesen Workspace einsehen kann.

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

Dataset abrufen#

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

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

Gibt das vollständige Dataset-Objekt unter einem dataset-Schlüssel zurück, einschließlich classNames, splits, versions, source und dem benutzerdefinierten metadata-Objekt.

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

Antwort (201):

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

Dataset aktualisieren#

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

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

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

Das Umbenennen ändert den URL-Namen, verwende daher den zurückgegebenen dataset-Wert für nachfolgende Anfragen.

Dataset löschen#

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

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

Verschiebt das Dataset in den Papierkorb, wo es 30 Tage lang wiederherstellbar ist.

Dataset klonen#

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

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

Kopiert ein zugängliches Dataset mitsamt seinen 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. Datasets, die von einer verknüpften Speicherquelle unterstützt werden, geben 409 zurück, da ihre Dateien nicht kopiert werden.

Einen Dataset-Export 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 Zustand des Datasets zu exportieren, wobei der zwischengespeicherte Export wiederverwendet wird, wenn sich seit seiner Generierung nichts geändert hat.

Abfrageparameter:

Antwort:

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

Das Anfordern einer bestimmten Version gibt downloadUrl und version anstelle von cached zurück.

Dataset-Version erstellen#

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

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

Erstellt einen unveränderlichen, nummerierten Schnappschuss des Datensatzes und speichert dessen NDJSON-Export. Erfordert Editor-Zugriff.

Body (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 Schnappschuss zurückgegeben wurde.

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}

Dataset-Version 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 Bildbytes zu kopieren.

Body:

{
    "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 klassenbezogene Annotationsanzahlen, Bild- und Annotationshistogramme sowie Heatmaps zurück. Große Datensätze werden stichprobenartig erfasst. In diesem Fall meldet sampleSize, wie viele Bilder dazu 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 dann die Quellen 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 (deren Annotationen werden gelöscht und die verbleibenden Klassen-IDs rücken nach unten):

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

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

{
    "classIds": [2, 4]
}

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

Splits 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 Splits verteilt neu zu. Die drei Prozentsätze müssen zusammen 100 ergeben.

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

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

Dataset-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 reiht eine Einbettungsanalyse in die Warteschlange ein und gibt 202 mit einer jobId zurück. DELETE bricht den aktiven Job ab und gibt die ID des abgebrochenen Jobs oder null zurück.

Bild-Clustering#

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

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

Gibt das UMAP-2D-Layout aus einer abgeschlossenen Analyse zurück, paginiert mit offset und limit (Standard und max. 50.000). Jeder Eintrag hat 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 dieselbe Bildform für bis zu 1.000 bereitgestellte Bild-IDs zurück und akzeptiert dieselben Filter- und URL-Abfrageparameter wie der Listen-Vorgang.

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

Datensatzdaten einlesen#

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

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

Verarbeitet einen abgeschlossenen Upload, ein Remote-Archiv oder eine verbundene Speicherquelle in einen bestehenden Datensatz. Gib genau eine Quelle an:

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

Body (hochgeladenes Archiv):

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

Body (Remote-Archiv oder NDJSON):

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

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

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

Body (Anhängen von Metadaten pro Bild):

{
    "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 Ordnern entsprechen. Bei NDJSON-Importen kann jeder Datensatz ein eigenes metadata-Objekt enthalten, das Vorrang vor einem passenden imageMetadata-Eintrag hat. Archivpfade sind auf 1.024 Zeichen, Metadatenschlüssel der obersten Ebene auf 128 Zeichen und jedes Metadatenobjekt sowie die gesamte imageMetadata-Map auf 500.000 serialisierte Zeichen beschränkt.

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#

Datensatzbilder anhand ihrer 24-stelligen Bild-ID untersuchen, annotieren, verschieben und löschen. Siehe Annotationsdokumentation.

Bild abrufen#

GET /api/images/{imageId}

Python SDK: client.images.retrieve(image_id)

Gibt metadata (benutzerdefiniert, vom Benutzer definiert), properties (Dateiname, Hash, Abmessungen, Split, Anzahl, Zeitstempel), labels und die 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 Formen, 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 dessen Annotationen dauerhaft.

Bild automatisch annotieren#

POST /api/images/{imageId}/predict

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

Führt eine 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, wenn du mit ihnen zufrieden bist.

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

Bilder als Batch verschieben#

PATCH /api/images/bulk

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

Verschiebt bis zu 1.000 Bilder aus einem Datensatz in einen anderen Split.

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

Dateinamen- oder Inhaltskonflikte geben 409 zurück, bis du einen korbweiten conflictPolicy aus skip, keep_both oder replace wählst. Die Antwort meldet modifiedCount, skippedCount und targetSplit.

Bilder als Batch 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 mit der Bild-ID als Schlüssel.

Projekte API#

Organisiere deine Modelle in Projekten. Jedes Modell gehört zu einem Projekt. Siehe 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 project-Objekt, ein models-Array von 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 metadata-Objekt ({}), um es zu löschen. Projektmetadaten verwenden dieselben Grenzwerte für Schlüssel (128 Zeichen) und serialisierte Objekte (500.000 Zeichen) wie 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)

Klonen eines zugänglichen Projekts und seiner abgeschlossenen Modelle. Der optionale Body akzeptiert project, name, description, visibility, license und ein Ziel owner.

Models API#

Verwalte trainierte YOLO-Modelle – Metriken anzeigen, Gewichte herunterladen, Inferenz ausführen und Training überwachen. Siehe Modell-Dokumentation.

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 model-Objekt – 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 untrainierten Modelleintrag, an den du Gewichte anhängen 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.

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

Benutzerdefinierte metadata ist von trainingsbezogenen Feldern wie trainArgs, environment und trainResults getrennt und verwendet dieselben 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 kurzlebige, signierte URLs für die Modellgewichte 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 bestehendes Projekt.

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

Führe die Inferenz aus.#

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

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

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

Multipart Form:

Gib entweder file oder source an. Tiefenmodelle akzeptieren auch bits (8, 12 oder 16), um die PNG-Quantisierung der Tiefenkarte auszuwählen. Anfragen, die die Eingabegrenzen 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 zur dichten Vorhersage eine semantic_mask oder depth PNG-Nutzlast (Tiefenwerte sind pixel × max / divisor, mit Divisor 255 für die Standard-8-Bit-Karte und 65535, wenn bits 12 oder 16 ist). Das Objekt metadata meldet Bildanzahl, Funktionslaufzeiten, Aufgabe und Dienstversionen. 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,
        "functionTimeAlive": 184.2,
        "functionTimeCall": 0.31,
        "task": "detect",
        "version": { "ultralytics": "8.4.120" }
    }
}

Training-Fortschritt überprüfen#

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

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

Gibt job zurück, das Status, Epochenfortschritt, Timing, Berechnungsdetails, Trainingsargumente, Epochenmetriken und sichere Fehlerdetails enthält, oder null, wenn das Modell noch nie trainiert wurde. Modelle in öffentlichen Projekten sind ohne Authentifizierung lesbar.

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 Job als abgebrochen. Gibt 409 zurück, wenn das Training nicht mehr aktiv ist.

Training API#

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

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 Lagerbestand, aufgeschlüsselt nach GPU ID, zurück. Öffentlich und unauthentifiziert; übergebe managed=true, um die verwaltete Trainingskapazität einzubeziehen, wozu ein API Key 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 keine Kapazität für die angeforderte GPU verfügbar ist.

Exports API#

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

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 äquivalenter Export, der bereits ausgeführt wird, gibt 409 zurück.

Unterstützte Formate:

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

Export-Status abrufen#

GET /api/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 zurück, das size, downloadUrl und downloadFilename enthält.

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 fertigen Export samt Datei. Die Antwort meldet, was eingetreten ist:

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

Deployments API#

Deploye Modelle auf dedizierten Inferenz-Endpunkten mit Integritätsprüfungen (Health Checks) und Monitoring. Siehe Endpoints-Dokumentation.

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

Deployments auflisten#

GET /api/deployments/{owner}

Python SDK: client.deployments.list(owner)

Abfrageparameter:

Anonyme Aufrufer müssen nach einem öffentlichen Modell filtern; das Auflisten eines ganzen Workspaces erfordert eine Authentifizierung.

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 und resources zurück.

Ein Deployment starten, stoppen oder ersetzen#

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

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

Ein einzelnes Feld action wählt die Operation aus:

{ "action": "start" }

Beim Ersetzen wird eine neue Revision ausgerollt, während Deployment-ID, Region und Endpunkt-URL erhalten bleiben; die bestehende Revision bleibt aktiv, falls das Rollout fehlschlägt. Das Ersetzungsmodell muss ein fertiges Modell sein, dessen Gewichte dein Key aufrufen kann. Abgeschlossene Operationen geben 200 mit status ready oder stopped zurück; Operationen, die noch ausgerollt werden, geben 202 mit deploying oder stopping zurück.

Deployment löschen#

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

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

Entfernt den Inferenz-Endpunkt dauerhaft.

Gesundheitsprüfung#

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

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

Pingt und wärmt den Endpunkt auf und gibt healthy, latencyMs und den übergeordneten status-Code zurück.

Inferenz auf einem Deployment ausführen#

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

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

Leitet ein Bild oder Video durch den dedizierten Endpunkt. Die Anfrage- und Antwortverträge entsprechen der Modell-Inferenz.

Multipart Form:

Metriken abrufen#

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

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

Abfrageparameter:

Die vollständige Antwort enthält summary (Anfragesummen, Fehlerrate, durchschnittliche und p50/p95/p99-Latenz) und timeSeries (Anfragen, Fehler, Latenz, CPU, Arbeitsspeicher, Instanzanzahl). Die Sparkline-Antwort gibt requests24h, totalRequests, errorRate und avgLatencyMs zurück.

Logs abrufen#

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

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

Abfrageparameter:

Papierkorb-API#

Soft-gelöschte Projekte, Datasets und Modelle anzeigen, wiederherstellen und dauerhaft löschen. Elemente werden nach 30 Tagen automatisch bereinigt. Siehe Papierkorb-Dokumentation.

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

Das Wiederherstellen eines Projekts stellt auch die Modelle wieder her, die mit ihm in den Papierkorb verschoben wurden, gemeldet als restoredModels.

Dauerhaft löschen#

DELETE /api/trash

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

Ein einzelnes Element löschen:

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

Oder den gesamten Papierkorb leeren:

{
    "all": true
}

Die Antwort meldet deletedCount sowie gegebenenfalls cascadedModels und survivingDeployments.

Upload-API#

Lade Dateien mithilfe signierter URLs direkt in den Cloud-Speicher hoch. Das Abschließen eines Modell-Uploads fügt dessen Gewichte hinzu; das Abschließen eines Dataset-Archiv-Uploads protokolliert die Sitzung, die du dann an Dataset Ingest übergibst. Siehe Data-Dokumentation.

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

Lade die Datei mit einer PUT-Anfrage an uploadUrl hoch und verwende dabei denselben Content-Type, den du deklariert hast.

Upload abschließen#

POST /api/upload/complete

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

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

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

Storage Integrations API#

Verbinde schreibgeschützte Google Cloud Storage-, Amazon S3- oder Azure Blob Storage-Konten und browse sie als Dataset-Quellen. Siehe Integrations-Dokumentation.

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.

Speicherorte entdecken#

POST /api/integrations/buckets/discover

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

Listet die Buckets oder Container auf, die mit den bereitgestellten Anmeldedaten gelesen werden können, 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=...)

Gleiche Anmeldedaten-Strukturen wie bei der Erkennung, plus ein erforderliches targets-Array von 1-50 Bucket- oder Container-Namen. 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 (jedes kind ist folder oder file) und ein optionales cursor für die nächste Seite zurück.

Speicher trennen#

DELETE /api/integrations/buckets/{id}

Python SDK: client.storage_integrations.delete(id)

Entfernt die gespeicherten Anmeldedaten, ohne die Anbietersdaten zu löschen. Verbundene Datasets bleiben sichtbar, aber ihre Dateien bleiben so lange nicht verfügbar, bis dasselbe Speicheronto wieder verbunden wird. Erfordert Workspace-Admin-Zugriff.

Dataset Import API#

Importiere Datasets von Drittanbieterdiensten. Siehe Roboflow-Integration.

Vorschau eines Roboflow-Imports#

POST /api/integrations/roboflow/preview

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

Löst einen Roboflow API-Schlüssel in einen Importplan auf: Workspace-Details, newDatasets, die importiert würden, Anzahl der übersprungenen, nicht unterstützten und nicht aufgelösten Projekte, bytesTotal und dein storage-Spielraum. Der Roboflow API-Schlüssel wird aus dem Body gelesen und nicht dauerhaft gespeichert.

{
    "apiKey": "ROBOFLOW_API_KEY"
}

Import von Roboflow#

POST /api/integrations/roboflow/import

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

Reiht Aufnahme-Jobs für bis zu 500 ausgewählte Roboflow-Projektversionen ein, wobei die von der Vorschau zurückgegebenen Elemente verwendet werden.

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

Antwort (201): imported-, failed- und skipped-Arrays. Importe erfordern Speicherplatz, und jedes Dataset muss in das Grössenlimit pro Import deines Tarifs passen.

Konto-API#

Inspiziere dein Platform-Konto, deine Schlüssel, deinen Speicher und deine öffentlichen Profile. Siehe Einstellungen-Dokumentation.

Kontoübersicht#

GET /api/account/summary

Python SDK: client.account.summary()

Gibt den Tarif, das Guthaben und die Ressourcenanzahl für den Workspace 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-Keys auflisten#

GET /api/api-keys

Python SDK: client.account.api_keys()

Gibt keys mit keyId, name, keyPrefix und createdAt für den Workspace des Schlüssels zurück. Per API-Schlüssel authentifizierte Anfragen erhalten nur Metadaten; vollständige Schlüsselwerte werden dem Workspace-Inhaber unter Einstellungen > API-Schlüssel in der Platform-Benutzeroberfläche angezeigt, wo Schlüssel auch erstellt und widerrufen werden.

Speichernutzung überprü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 für authentifizierte Aufrufer 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#

Überprüfe die Tarbitnutzung und dein Guthabenkonto. Siehe Abrechnungsdokumentation.

Tarif und Nutzung anzeigen#

GET /api/billing/usage-summary

Python SDK: client.billing.usage_summary()

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

Transaktionen anzeigen#

GET /api/billing/transactions

Python SDK: client.billing.transactions()

Abfrageparameter:

Jede Transaktion umfasst id, type (wie purchase, training, monthly_grant oder refund), amountCents, balanceAfter, createdAt, ein optionales receiptUrl sowie Modellkontext für Trainingskosten. Interne Abrechnungsdetails werden niemals zurückgegeben.

Explore API#

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

Ö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 die Pfadparameter positionell, andere Eingaben als Schlüsselwortargumente und optionale anfragespezifische timeout und extra_headers.

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

from ultralytics_platform import Platform

with Platform() as client:  # reads ULTRALYTICS_API_KEY
    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, erfolglose Antworten lösen APIError mit status_code, body und geparstem json aus, und Verbindungsfehler lösen APIConnectionError aus. Siehe das SDK-Repository für das vollständige README.

Python-Integration#

Verwende für Trainings- und Inferenz-Workflows das Ultralytics Python-Paket, das Authentifizierung, Uploads und Echtzeit-Metrik-Streaming automatisch verarbeitet.

Installation & Einrichtung#

pip install "ultralytics>=8.4.120"

Installation überprüfen:

yolo check

Authentifizierung#

yolo login YOUR_API_KEY

Plattform-Datensätze verwenden#

Referenziere Datasets mit ul://-URIs:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Train on your Platform dataset
model.train(
    data="ul://your-username/datasets/your-dataset",
    epochs=100,
    imgsz=640,
)

URI-Format:

Push an die Plattform#

Ergebnisse an ein Plattform-Projekt senden:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Results automatically sync to Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="your-username/my-project",
    name="experiment-1",
)

Was synchronisiert wird:

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

API-Beispiele#

Lade ein Modell von der Plattform:

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

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

Inferenz ausführen:

results = model("image.jpg")

# Access results
for r in results:
    boxes = r.boxes  # Detection boxes
    masks = r.masks  # Segmentation masks
    keypoints = r.keypoints  # Pose keypoints
    probs = r.probs  # Classification probabilities

Modell exportieren:

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

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

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

Validierung:

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

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

FAQ#