REST API-Referenz

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

# 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

Die meisten API-Anfragen erfordern eine Authentifizierung über einen API-Schlüssel. Öffentliche Endpunkte (Auflistung öffentlicher Datensätze, Projekte und Modelle) unterstützen den anonymen Lesezugriff ohne Schlüssel.

API-Schlüssel abrufen

1. Gehen Sie zu Settings > Profile (Abschnitt „API-Schlüssel“)
2. Klicken Create Key
3. Kopieren Sie den generierten Schlüssel

Detaillierte Anweisungen finden Sie unter API-Schlüssel.

Autorisierungs-Header

Fügen Sie Ihren API-Schlüssel in alle Anfragen ein:

Authorization: Bearer ul_your_api_key_here

Beispiel

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

import requests

headers = {"Authorization": "Bearer ul_abc123..."}
response = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers=headers,
)
data = response.json()

const response = await fetch("https://platform.ultralytics.com/api/datasets", {
  headers: { Authorization: "Bearer ul_abc123..." },
});
const data = await response.json();

Basis-URL

Alle API-Endpunkte verwenden:

https://platform.ultralytics.com/api

Ratenbegrenzungen

Die API verwendet ein zweistufiges System zur Begrenzung der Rate, um vor Missbrauch zu schützen und gleichzeitig die legitime Nutzung uneingeschränkt zu ermöglichen:

• Pro API-Schlüssel – Beschränkungen, die pro API-Schlüssel für authentifizierte Anfragen gelten
• Pro IP — 100 Anfragen/Minute pro IP-Adresse auf allen /api/* Pfade (gilt sowohl für authentifizierte als auch für nicht authentifizierte Anfragen)

Bei Drosselung gibt die API Folgendes zurück 429 mit Wiederholungsmetadaten:

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

Pro API-Schlüssel-Limits

Ratenbeschränkungen werden automatisch basierend auf dem aufgerufenen Endpunkt angewendet. Aufwändige Vorgänge unterliegen strengeren Beschränkungen, um Missbrauch zu verhindern, während für Standard-CRUD-Vorgänge großzügige Standardwerte gelten:

Jede Kategorie verfügt über einen unabhängigen Zähler pro API-Schlüssel. Wenn Sie beispielsweise 20 Vorhersageanfragen stellen, hat dies keinen Einfluss auf Ihr Standardkontingent von 100 Anfragen pro Minute.

Dedizierte Endpunkte (unbegrenzt)

Dedizierte Endpunkte sind nicht den API-Schlüssel-Ratenbeschränkungen unterworfenWenn Sie ein Modell auf einem dedizierten Endpunkt bereitstellen, werden Anfragen an diese Endpunkt-URL (z. B. https://predict-abc123.run.app/predict) gelangen direkt zu Ihrem dedizierten Dienst, ohne dass die Plattform die Geschwindigkeit begrenzt. Sie bezahlen für die Rechenleistung und erhalten daher unbegrenzten Durchsatz bis zur Skalierungskonfiguration Ihres Endpunkts.

Antwortformat

Erfolgsreaktionen

Die Antworten geben JSON mit ressourcenspezifischen Feldern zurück:

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

Fehlerantworten

{
    "error": "Invalid dataset ID"
}

Datensätze API

Verwalten Sie beschriftete Bildersammlungen für das Training von YOLO .

Datensätze auflisten

GET /api/datasets

Abfrageparameter:

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

import requests

resp = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 10},
)
for ds in resp.json()["datasets"]:
    print(f"{ds['name']}: {ds['imageCount']} images")

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

Datensatz abrufen

GET /api/datasets/{datasetId}

Gibt alle Details zum Datensatz zurück, einschließlich Metadaten, Klassennamen und Aufteilungszahlen.

Datensatz erstellen

POST /api/datasets

Body:

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

Datensatz aktualisieren

PATCH /api/datasets/{datasetId}

Körper (teilweise Aktualisierung):

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

Datensatz löschen

DELETE /api/datasets/{datasetId}

Löscht den Datensatz vorläufig (wird in den Papierkorb verschoben und kann 30 Tage lang wiederhergestellt werden).

Datensatz klonen

POST /api/datasets/{datasetId}/clone

Erstellt eine Kopie des Datensatzes mit allen Bildern und Beschriftungen. Es können nur öffentliche Datensätze geklont werden.

Körper (alle Felder optional):

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

Datensatz exportieren

GET /api/datasets/{datasetId}/export

Gibt eine JSON-Antwort mit einer signierten Download-URL für die Datensatz-Exportdatei zurück.

Antwort:

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

Klassenstatistik abrufen

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

Gibt die Klassenverteilung, die Standort-Heatmap und die Dimensionsstatistiken zurück. Die Ergebnisse werden bis zu 5 Minuten lang zwischengespeichert.

Antwort:

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

Modelle anhand von Datensätzen trainieren

GET /api/datasets/{datasetId}/models

Gibt Modelle zurück, die mit diesem Datensatz 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
}

Datensatz automatisch annotieren

POST /api/datasets/{datasetId}/predict

Führen Sie YOLO für Bilder im Datensatz durch, um Annotationen automatisch zu generieren. Verwendet ein ausgewähltes Modell, um Labels für nicht annotierte Bilder vorherzusagen.

Body:

Datensatzaufnahme

POST /api/datasets/ingest

Erstellen Sie einen Datensatz-Ingest-Job, um hochgeladene ZIP-Dateien mit Bildern und Beschriftungen zu verarbeiten.

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

Datensatz Bilder

Bilderliste

GET /api/datasets/{datasetId}/images

Abfrageparameter:

Signierte Bild-URLs abrufen

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

Erhalten Sie signierte URLs für eine Reihe von Bild-Hashes (zur Anzeige im Browser).

Bild löschen

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

Bildbeschriftungen abrufen

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

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

Bildbeschriftungen aktualisieren

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

Body:

{
    "labels": [{ "classId": 0, "bbox": [0.5, 0.5, 0.2, 0.3] }]
}

Massenbildbearbeitung

Verschieben Sie Bilder zwischen Teilungen (Train/Val/Test) innerhalb eines Datensatzes:

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

Bilder in großen Mengen löschen:

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

Projekte API

Verwalten Sie Trainingsarbeitsbereiche, in denen Modelle gruppiert sind.

Projekte auflisten

GET /api/projects

Abfrageparameter:

Projekt abrufen

GET /api/projects/{projectId}

Projekt erstellen

POST /api/projects

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

resp = requests.post(
    "https://platform.ultralytics.com/api/projects",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"name": "my-project", "slug": "my-project", "description": "Detection experiments"},
)
project_id = resp.json()["projectId"]

Projekt aktualisieren

PATCH /api/projects/{projectId}

Projekt löschen

DELETE /api/projects/{projectId}

Das Projekt wird vorläufig gelöscht (in den Papierkorb verschoben).

Projekt klonen

POST /api/projects/{projectId}/clone

Projekt-Symbol

Projekt-Symbol hochladen (mehrteiliges Formular mit Bilddatei):

POST /api/projects/{projectId}/icon

Entfernen Sie das Projektsymbol:

DELETE /api/projects/{projectId}/icon

Modelle API

Verwalten Sie Checkpoints für trainierte Modelle innerhalb von Projekten.

Modelle auflisten

GET /api/models

Abfrageparameter:

Liste der abgeschlossenen Modelle

GET /api/models/completed

Gibt Modelle zurück, deren Training abgeschlossen ist (zur Verwendung in Modellselektoren und bei der Bereitstellung).

Modell abrufen

GET /api/models/{modelId}

Modell erstellen

POST /api/models

JSON-Hauptteil:

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.

Klonmodell

POST /api/models/{modelId}/clone

Klonen Sie ein öffentliches Modell in eines Ihrer Projekte.

Body:

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

Track herunterladen

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

Analyse der Downloads von Track-Modellen.

Inferenz ausführen

POST /api/models/{modelId}/predict

Multipart-Formular:

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

with open("image.jpg", "rb") as f:
    resp = requests.post(
        f"https://platform.ultralytics.com/api/models/{model_id}/predict",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": f},
        data={"conf": 0.5},
    )
results = resp.json()["images"][0]["results"]

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

Predict-Token erhalten

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

Erhalten Sie ein kurzlebiges Token für direkte Vorhersageanfragen. Das Token umgeht den API-Proxy für eine Inferenz mit geringerer Latenz aus clientseitigen Anwendungen.

Aufwärmmodell

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

Laden Sie ein Modell vorab, um die erste Inferenz zu beschleunigen. Rufen Sie dies vor der Ausführung von Vorhersagen auf, um Verzögerungen bei der ersten Anfrage zu vermeiden.

Training API

Cloud-Schulungsaufträge starten, überwachen und abbrechen.

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 $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "MODEL_ID",
    "projectId": "PROJECT_ID",
    "gpuType": "rtx-4090",
    "trainArgs": {
      "model": "yolo11n.pt",
      "data": "ul://username/datasets/my-dataset",
      "epochs": 100,
      "imgsz": 640,
      "batch": 16
    }
  }' \
  https://platform.ultralytics.com/api/training/start

resp = requests.post(
    "https://platform.ultralytics.com/api/training/start",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "modelId": "MODEL_ID",
        "projectId": "PROJECT_ID",
        "gpuType": "rtx-4090",
        "trainArgs": {
            "model": "yolo11n.pt",
            "data": "ul://username/datasets/my-dataset",
            "epochs": 100,
            "imgsz": 640,
            "batch": 16,
        },
    },
)

Trainingsstatus abrufen

GET /api/models/{modelId}/training

Gibt den aktuellen Status, die Metriken und den Fortschritt des Trainingsauftrags für ein Modell zurück.

Training abbrechen

DELETE /api/models/{modelId}/training

Beendet die ausgeführte Recheninstanz und markiert den Auftrag als abgebrochen.

Bereitstellungen API

Erstellen und verwalten Sie dedizierte Inferenz-Endpunkte.

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]

Bereitstellungen auflisten

GET /api/deployments

Abfrageparameter:

Bereitstellung 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 über eine eindeutige URL global zugänglich.

Bereitstellung abrufen

GET /api/deployments/{deploymentId}

Bereitstellung löschen

DELETE /api/deployments/{deploymentId}

Bereitstellung starten

POST /api/deployments/{deploymentId}/start

Eine angehaltene Bereitstellung fortsetzen.

Bereitstellung stoppen

POST /api/deployments/{deploymentId}/stop

Eine laufende Bereitstellung pausieren (stoppt die Abrechnung).

Zustandsprüfung

GET /api/deployments/{deploymentId}/health

Gibt den Gesundheitszustand des Bereitstellungsendpunkts zurück.

Inferenz bei Bereitstellung ausführen

POST /api/deployments/{deploymentId}/predict

Senden Sie ein Bild direkt an einen Bereitstellungsendpunkt zur Inferenz. Funktional gleichwertig mit der Modellvorhersage, jedoch über den dedizierten Endpunkt geleitet, um die Latenz zu verringern.

Multipart-Formular:

Metriken abrufen

GET /api/deployments/{deploymentId}/metrics

Gibt Metriken zu Anfragen, Latenz und Fehlerquote mit Sparkline-Daten zurück.

Abfrageparameter:

Protokolle abrufen

GET /api/deployments/{deploymentId}/logs

Abfrageparameter:

Überwachungs-API

Aggregierte Metriken

GET /api/monitoring

Gibt aggregierte Metriken für alle Benutzerbereitstellungen zurück: Gesamtanzahl der Anfragen, aktive Bereitstellungen, Fehlerquote und durchschnittliche Latenz.

Export API

Modelle in optimierte Formate für den Einsatz am Rand konvertieren.

Exporte auflisten

GET /api/exports

Abfrageparameter:

Export erstellen

POST /api/exports

Body:

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

resp = requests.post(
    "https://platform.ultralytics.com/api/exports",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"modelId": "MODEL_ID", "format": "onnx"},
)
export_id = resp.json()["exportId"]

Unterstützte Formate:

Exportstatus abrufen

GET /api/exports/{exportId}

Export abbrechen

DELETE /api/exports/{exportId}

Track-Export herunterladen

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

Aktivitäts-API

tracken und verwalten Sie Aktivitätsereignisse für Ihr Konto.

Aktivitäten auflisten

GET /api/activity

Abfrageparameter:

Ereignisse als gesehen markieren

POST /api/activity/mark-seen

Body:

{
    "all": true
}

Oder bestimmte IDs übergeben:

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

Ereignisse archivieren

POST /api/activity/archive

Body:

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

Oder bestimmte IDs übergeben:

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

Papierkorb-API

Verwalten Sie vorläufig gelöschte Ressourcen (30 Tage Aufbewahrungsfrist).

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

Verwalten Sie Guthaben, Abonnements und Zahlungsmethoden.

Guthaben abrufen

GET /api/billing/balance

Abfrageparameter:

Antwort:

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

Nutzungsübersicht abrufen

GET /api/billing/usage-summary

Gibt Details zu Plänen, Limits und Nutzungsmetriken zurück.

Transaktionen abrufen

GET /api/billing/transactions

Gibt die Transaktionshistorie zurück (die aktuellste zuerst).

Abfrageparameter:

Checkout-Sitzung erstellen

POST /api/billing/checkout-session

Body:

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

Erstellt eine Checkout-Sitzung für den Kauf auf Kredit.

Abonnement-Checkout erstellen

POST /api/billing/subscription-checkout

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

Body:

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

Portal-Sitzung erstellen

POST /api/billing/portal-session

Gibt die URL zum Abrechnungsportal für die Abonnementverwaltung zurück.

Automatische Aufladung

Fügen Sie automatisch Guthaben hinzu, wenn der Kontostand unter einen Schwellenwert fällt.

Automatische Aufladung konfigurieren

GET /api/billing/auto-topup

Abfrageparameter:

Konfiguration für automatische Aufladung aktualisieren

PATCH /api/billing/auto-topup

Body:

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

Zahlungsmethoden

Zahlungsmethoden auflisten

GET /api/billing/payment-methods

Setup-Absicht erstellen

POST /api/billing/payment-methods/setup

Gibt einen geheimen Client-Schlüssel zum Hinzufügen einer neuen Zahlungsmethode zurück.

Standardzahlungsmethode festlegen

POST /api/billing/payment-methods/default

Body:

{
    "paymentMethodId": "pm_123"
}

Zahlungsdaten 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

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

Speicher neu berechnen

POST /api/storage

Löst eine Neuberechnung der Speichernutzung aus.

API hochladen

Direkte Datei-Uploads verwenden einen zweistufigen signierten URL-Ablauf.

Signierte Upload-URL abrufen

POST /api/upload/signed-url

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

Vollständiger Upload

POST /api/upload/complete

Benachrichtigen Sie die Plattform, dass der Datei-Upload abgeschlossen ist, damit sie mit der 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

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 $API_KEY" \
  "https://platform.ultralytics.com/api/api-keys?keyId=KEY_ID"

Teams & Mitglieder API

Verwalten Sie die Zusammenarbeit im Arbeitsbereich mit Teams, Mitgliedern und Einladungen.

Teams auflisten

GET /api/teams

Team erstellen

POST /api/teams/create

Body:

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

Mitgliederliste

GET /api/members

Gibt die 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}

Eigentumsübertragung

POST /api/members/transfer-ownership

Einladungen

Einladung annehmen

POST /api/invites/accept

Einladungsinformationen erhalten

GET /api/invites/info

Abfrageparameter:

Einladung widerrufen

DELETE /api/invites/{inviteId}

Einladung erneut senden

POST /api/invites/{inviteId}/resend

API erkunden

Öffentliche Inhalte suchen

GET /api/explore/search

Abfrageparameter:

Seitenleiste Daten

GET /api/explore/sidebar

Gibt kuratierte Inhalte für die Seitenleiste „Entdecken“ zurück.

Benutzer- und Einstellungs-APIs

Benutzer nach Benutzername suchen

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

Benutzerprofileinstellungen abrufen oder aktualisieren (Anzeigename, Biografie, Links zu sozialen Netzwerken usw.).

Profil-Symbol

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

Profil-Avatar hochladen oder entfernen.

Einarbeitung

POST /api/onboarding

Vollständiger Onboarding-Prozess (Datenregion und Benutzername festlegen).

DSGVO-API

DSGVO-konforme Endpunkte für Datenexport und -löschung.

GDPR-Jobstatus abrufen

GET /api/gdpr

Abfrageparameter:

Gibt den Auftragsstatus zurück. Bei abgeschlossenen Exportaufträgen enthält die Antwort einen downloadUrl.

Export starten oder Ablauf löschen

POST /api/gdpr

Body:

{
    "action": "export"
}

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

Optional für Team-Arbeitsbereiche:

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

Fehlercodes

Python

Verwenden Sie für eine einfachere Integration das Ultralytics Python , das die Authentifizierung, Uploads und das Streaming von Echtzeitmetriken automatisch übernimmt.

Installation & Einrichtung

pip install ultralytics

Installation überprüfen:

yolo check

Authentifizierung

yolo settings api_key=YOUR_API_KEY

export ULTRALYTICS_API_KEY=YOUR_API_KEY

from ultralytics import settings

settings.api_key = "YOUR_API_KEY"

Nutzung von Plattform-Datensätzen

Referenzdatensätze mit ul:// URIs:

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

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

URI-Format:

Auf die Plattform übertragen

Ergebnisse an ein Plattformprojekt senden:

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

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

Was synchronisiert wird:

• Trainingsmetriken (Echtzeit)
• Gewichte des endgültigen Modells
• Validierungsdiagramme
• Konsolenausgabe
• Systemmetriken

API-Beispiele

Laden Sie 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

Exportmodell:

# 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/my-dataset")

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

Webhooks

Webhooks benachrichtigen Ihren Server über Plattformereignisse mittels HTTP-POST-Callbacks:

FAQ

Wie paginiere ich große Ergebnisse?

Die meisten Endpunkte verwenden ein limit Parameter zur Steuerung der Anzahl der pro Anfrage zurückgegebenen Ergebnisse:

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

Die Endpunkte „Activity“ und „Trash“ unterstützen ebenfalls ein page Parameter für seitenbasierte Paginierung:

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

Der Endpunkt „Explore Search“ verwendet offset anstelle von pagemit einer festen Seitengröße von 20:

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

Kann ich die API ohne ein SDK nutzen?

Ja, alle Funktionen sind über REST verfügbar. Das Python ist ein praktischer Wrapper, der Funktionen wie Echtzeit-Metrik-Streaming und automatische Modell-Uploads hinzufügt.

Gibt es API-Client-Bibliotheken?

Derzeit verwenden Sie das Ultralytics Python-Paket oder stellen direkte HTTP-Anfragen. Offizielle Client-Bibliotheken für andere Sprachen sind geplant.

Wie gehe ich mit Ratenbegrenzungen um?

Verwenden Sie den Retry-After Header aus der 429-Antwort, um die richtige Zeit 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 Sie Ressourcen über die API erstellen. Sie finden sie auch in der Plattform-URL:

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

Verwenden Sie die Listenendpunkte, um nach Namen zu suchen oder nach Projekten zu filtern.

📅 Erstellt vor 1 Monat ✏️ Aktualisiert vor 5 Tagen

Kommentare