REST API Referenz

Ultralytics Platform bietet eine umfassende REST API für den programmatischen Zugriff auf Datensätze, Modelle, Training und Deployments.

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

API-Übersicht

Die API ist um die Kernressourcen der Plattform herum organisiert:

graph LR
    A[API Key] --> B[Datasets]
    A --> C[Projects]
    A --> D[Models]
    A --> E[Deployments]
    B -->|train on| D
    C -->|contains| D
    D -->|deploy to| E
    D -->|export| F[Exports]
    B -->|auto-annotate| B

Authentifizierung

Ressourcen-APIs wie Datensätze, Projekte, Modelle, Training, Exporte und Vorhersagen verwenden eine API-Key-Authentifizierung. Öffentliche Endpoints (Auflistung öffentlicher Datensätze, Projekte und Modelle) unterstützen anonymen Lesezugriff ohne Key. Kontoorientierte Routen – einschließlich Aktivität, Einstellungen, Teams, Abrechnung und DSGVO-Abläufen – erfordern derzeit eine authentifizierte Browsersitzung und sind nicht über API-Key verfügbar.

API-Key abrufen

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

Siehe API-Keys für detaillierte Anweisungen.

Autorisierungs-Header

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

Authorization: Bearer YOUR_API_KEY

Beispiel

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

Basis-URL

Alle API-Endpoints verwenden:

Ratenbegrenzungen

Die API erzwingt Ratenbegrenzungen pro API-Key (Sliding-Window, unterstützt durch Upstash Redis), um Missbrauch zu verhindern, während legitime Nutzung uneingeschränkt bleibt. Anonymer Datenverkehr wird zusätzlich durch die Missbrauchskontrollen auf Plattformebene von Vercel geschützt.

Bei Drosselung gibt die API 429 mit Retry-Metadaten zurück:

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

Limits pro API-Key

Ratenbegrenzungen werden automatisch basierend auf dem aufgerufenen Endpoint angewendet. Ressourcenintensive Operationen haben strengere Limits, um Missbrauch zu verhindern, während Standard-CRUD-Operationen sich ein großzügiges Standardlimit teilen:

Jede Kategorie hat einen unabhängigen Zähler pro API-Key. Wenn du beispielsweise 20 Predict-Anfragen stellst, beeinflusst dies nicht dein Standard-Kontingent von 100 Anfragen/Min.

Dedizierte Endpoints (Unbegrenzt)

Dedizierte Endpoints unterliegen keinen Ratenbegrenzungen durch API-Keys. Wenn du ein Modell auf einem dedizierten Endpoint bereitstellst, gehen Anfragen an diese Endpoint-URL (z. B. https://predict-abc123.run.app/predict) direkt an deinen dedizierten Dienst ohne Ratenbegrenzung durch die Plattform. Da du für die Rechenleistung bezahlst, erhältst du den Durchsatz deiner dedizierten Dienstkonfiguration anstelle der geteilten API-Limits.

Antwortformat

Erfolgsantworten

Antworten geben JSON mit ressourcenspezifischen Feldern zurück:

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

Fehlerantworten

{
    "error": "Dataset not found"
}

Datensätze-API

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

Datensätze auflisten

GET /api/datasets

Abfrageparameter:

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

Antwort:

{
    "datasets": [
        {
            "_id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "classNames": ["person", "car"],
            "visibility": "private",
            "username": "johndoe",
            "starCount": 3,
            "isStarred": false,
            "sampleImages": [
                {
                    "url": "https://storage.example.com/...",
                    "width": 1920,
                    "height": 1080,
                    "labels": [{ "classId": 0, "bbox": [0.5, 0.4, 0.3, 0.6] }]
                }
            ],
            "createdAt": "2024-01-15T10:00:00Z",
            "updatedAt": "2024-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

Dataset abrufen

GET /api/datasets/{datasetId}

Gibt die vollständigen Dataset-Details zurück, einschließlich Metadaten, Klassennamen und Split-Anzahlen.

Dataset erstellen

POST /api/datasets

Body:

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

Dataset aktualisieren

PATCH /api/datasets/{datasetId}

Body (partielle Aktualisierung):

{
    "name": "Updated Name",
    "description": "New description",
    "visibility": "public"
}

Dataset löschen

DELETE /api/datasets/{datasetId}

Löscht das Dataset vorläufig (wird in den Papierkorb verschoben und kann für 30 Tage wiederhergestellt werden).

Dataset klonen

POST /api/datasets/{datasetId}/clone

Erstellt eine Kopie des Datasets mit allen Bildern und Labels. Nur öffentliche Datasets können geklont werden. Erfordert eine aktive Plattform-Browsersitzung – nicht über API-Key verfügbar.

Body (alle Felder optional):

{
    "name": "cloned-dataset",
    "description": "My cloned dataset",
    "visibility": "private",
    "owner": "team-username"
}

Dataset exportieren

GET /api/datasets/{datasetId}/export

Gibt eine JSON-Antwort mit einer signierten Download-URL für den neuesten Dataset-Export zurück.

Abfrageparameter:

Antwort:

{
    "downloadUrl": "https://storage.example.com/export.ndjson?signed=...",
    "cached": true
}

Dataset-Version erstellen

POST /api/datasets/{datasetId}/export

Erstelle einen neuen nummerierten Versions-Snapshot des Datasets. Nur für den Besitzer. Die Version erfasst die aktuelle Anzahl der Bilder, Klassen, Annotationen und die Split-Verteilung und generiert und speichert dann einen unveränderlichen NDJSON-Export.

Request Body:

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

Alle Felder sind optional. Das Feld description ist ein vom Benutzer bereitgestelltes Label für die Version.

Antwort:

{
    "version": 3,
    "downloadUrl": "https://storage.example.com/v3.ndjson?signed=..."
}

Versionsbeschreibung aktualisieren

PATCH /api/datasets/{datasetId}/export

Aktualisiere die Beschreibung einer bestehenden Version. Nur für den Besitzer.

Request Body:

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

Antwort:

{
    "ok": true
}

Klassenstatistik abrufen

GET /api/datasets/{datasetId}/class-stats

Gibt die Klassenverteilung, die Standort-Heatmap und Dimensionsstatistiken zurück. Ergebnisse werden für bis zu 5 Minuten gecacht.

Antwort:

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120 }],
        "heightHistogram": [{ "bin": 480, "count": 95 }],
        "pointsHistogram": [{ "bin": 4, "count": 200 }]
    },
    "locationHeatmap": {
        "bins": [
            [5, 10],
            [8, 3]
        ],
        "maxCount": 50
    },
    "dimensionHeatmap": {
        "bins": [
            [2, 5],
            [3, 1]
        ],
        "maxCount": 12,
        "minWidth": 10,
        "maxWidth": 1920,
        "minHeight": 10,
        "maxHeight": 1080
    },
    "classNames": ["person", "car", "dog"],
    "cached": true,
    "sampled": false,
    "sampleSize": 1000
}

Modelle abrufen, die mit dem Dataset trainiert wurden

GET /api/datasets/{datasetId}/models

Gibt Modelle zurück, die mit diesem Dataset trainiert wurden.

Antwort:

{
    "models": [
        {
            "_id": "model_abc123",
            "name": "experiment-1",
            "slug": "experiment-1",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "projectId": "project_xyz",
            "projectSlug": "my-project",
            "projectIconColor": "#3b82f6",
            "projectIconLetter": "M",
            "username": "johndoe",
            "startedAt": "2024-01-14T22:00:00Z",
            "completedAt": "2024-01-15T10:00:00Z",
            "createdAt": "2024-01-14T21:55:00Z",
            "metrics": {
                "mAP50": 0.85,
                "mAP50-95": 0.72,
                "precision": 0.88,
                "recall": 0.81
            }
        }
    ],
    "count": 1
}

Dataset automatisch annotieren

POST /api/datasets/{datasetId}/predict

Führe YOLO-Inferenz auf Dataset-Bildern aus, um Annotationen automatisch zu generieren. Verwendet ein ausgewähltes Modell, um Labels für nicht annotierte Bilder vorherzusagen.

Body:

Dataset-Ingest

POST /api/datasets/ingest

Erstelle einen Dataset-Ingest-Job, um hochgeladene ZIP- oder TAR-Dateien, einschließlich .tar.gz und .tgz, die Bilder und Labels enthalten, zu verarbeiten.

graph LR
    A[Upload Archive] --> B[POST /api/datasets/ingest]
    B --> C[Process Archive]
    C --> D[Extract images]
    C --> E[Parse labels]
    C --> F[Generate thumbnails]
    D & E & F --> G[Dataset ready]

Dataset-Bilder

Bilder auflisten

GET /api/datasets/{datasetId}/images

Abfrageparameter:

Signierte Bild-URLs abrufen

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

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

Bild löschen

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

Bild-Labels abrufen

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

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

Bild-Labels aktualisieren

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

Body:

{
    "labels": [
        { "classId": 0, "bbox": [0.5, 0.5, 0.2, 0.3] },
        { "classId": 1, "segments": [0.1, 0.2, 0.3, 0.2, 0.2, 0.4] }
    ]
}

Massen-Bildoperationen

Bilder zwischen Splits (train/val/test) innerhalb eines Datasets verschieben:

PATCH /api/datasets/{datasetId}/images/bulk

Bilder massenhaft löschen:

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

Projects API

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

Projekte auflisten

GET /api/projects

Abfrageparameter:

Projekt abrufen

GET /api/projects/{projectId}

Projekt erstellen

POST /api/projects

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "slug": "my-project", "description": "Detection experiments"}' \
  https://platform.ultralytics.com/api/projects

Projekt aktualisieren

PATCH /api/projects/{projectId}

Projekt löschen

DELETE /api/projects/{projectId}

Löscht das Projekt vorläufig (wird in den Papierkorb verschoben).

Projekt klonen

POST /api/projects/{projectId}/clone

Klont ein öffentliches Projekt (mit all seinen Modellen) in deinen Workspace. Erfordert eine aktive Plattform-Browsersitzung – nicht über API-Key verfügbar.

Projekt-Icon

Lade ein Projekt-Icon hoch (Multipart-Formular mit Bilddatei):

POST /api/projects/{projectId}/icon

Entferne das Projekt-Icon:

DELETE /api/projects/{projectId}/icon

Beide erfordern eine aktive Plattform-Browsersitzung – nicht über API-Key verfügbar.

Models API

Verwalte trainierte YOLO Modelle – sehe Metriken ein, lade Gewichte herunter, führe Inferenz aus und exportiere in andere Formate. Siehe Models documentation.

Modelle auflisten

GET /api/models

Abfrageparameter:

Abgeschlossene Modelle auflisten

GET /api/models/completed

Gibt Modelle zurück, deren Training beendet ist (zur Verwendung in Modellselektoren und für Deployments).

Modell abrufen

GET /api/models/{modelId}

Modell erstellen

POST /api/models

JSON-Body:

Modell aktualisieren

PATCH /api/models/{modelId}

Modell löschen

DELETE /api/models/{modelId}

Modelldateien herunterladen

GET /api/models/{modelId}/files

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

Modell klonen

POST /api/models/{modelId}/clone

Klone ein öffentliches Modell in eines deiner Projekte. Erfordert eine aktive Plattform-Browser-Sitzung – nicht über API-Key verfügbar.

Body:

{
    "targetProjectSlug": "my-project",
    "modelName": "cloned-model",
    "description": "Cloned from public model",
    "owner": "team-username"
}

Download verfolgen

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

Analysedaten für Modelldownloads verfolgen.

Inferenz ausführen

POST /api/models/{modelId}/predict

Multipart-Form:

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

Antwort:

{
    "images": [
        {
            "shape": [1080, 1920],
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1
    }
}

Vorhersage-Token abrufen

POST /api/models/{modelId}/predict/token

Modell aufwärmen

POST /api/models/{modelId}/predict/warmup

Training-API

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

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

Training starten

POST /api/training/start

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

Trainingsstatus abrufen

GET /api/models/{modelId}/training

Gibt den aktuellen Status, die Metriken und den Fortschritt eines Trainingsjobs für ein Modell zurück. Öffentliche Projekte sind anonym zugänglich; private Projekte erfordern eine aktive Plattform-Browser-Sitzung (diese Route akzeptiert keine API-Key-Authentifizierung).

Training abbrechen

DELETE /api/models/{modelId}/training

Beendet die laufende Recheninstanz und markiert den Job als abgebrochen. Erfordert eine aktive Plattform-Browser-Sitzung – nicht über API-Key verfügbar.

Deployment-API

Deploye Modelle auf dedizierte Inferenz-Endpunkte mit Gesundheitschecks und Überwachung. Neue Deployments nutzen standardmäßig Scale-to-Zero, und die API akzeptiert ein optionales resources Objekt. Siehe Endpoints documentation.

graph LR
    A[Create] --> B[Deploying]
    B --> C[Ready]
    C -->|stop| D[Stopped]
    D -->|start| C
    C -->|delete| E[Deleted]
    D -->|delete| E
    C -->|predict| F[Inference Results]

Deployments auflisten

GET /api/deployments

Abfrageparameter:

Deployment erstellen

POST /api/deployments

Body:

{
    "modelId": "model_abc123",
    "name": "my-deployment",
    "region": "us-central1",
    "resources": {
        "cpu": 1,
        "memoryGi": 2,
        "minInstances": 0,
        "maxInstances": 1
    }
}

Erstellt einen dedizierten Inferenz-Endpunkt in der angegebenen Region. Der Endpunkt ist global über eine eindeutige URL zugänglich.

Deployment abrufen

GET /api/deployments/{deploymentId}

Deployment löschen

DELETE /api/deployments/{deploymentId}

Deployment starten

POST /api/deployments/{deploymentId}/start

Ein gestopptes Deployment fortsetzen.

Deployment stoppen

POST /api/deployments/{deploymentId}/stop

Ein laufendes Deployment pausieren (stoppt die Abrechnung).

Gesundheitscheck

GET /api/deployments/{deploymentId}/health

Gibt den Gesundheitsstatus des Deployment-Endpunkts zurück.

Inferenz auf Deployment ausführen

POST /api/deployments/{deploymentId}/predict

Sende ein Bild für eine Inferenz direkt an einen Deployment-Endpunkt. Funktionell identisch mit der Modell-Vorhersage, aber für geringere Latenz über den dedizierten Endpunkt geroutet.

Multipart-Form:

Metriken abrufen

GET /api/deployments/{deploymentId}/metrics

Gibt die Anzahl der Anfragen, die Latenz und Fehlerraten-Metriken mit Sparkline-Daten zurück.

Abfrageparameter:

Logs abrufen

GET /api/deployments/{deploymentId}/logs

Abfrageparameter:

Überwachungs-API

Aggregierte Metriken

GET /api/monitoring

Gibt aggregierte Metriken über alle Benutzerbereitstellungen hinweg zurück: Gesamtzahl der Anfragen, aktive Bereitstellungen, Fehlerrate und durchschnittliche Latenz.

Export-API

Konvertiere Modelle in optimierte Formate wie ONNX, TensorRT, CoreML und TFLite für die Edge-Bereitstellung. Siehe Bereitstellungs-Dokumentation.

Exporte auflisten

GET /api/exports

Abfrageparameter:

Export erstellen

POST /api/exports

Body:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"modelId": "MODEL_ID", "format": "onnx"}' \
  https://platform.ultralytics.com/api/exports

Unterstützte Formate:

Export-Status abrufen

GET /api/exports/{exportId}

Export abbrechen

DELETE /api/exports/{exportId}

Export-Download nachverfolgen

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

Aktivitäts-API

Sieh dir einen Feed der letzten Aktionen in deinem Konto an – Trainingsläufe, Uploads und mehr. Siehe Aktivitäts-Dokumentation.

Aktivitäten auflisten

GET /api/activity

Abfrageparameter:

Ereignisse als gesehen markieren

POST /api/activity/mark-seen

Body:

{
    "all": true
}

Oder gib spezifische IDs an:

{
    "eventIds": ["EVENT_ID_1", "EVENT_ID_2"]
}

Ereignisse archivieren

POST /api/activity/archive

Body:

{
    "all": true,
    "archive": true
}

Oder gib spezifische IDs an:

{
    "eventIds": ["EVENT_ID_1", "EVENT_ID_2"],
    "archive": false
}

Papierkorb-API

Gelöschte Elemente anzeigen und wiederherstellen. Elemente werden nach 30 Tagen dauerhaft entfernt. Siehe Papierkorb-Dokumentation.

Papierkorb auflisten

GET /api/trash

Abfrageparameter:

Element wiederherstellen

POST /api/trash

Body:

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

Element dauerhaft löschen

DELETE /api/trash

Body:

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

Papierkorb leeren

DELETE /api/trash/empty

Löscht alle Elemente im Papierkorb dauerhaft.

Abrechnungs-API

Überprüfe dein Guthaben, kaufe Credits, sieh dir den Transaktionsverlauf an und konfiguriere die automatische Aufladung. Siehe Abrechnungs-Dokumentation.

Guthaben abrufen

GET /api/billing/balance

Abfrageparameter:

Antwort:

{
    "creditsCents": 2500,
    "plan": "free",
    "cashBalance": 25,
    "creditBalance": 0,
    "reservedAmount": 0,
    "totalBalance": 25
}

Nutzungszusammenfassung abrufen

GET /api/billing/usage-summary

Gibt Plan-Details, Limits und Nutzungsmetriken zurück.

Transaktionen abrufen

GET /api/billing/transactions

Gibt den Transaktionsverlauf zurück (aktuellste zuerst).

Abfrageparameter:

Checkout-Sitzung erstellen

POST /api/billing/checkout-session

Body:

{
    "amount": 25,
    "owner": "team-username"
}

Erstellt eine Checkout-Sitzung für den Credit-Kauf.

Abonnement-Checkout erstellen

POST /api/billing/subscription-checkout

Erstellt eine Checkout-Sitzung für ein Pro-Abonnement-Upgrade.

Body:

{
    "planId": "pro",
    "billingCycle": "monthly",
    "owner": "team-username"
}

Abonnement kündigen oder fortsetzen

DELETE /api/billing/subscription-checkout

Kündigt ein Pro-Abonnement standardmäßig zum Ende des Abrechnungszeitraums. Sende {"resume": true}, um eine bereits geplante Kündigung vor Ende des Abrechnungszeitraums rückgängig zu machen.

Body:

{
    "resume": true
}

Automatisches Aufladen

Guthaben automatisch aufladen, wenn der Kontostand unter einen Schwellenwert fällt.

Auto-Aufladungskonfiguration abrufen

GET /api/billing/auto-topup

Abfrageparameter:

Auto-Aufladungskonfiguration aktualisieren

PATCH /api/billing/auto-topup

Body:

{
    "enabled": true,
    "thresholdCents": 500,
    "amountCents": 2500
}

Zahlungsmethoden

Zahlungsmethoden auflisten

GET /api/billing/payment-methods

Setup Intent erstellen

POST /api/billing/payment-methods/setup

Gibt ein Client-Secret zum Hinzufügen einer neuen Zahlungsmethode zurück.

Standard-Zahlungsmethode festlegen

POST /api/billing/payment-methods/default

Body:

{
    "paymentMethodId": "pm_123"
}

Rechnungsdaten aktualisieren

PATCH /api/billing/payment-methods

Body:

{
    "name": "Jane Doe",
    "address": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
    }
}

Zahlungsmethode löschen

DELETE /api/billing/payment-methods/{id}

Speicher-API

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

Speicherinformationen abrufen

GET /api/storage

Antwort:

{
    "tier": "free",
    "usage": {
        "storage": {
            "current": 1073741824,
            "limit": 107374182400,
            "percent": 1.0
        }
    },
    "region": "us",
    "username": "johndoe",
    "updatedAt": "2024-01-15T10:00:00Z",
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "dataset_abc123",
                "name": "my-dataset",
                "slug": "my-dataset",
                "sizeBytes": 536870912,
                "type": "dataset"
            },
            {
                "_id": "model_def456",
                "name": "experiment-1",
                "slug": "experiment-1",
                "sizeBytes": 134217728,
                "type": "model",
                "parentName": "My Project",
                "parentSlug": "my-project"
            }
        ]
    }
}

Upload-API

Lade Dateien für schnelle, zuverlässige Übertragungen direkt in den Cloud-Speicher hoch, indem du signierte URLs verwendest. Nutzt einen zweistufigen Prozess: Signierte URL abrufen, dann Datei hochladen. Siehe Daten-Dokumentation.

Signierte Upload-URL abrufen

POST /api/upload/signed-url

Fordere eine signierte URL an, um eine Datei direkt in den Cloud-Speicher hochzuladen. Die signierte URL umgeht den API-Server für große Dateiübertragungen.

Body:

{
    "assetType": "images",
    "assetId": "abc123",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "totalBytes": 5242880
}

Antwort:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "objectPath": "images/abc123/my-image.jpg",
    "downloadUrl": "https://cdn.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

Upload abschließen

POST /api/upload/complete

Benachrichtige die Plattform, dass ein Datei-Upload abgeschlossen ist, damit die Verarbeitung beginnen kann.

Body:

{
    "datasetId": "abc123",
    "objectPath": "datasets/abc123/images/my-image.jpg",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "size": 5242880
}

API-Schlüssel-API

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

API-Schlüssel auflisten

GET /api/api-keys

API-Schlüssel erstellen

POST /api/api-keys

Body:

{
    "name": "training-server"
}

API-Schlüssel löschen

DELETE /api/api-keys

Abfrageparameter:

Beispiel:

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/api-keys?keyId=KEY_ID"

Teams & Mitglieder-API

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

Teams auflisten

GET /api/teams

Team erstellen

POST /api/teams/create

Body:

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

Mitglieder auflisten

GET /api/members

Gibt Mitglieder des aktuellen Arbeitsbereichs zurück.

Mitglied einladen

POST /api/members

Body:

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

Mitgliedsrolle aktualisieren

PATCH /api/members/{userId}

Mitglied entfernen

DELETE /api/members/{userId}

Eigentümerschaft übertragen

POST /api/members/transfer-ownership

Einladungen

Einladung annehmen

POST /api/invites/accept

Einladungsinformationen abrufen

GET /api/invites/info

Abfrageparameter:

Einladung widerrufen

DELETE /api/invites/{inviteId}

Einladung erneut senden

POST /api/invites/{inviteId}/resend

Explore-API

Suche und durchstöbere öffentliche Datensätze und Projekte, die von der Community geteilt wurden. Siehe Explore-Dokumentation.

Öffentliche Inhalte durchsuchen

GET /api/explore/search

Abfrageparameter:

Sidebar-Daten

GET /api/explore/sidebar

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

Benutzer- & Einstellungs-APIs

Verwalte dein Profil, API-Schlüssel, Speichernutzung und Datenschutz-Einstellungen. Siehe Einstellungs-Dokumentation.

Benutzer nach Benutzername abrufen

GET /api/users

Abfrageparameter:

Benutzer folgen oder entfolgen

PATCH /api/users

Body:

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

Verfügbarkeit des Benutzernamens prüfen

GET /api/username/check

Abfrageparameter:

Einstellungen

GET /api/settings
POST /api/settings

Profil-Einstellungen des Benutzers abrufen oder aktualisieren (Anzeigename, Bio, soziale Links, etc.).

Profilsymbol

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

Profil-Avatar hochladen oder entfernen.

Onboarding

POST /api/onboarding

Onboarding-Prozess abschließen (Datenregion, Benutzername festlegen).

GDPR-API

Fordere einen Export aller deiner Daten an oder lösche dein Konto dauerhaft. Siehe Einstellungs-Dokumentation.

GDPR-Jobstatus abrufen

GET /api/gdpr

Abfrageparameter:

Gibt den Jobstatus zurück. Für abgeschlossene Export-Jobs enthält die Antwort eine downloadUrl.

Export- oder Lösch-Prozess starten

POST /api/gdpr

Body:

{
    "action": "export"
}

{
    "action": "delete",
    "confirmationWord": "DELETE"
}

Optional für Team-Arbeitsbereiche:

{
    "action": "delete",
    "confirmationWord": "DELETE",
    "teamUsername": "my-team"
}

Fehlercodes

Python-Integration

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

Installation & Einrichtung

pip install ultralytics

Installation überprüfen:

yolo check

Authentifizierung

yolo settings api_key=YOUR_API_KEY

Plattform-Datensätze verwenden

Referenziere Datensätze mit ul://-URIs:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

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

URI-Format:

Push zur Plattform

Sende Ergebnisse an ein Plattform-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 (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")

Führe Inferenz aus:

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, half=True)

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

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

Validierung:

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

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

Webhooks

Die Plattform verwendet interne Webhooks, um Echtzeit-Trainingsmetriken vom ultralytics Python SDK (das auf Cloud-GPUs oder entfernten/lokalen Maschinen läuft) zurück zur Plattform zu streamen – epochenweiser Loss, mAP, Systemstatistiken und Abschlussstatus. Diese Webhooks werden über den pro Trainingsauftrag bereitgestellten HMAC webhookSecret authentifiziert und sind nicht für die Nutzung durch Benutzeranwendungen vorgesehen.

FAQ

Wie paginiere ich große Ergebnisse?

Die meisten Endpunkte verwenden einen limit-Parameter, um zu steuern, wie viele Ergebnisse pro Anfrage zurückgegeben werden:

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

Die Aktivitäts- und Papierkorb-Endpunkte unterstützen zusätzlich einen page-Parameter für seitenbasierte Paginierung:

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

The Explore Search endpoint uses offset instead of page, with a fixed page size of 20:

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

Kann ich die API ohne SDK verwenden?

Ja, alle Funktionen sind über REST verfügbar. Das Python SDK ist ein Komfort-Wrapper, der Funktionen wie Echtzeit-Metrik-Streaming und automatische Modell-Uploads hinzufügt. Du kannst außerdem alle Endpunkte interaktiv unter platform.ultralytics.com/api/docs erkunden.

Gibt es API-Client-Bibliotheken?

Derzeit verwende das Ultralytics Python-Paket oder führe direkte HTTP-Anfragen aus. Offizielle Client-Bibliotheken für andere Sprachen sind geplant.

Wie gehe ich mit Ratenbegrenzungen um?

Verwende den Retry-After-Header aus der 429-Antwort, um die korrekte Zeitspanne zu warten:

import time

import requests

def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code != 429:
            return response
        wait = int(response.headers.get("Retry-After", 2**attempt))
        time.sleep(wait)
    raise Exception("Rate limit exceeded")

Wie finde ich meine Modell- oder Datensatz-ID?

Ressourcen-IDs werden zurückgegeben, wenn du Ressourcen über die API erstellst. Du findest sie auch in der Plattform-URL:

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

Verwende die Listen-Endpunkte, um nach Name zu suchen oder nach Projekt zu filtern.