REST API-Referenz
Ultralytics Platform bietet eine umfassende REST API für den programmatischen Zugriff auf Datensätze, Modelle, Trainings und Bereitstellungen.
Schnellstart
# List your datasets
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://platform.ultralytics.com/api/datasets
# Run inference on a model
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@image.jpg" \
https://platform.ultralytics.com/api/models/MODEL_ID/predict
Authentifizierung
Alle API-Anfragen erfordern eine Authentifizierung mittels API-Schlüssel.
API-Schlüssel abrufen
- Gehen Sie zu Einstellungen > API-Schlüssel
- Klicken Sie auf Schlüssel erstellen
- 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
Basis-URL
Alle API-Endpunkte verwenden:
https://platform.ultralytics.com/api
Ratenbegrenzungen
| Plan | Anfragen/Minute | Anfragen/Tag |
|---|---|---|
| Kostenlos | 60 | 1,000 |
| Pro | 300 | 50,000 |
| Enterprise | Benutzerdefiniert | Benutzerdefiniert |
Ratenbegrenzungs-Header sind in den Antworten enthalten:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1640000000
Antwortformat
Alle Antworten sind JSON:
{
"success": true,
"data": { ... },
"meta": {
"page": 1,
"limit": 20,
"total": 100
}
}
Fehlerantworten
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid dataset ID",
"details": { ... }
}
}
Datensätze API
Datensätze auflisten
GET /api/datasets
Abfrageparameter:
| Parameter | Typ | Beschreibung |
|---|---|---|
page | int | Seitennummer (Standard: 1) |
limit | int | Elemente pro Seite (Standard: 20) |
task | string | Nach Aufgabentyp filtern |
Antwort:
{
"success": true,
"data": [
{
"id": "dataset_abc123",
"name": "my-dataset",
"slug": "my-dataset",
"task": "detect",
"imageCount": 1000,
"classCount": 10,
"visibility": "private",
"createdAt": "2024-01-15T10:00:00Z"
}
]
}
Datensatz abrufen
GET /api/datasets/{datasetId}
Datensatz erstellen
POST /api/datasets
Body:
{
"name": "my-dataset",
"task": "detect",
"description": "A custom detection dataset"
}
Datensatz löschen
DELETE /api/datasets/{datasetId}
Datensatz exportieren
POST /api/datasets/{datasetId}/export
Gibt eine Download-URL im NDJSON-Format zurück.
Modelle anhand von Datensätzen trainieren
GET /api/datasets/{datasetId}/models
Gibt eine Liste der Modelle zurück, die mit diesem Datensatz trainiert wurden, und zeigt die Beziehung zwischen den Datensätzen und den daraus erstellten Modellen.
Antwort:
{
"success": true,
"data": [
{
"id": "model_abc123",
"name": "experiment-1",
"projectId": "project_xyz",
"trainedAt": "2024-01-15T10:00:00Z",
"metrics": {
"mAP50": 0.85,
"mAP50-95": 0.72
}
}
]
}
Projekte API
Projekte auflisten
GET /api/projects
Projekt abrufen
GET /api/projects/{projectId}
Projekt erstellen
POST /api/projects
Body:
{
"name": "my-project",
"description": "Detection experiments"
}
Projekt löschen
DELETE /api/projects/{projectId}
Modelle API
Modelle auflisten
GET /api/models
Abfrageparameter:
| Parameter | Typ | Beschreibung |
|---|---|---|
projectId | string | Nach Projekt filtern |
task | string | Nach Aufgabentyp filtern |
Modell abrufen
GET /api/models/{modelId}
Modell hochladen
POST /api/models
Multipart-Formular:
| Feld | Typ | Beschreibung |
|---|---|---|
file | Datei definiert | Modell-Datei (.pt) |
projectId | string | Zielprojekt |
name | string | Modellname |
Modell löschen
DELETE /api/models/{modelId}
Modell herunterladen
GET /api/models/{modelId}/files
Gibt signierte Download-URLs für Modelldateien zurück.
Inferenz ausführen
POST /api/models/{modelId}/predict
Multipart-Formular:
| Feld | Typ | Beschreibung |
|---|---|---|
file | Datei definiert | Bilddatei |
conf | float | Konfidenzschwelle |
iou | float | IoU-Schwelle |
Antwort:
{
"success": true,
"predictions": [
{
"class": "person",
"confidence": 0.92,
"box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
}
]
}
Training API
Training starten
POST /api/training/start
Body:
{
"modelId": "model_abc123",
"datasetId": "dataset_xyz789",
"epochs": 100,
"imageSize": 640,
"gpuType": "rtx-4090"
}
Trainingsstatus abrufen
GET /api/models/{modelId}/training
Training abbrechen
DELETE /api/models/{modelId}/training
Bereitstellungen API
Bereitstellungen auflisten
GET /api/deployments
Abfrageparameter:
| Parameter | Typ | Beschreibung |
|---|---|---|
modelId | string | Nach Modell filtern |
Bereitstellung erstellen
POST /api/deployments
Body:
{
"modelId": "model_abc123",
"region": "us-central1",
"minInstances": 0,
"maxInstances": 10
}
Bereitstellung abrufen
GET /api/deployments/{deploymentId}
Bereitstellung starten
POST /api/deployments/{deploymentId}/start
Bereitstellung stoppen
POST /api/deployments/{deploymentId}/stop
Bereitstellung löschen
DELETE /api/deployments/{deploymentId}
Metriken abrufen
GET /api/deployments/{deploymentId}/metrics
Protokolle abrufen
GET /api/deployments/{deploymentId}/logs
Abfrageparameter:
| Parameter | Typ | Beschreibung |
|---|---|---|
severity | string | INFO, WARNING, ERROR |
limit | int | Anzahl der Einträge |
Export API
Exporte auflisten
GET /api/exports
Export erstellen
POST /api/exports
Body:
{
"modelId": "model_abc123",
"format": "onnx"
}
Unterstützte Formate:
onnx, torchscript, openvino, tensorrt, coreml, tflite, saved_model, graphdef, paddle, ncnn, edgetpu, tfjs, mnn, rknn, imx, axelera, executorch
Exportstatus abrufen
GET /api/exports/{exportId}
Aktivitäts-API
tracken und verwalten Sie Aktivitätsereignisse für Ihr Konto.
Aktivitäten auflisten
GET /api/activity
Abfrageparameter:
| Parameter | Typ | Beschreibung |
|---|---|---|
startDate | string | Filter ab Datum (ISO) |
endDate | string | Filter bis Datum (ISO) |
search | string | In Ereignismeldungen suchen |
Ereignisse als gesehen markieren
POST /api/activity/mark-seen
Ereignisse archivieren
POST /api/activity/archive
Papierkorb-API
Verwalten Sie vorläufig gelöschte Ressourcen (30 Tage Aufbewahrungsfrist).
Papierkorb auflisten
GET /api/trash
Element wiederherstellen
POST /api/trash
Body:
{
"itemId": "item_abc123",
"type": "dataset"
}
Papierkorb leeren
POST /api/trash/empty
Löscht alle Elemente im Papierkorb dauerhaft.
Abrechnungs-API
Guthaben und Abonnements verwalten.
Guthaben abrufen
GET /api/billing/balance
Antwort:
{
"success": true,
"data": {
"cashBalance": 5000000,
"creditBalance": 20000000,
"reservedAmount": 0,
"totalBalance": 25000000
}
}
Micro-USD
Alle Beträge sind in Micro-USD (1.000.000 = 1,00 $) für eine präzise Abrechnung angegeben.
Nutzungsübersicht abrufen
GET /api/billing/usage-summary
Gibt Details zu Plänen, Limits und Nutzungsmetriken zurück.
Checkout-Sitzung erstellen
POST /api/billing/checkout-session
Body:
{
"amount": 25
}
Erstellt eine Stripe-Checkout-Sitzung für den Kauf von Guthaben (5–1000 $).
Abonnement-Checkout erstellen
POST /api/billing/subscription-checkout
Erstellt eine Stripe-Checkout-Sitzung für das Pro-Abonnement.
Portal-Sitzung erstellen
POST /api/billing/portal-session
Gibt die URL zum Stripe-Abrechnungsportal für die Abonnementverwaltung zurück.
Zahlungsverlauf abrufen
GET /api/billing/payments
Gibt eine Liste der Zahlungstransaktionen von Stripe zurück.
Speicher-API
Speicherinformationen abrufen
GET /api/storage
Antwort:
{
"success": true,
"data": {
"used": 1073741824,
"limit": 107374182400,
"percentage": 1.0
}
}
DSGVO-API
DSGVO-konforme Endpunkte für Datenexport und -löschung.
Kontodaten exportieren/löschen
POST /api/gdpr
Body:
{
"action": "export"
}
| Aktion | Beschreibung |
|---|---|
export | Alle Kontodaten herunterladen |
delete | Konto und alle Daten löschen |
Irreversible Aktion
Die Kontolöschung ist dauerhaft und kann nicht rückgängig gemacht werden. Alle Daten, Modelle und Bereitstellungen werden gelöscht.
API-Schlüssel-API
API-Schlüssel auflisten
GET /api/api-keys
API-Schlüssel erstellen
POST /api/api-keys
Body:
{
"name": "training-server",
"scopes": ["training", "models"]
}
API-Schlüssel löschen
DELETE /api/api-keys/{keyId}
Fehlercodes
| Code | Beschreibung |
|---|---|
UNAUTHORIZED | Ungültiger oder fehlender API-Schlüssel |
FORBIDDEN | Unzureichende Berechtigungen |
NOT_FOUND | Ressource nicht gefunden |
VALIDATION_ERROR | Ungültige Anfragedaten |
RATE_LIMITED | Zu viele Anfragen |
INTERNAL_ERROR | Serverfehler |
Python
Für eine einfachere Integration verwenden Sie das Ultralytics Python-Paket.
Installation & Einrichtung
pip install ultralytics
Installation überprüfen:
yolo check
Anforderung an die Paketversion
Die Plattform-Integration erfordert ultralytics>=8.4.0. Ältere Versionen funktionieren NICHT mit der Plattform.
Authentifizierung
Methode 1: CLI (empfohlen)
yolo settings api_key=YOUR_API_KEY
Methode 2: Umgebungsvariable
export ULTRALYTICS_API_KEY=YOUR_API_KEY
Methode 3: Im Code
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:
ul://{username}/{resource-type}/{name}
Examples:
ul://john/datasets/coco-custom # Dataset
ul://john/my-project # Project
ul://john/my-project/exp-1 # Specific model
ul://ultralytics/yolo26/yolo26n # Official model
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:
| Ereignis | Beschreibung |
|---|---|
training.started | Trainingsjob gestartet |
training.epoch | Epoche abgeschlossen |
training.completed | Training abgeschlossen |
training.failed | Training fehlgeschlagen |
export.completed | Export bereit |
Das Webhook-Setup ist in Enterprise-Plänen verfügbar.
FAQ
Wie paginiere ich große Ergebnisse?
Verwenden Sie page und limit Parameter:
GET /api/datasets?page=2 &
limit=50
Kann ich die API ohne ein SDK nutzen?
Ja, alle Funktionen sind über REST verfügbar. Das SDK ist ein Komfort-Wrapper.
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?
Implementieren Sie exponentielles Backoff:
import time
def api_request_with_retry(url, max_retries=3):
for attempt in range(max_retries):
response = requests.get(url)
if response.status_code != 429:
return response
wait = 2**attempt
time.sleep(wait)
raise Exception("Rate limit exceeded")
