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

Ressourcen-APIs wie Datensätze, Projekte, Modelle, Trainings, Exporte und Vorhersagen verwenden die Authentifizierung per API-Schlüssel. Öffentliche Endpunkte (die öffentliche Datensätze, Projekte und Modelle auflisten) unterstützen den anonymen Lesezugriff ohne Schlüssel. Kontobezogene Routen – darunter Aktivitäten, Einstellungen, Teams, Abrechnung und DSGVO-Abläufe – erfordern derzeit eine authentifizierte Browsersitzung und sind nicht über einen API-Schlüssel verfügbar.

API-Schlüssel abrufen

1. Gehen Sie zu Settings > API Keys
2. Klicken Sie 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 YOUR_API_KEY

Beispiel

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

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
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 YOUR_API_KEY" },
});
const data = await response.json();

Basis-URL

Alle API-Endpunkte verwenden:

https://platform.ultralytics.com/api

Ratenbegrenzungen

Die API wendet pro API-Schlüssel Ratenbegrenzungen an (Sliding-Window-Verfahren, auf Upstash Redis basierend), um vor Missbrauch zu schützen und gleichzeitig die legitime Nutzung uneingeschränkt zu ermöglichen. Anonymer Datenverkehr wird zusätzlich durch die Missbrauchsschutzmaßnahmen auf Plattformebene von Vercel geschützt.

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 hat einen unabhängigen Zähler pro API-Schlüssel. Zum Beispiel wirken sich 20 predict-Anfragen nicht auf Ihr Standardkontingent von 100 Anfragen/Min aus.

Dedizierte Endpunkte (Unbegrenzt)

Dedizierte Endpunkte sind nicht den API-Schlüssel-Ratenbeschränkungen unterworfen. Wenn Sie ein Modell auf einem dedizierten Endpunkt bereitstellen, werden Anfragen an diese Endpunkt-URL (z. B., https://predict-abc123.run.app/predict) werden direkt an Ihren dedizierten Dienst weitergeleitet, ohne dass die Plattform eine Ratenbegrenzung vornimmt. Da Sie für die Rechenleistung bezahlen, profitieren Sie vom Durchsatz Ihrer dedizierten Dienstkonfiguration und sind nicht an die Grenzen der gemeinsam genutzten API gebunden.

Antwortformat

Erfolgsreaktionen

Die Antworten geben JSON mit ressourcenspezifischen Feldern zurück:

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

Fehlerantworten

{
    "error": "Dataset not found"
}

Datensätze API

Beschriftete Bilddatensätze für das Training von YOLO-Modellen erstellen, durchsuchen und verwalten. Siehe Datensatz-Dokumentation.

Datensätze auflisten

GET /api/datasets

Abfrageparameter:

curl -H "Authorization: Bearer YOUR_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}

Body (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. Erfordert eine aktive Browser-Sitzung auf der Plattform – nicht über einen API-Schlüssel verfügbar.

Body (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 den neuesten Datenexport zurück.

Abfrageparameter:

Antwort:

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

Datensatzversion erstellen

POST /api/datasets/{datasetId}/export

Erstellen Sie einen neuen nummerierten Versions-Snapshot des Datensatzes. Nur für den Eigentümer. Die Version erfasst die aktuelle Bildanzahl, Klassenanzahl, Annotationsanzahl und Split-Verteilung und generiert und speichert dann einen unveränderlichen NDJSON-Export.

Anfrage-Textkörper:

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

Alle Felder sind optional. Die description Das Feld ist eine vom Benutzer angegebene Bezeichnung für die Version.

Antwort:

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

Update-Version Beschreibung

PATCH /api/datasets/{datasetId}/export

Die Beschreibung einer bestehenden Version aktualisieren. Nur für Eigentümer.

Anfrage-Textkörper:

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

Antwort:

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

Automatische Datensatz-Annotation

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 Job zur Datensatzaufnahme, um hochgeladene ZIP- oder TAR-Dateien zu verarbeiten, einschließlich .tar.gz und .tgz, die Bilder und Labels enthalten.

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]

Datensatzbilder

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] },
        { "classId": 1, "segments": [0.1, 0.2, 0.3, 0.2, 0.2, 0.4] }
    ]
}

Massenbildoperationen

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

Ordnen Sie Ihre Modelle in Projekten. Jedes Modell gehört zu einem Projekt. Siehe Dokumentation zu Projekten.

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

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

Kloniert ein öffentliches Projekt (mit allen darin enthaltenen Modellen) in Ihren Arbeitsbereich. Erfordert eine aktive Browser-Sitzung auf der Plattform – nicht über einen API-Schlüssel verfügbar.

Projekt-Symbol

Projekt-Symbol hochladen (mehrteiliges Formular mit Bilddatei):

POST /api/projects/{projectId}/icon

Entfernen Sie das Projektsymbol:

DELETE /api/projects/{projectId}/icon

Für beides ist eine aktive Browser-Sitzung auf der Plattform erforderlich – dies ist über einen API-Schlüssel nicht möglich.

Modelle API

Verwalten Sie trainierte YOLO – Metriken anzeigen, Gewichte herunterladen, Inferenz ausführen und in andere Formate exportieren. Siehe Dokumentation zu Modellen.

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}

Modell-Dateien herunterladen

GET /api/models/{modelId}/files

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

Modell klonen

POST /api/models/{modelId}/clone

Kopiere ein öffentliches Modell in eines deiner Projekte. Dazu ist eine aktive Browser-Sitzung auf der Plattform erforderlich – nicht über einen API-Schlüssel verfügbar.

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

Aufwärmmodell

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

Training API

Starten Sie YOLO auf Cloud-GPUs (23 GPU von RTX 2000 Ada bis B200) und verfolgen Sie den Fortschritt in Echtzeit. Weitere Informationen finden Sie in der Dokumentation zum Cloud-Training.

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

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": "yolo26n.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. Auf öffentliche Projekte kann anonym zugegriffen werden; für private Projekte ist eine aktive Browser-Sitzung auf der Plattform erforderlich (diese Route akzeptiert keine Authentifizierung per API-Schlüssel).

Training abbrechen

DELETE /api/models/{modelId}/training

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

Bereitstellungen API

Stellen Sie Modelle auf dedizierten Inferenz-Endpunkten bereit, einschließlich Zustandsprüfungen und Überwachung. Bei neuen Bereitstellungen wird standardmäßig „Scale-to-Zero“ verwendet, und die API akzeptiert einen optionalen resources Objekt. Siehe Dokumentation zu Endpunkten.

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 wie ONNX, TensorRT, CoreML und TFLite für die Edge-Bereitstellung konvertieren. Siehe Bereitstellungsdokumentation.

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

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

Zeige einen Feed mit den jüngsten Aktivitäten in deinem Konto an – Trainingsläufe, Uploads und mehr. Siehe Dokumentation zu „Aktivitäten“.

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

Gelöschte Elemente anzeigen und wiederherstellen. Nach 30 Tagen werden die Elemente endgültig gelöscht. Siehe Dokumentation zum Papierkorb.

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üfen Sie Ihr Guthaben, kaufen Sie Guthaben, sehen Sie den Transaktionsverlauf ein und konfigurieren Sie die automatische Aufladung. Siehe Abrechnungsdokumentation.

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 Kreditkauf.

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

Abonnement kündigen oder fortsetzen

DELETE /api/billing/subscription-checkout

Kündigt standardmäßig ein Pro-Abonnement zum Ende des Abrechnungszeitraums. Senden {"resume": true} um eine bereits geplante Stornierung vor Ablauf des Abrechnungszeitraums wieder in Kraft zu setzen.

Body:

{
    "resume": true
}

Automatische Aufladung

Guthaben automatisch hinzufügen, wenn der Saldo 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 Intent 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

Überprüfen Sie Ihre Speichernutzungsaufschlüsselung nach Kategorie (Datensätze, Modelle, Exporte) und sehen Sie Ihre größten Elemente.

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

API hochladen

Laden Sie Dateien mithilfe signierter URLs direkt in den Cloud-Speicher hoch, um schnelle und zuverlässige Übertragungen zu gewährleisten. Der Vorgang erfolgt in zwei Schritten: Rufen Sie zunächst eine signierte URL ab und laden Sie dann die Datei hoch. Weitere Informationen finden Sie in der Dokumentation zu „Data“.

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

Upload abschließen

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

Verwalten Sie Ihre API-Schlüssel für den programmgesteuerten Zugriff. Siehe Dokumentation zu API-Schlüsseln.

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

Team-Workspaces erstellen, Mitglieder einladen und Rollen für die Zusammenarbeit verwalten. Siehe Teams-Dokumentation.

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

Durchsuchen und entdecken Sie öffentliche Datensätze und Projekte, die von der Community geteilt werden. Siehe Dokumentation zu „Explore“.

Ö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

Verwalten Sie Ihr Profil, Ihre API-Schlüssel, Ihre Speichernutzung und Ihre Datenschutzeinstellungen. Siehe Dokumentation zu den Einstellungen.

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

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

DSGVO-API

Fordern Sie einen Export all Ihrer Daten an oder löschen Sie Ihr Konto endgültig. Siehe Dokumentation zu den Einstellungen.

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("yolo26n.pt")

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

URI-Format:

Auf die Plattform übertragen

Ergebnisse an ein Plattformprojekt 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)
• 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/datasets/my-dataset")

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

Webhooks

Die Plattform nutzt interne Webhooks, um Trainingsdaten in Echtzeit aus dem ultralytics Python (auf Cloud-GPUs oder Remote-/lokalen Rechnern) zurück an die Plattform – Verlust pro Epoch, mAP, Systemstatistiken und Abschlussstatus. Diese Webhooks werden über HMAC authentifiziert webhookSecret werden pro Trainingsauftrag bereitgestellt und sind nicht für die Nutzung durch Benutzeranwendungen vorgesehen.

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 YOUR_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 YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/activity?page=2&limit=20"

Der Endpunkt „Explore Search“ verwendet offset anstelle von page, mit 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 das Streaming von Metriken in Echtzeit und automatische Modell-Uploads bietet. Unter platform.ultralytics.com/api/docs können Sie außerdem alle Endpunkte interaktiv erkunden.

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 3 Monaten ✏️ Aktualisiert vor 5 Tagen

Kommentare