API-Schlüssel#

Ultralytics Platform API-Schlüssel ermöglichen einen sicheren programmatischen Zugriff für Remote-Training, Inferenz und Automatisierung. Erstelle benannte Schlüssel mit AES-256-GCM-Verschlüsselung für verschiedene Anwendungsfälle.

API-Key erstellen#

Erstelle einen neuen API-Schlüssel:

1. Gehe zu Einstellungen > API-Schlüssel
2. Klicke auf Schlüssel erstellen
3. Gib einen Namen für den Schlüssel ein (z. B. "Training Server")
4. Klicke auf Schlüssel erstellen

Schlüsselname#

Gib deinem Schlüssel einen beschreibenden Namen:

• training-server - Für Remote-Training-Maschinen
• ci-pipeline - Für die CI/CD-Integration
• local-dev - Für die lokale Entwicklung

Schlüsselanzeige#

Nach der Erstellung wird der Schlüssel in einem Bestätigungsdialog angezeigt:

Schlüsselformat#

API-Schlüssel folgen diesem Format:

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

• Präfix: ul_ identifiziert Ultralytics-Schlüssel
• Körper: 40 zufällige hexadezimale Zeichen
• Gesamt: 43 Zeichen

Schlüsselsicherheit#

• Schlüssel werden mit AES-256-GCM encryption gespeichert, niemals im Klartext
• Die ersten 11 Zeichen (ul_ plus 8 Hexadezimalzeichen) dienen als Anzeigepräfix, sodass ein Schlüssel identifiziert werden kann, ohne ihn preiszugeben

Verwendung von API-Schlüsseln#

Umgebungsvariable#

Setze deinen Schlüssel als Umgebungsvariable:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

Validiere und speichere den Key mit der YOLO CLI:

yolo login YOUR_API_KEY

Entferne den gespeicherten Schlüssel mit yolo logout.

HTTP-Header#

Füge den Schlüssel in API-Anfragen ein:

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

Oder übergib ihn an das Python SDK (pip install "ultralytics-platform>=0.1.5"), das auch ULTRALYTICS_API_KEY liest:

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

Siehe die REST API Reference für alle verfügbaren Endpunkte.

Remote-Training#

Aktiviere das Metrik-Streaming mit deinem Schlüssel.

Installiere oder aktualisiere das Ultralytics-Paket vor dem Start:

pip install -U ultralytics

export ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1

Siehe Cloud Training für die vollständige Anleitung zum Remote-Training.

Schlüssel verwalten#

Schlüssel anzeigen#

Alle Schlüssel werden auf der Registerkarte Settings > API Keys aufgelistet:

Jede Schlüsselkarte zeigt den Schlüsselnamen, den kopierbaren Schlüsselwert, den relativen Erstellungszeitpunkt und eine Schaltfläche zum Widerrufen.

Schlüssel widerrufen#

Widerrufe einen Schlüssel, der kompromittiert wurde oder nicht mehr benötigt wird:

1. Finde den Schlüssel im Bereich API-Schlüssel
2. Klicke auf die Schaltfläche Widerrufen (Papierkorb)
3. Bestätige den Widerruf

Schlüssel neu generieren#

Falls ein Schlüssel kompromittiert wurde:

1. Erstelle einen neuen Schlüssel mit demselben Namen
2. Aktualisiere deine Anwendungen
3. Widerrufe den alten Schlüssel

Workspace API-Schlüssel#

API-Schlüssel sind auf den aktuell aktiven Workspace beschränkt:

• Persönlicher Workspace: Schlüssel authentifizieren sich als dein persönliches Konto
• Team-Workspace: Schlüssel authentifizieren sich als Inhaber des Team-Workspaces mit vollen Inhaberberechtigungen in diesem Workspace

Wenn du Workspaces in der Seitenleiste wechselst, zeigt der Bereich „API Keys“ die Schlüssel für diesen Workspace an. Da ein Workspace-Schlüssel Inhaberberechtigungen besitzt, kann nur der Workspace-Inhaber einen solchen erstellen, anzeigen oder widerrufen. Siehe Teams für Details zu den Rollen.

On Premise Worker Keys#

Das Verbinden eines On Premise-Hosts generiert einen separaten Worker-Schlüssel. Worker-Schlüssel werden über die On Premise-Integration statt über diese Registerkarte verwaltet, werden niemals zusammen mit deinen API-Schlüsseln aufgelistet und werden durch das Trennen des Hosts widerrufen – wodurch auch die in der Warteschlange befindlichen und laufenden Jobs dieses Hosts abgebrochen werden.

Best Practices für die Sicherheit#

Was du tun solltest#

• Speichere Schlüssel in Umgebungsvariablen
• Verwende separate Schlüssel für verschiedene Umgebungen
• Widerrufe ungenutzte Schlüssel zeitnah
• Rotiere Schlüssel regelmäßig
• Verwende beschreibende Namen, um die Zwecke der Schlüssel zu identifizieren

Was du nicht tun solltest#

• Vermeide das Committen von Schlüsseln in die Versionskontrolle
• Vermeide das Teilen von Schlüsseln zwischen Anwendungen
• Vermeide das Protokollieren von Schlüsseln in der Anwendungsausgabe
• Vermeide das Einbetten von Schlüsseln in clientseitigen Code

Schlüsselrotation#

Rotiere Schlüssel regelmäßig aus Sicherheitsgründen:

1. Erstelle einen neuen Schlüssel mit demselben Namen
2. Aktualisiere Anwendungen, um den neuen Schlüssel zu verwenden
3. Überprüfe, ob die Anwendungen korrekt funktionieren
4. Widerrufe den alten Schlüssel

Fehlerbehebung#

Fehler: Ungültiger Schlüssel#

Error: Invalid API key

Lösungen:

1. Überprüfe, ob der Schlüssel korrekt kopiert wurde (einschließlich des Präfixes ul_)
2. Prüfe, ob der Schlüssel widerrufen wurde
3. Bestätige, dass die Umgebungsvariable gesetzt ist
4. Stelle sicher, dass du ultralytics>=8.4.120 verwendest

Zugriff verweigert#

Error: Permission denied for this operation

Lösungen:

1. Überprüfe, ob du der Eigentümer der Ressource bist oder den entsprechenden Workspace-Zugriff hast
2. Prüfe, ob der Schlüssel zum richtigen Workspace gehört
3. Wenn du Schlüssel in einem Team-Workspace verwist, vergewissere dich, dass du der Workspace-Inhaber bist – andere Rollen erhalten Workspace owner access required
4. Erstelle bei Bedarf einen neuen Schlüssel

Ratenbegrenzung#

Error: Rate limit exceeded

Lösungen:

1. Reduziere die Anforderungshäufigkeit – siehe die rate limit table für Limits pro Kategorie
2. Implementiere exponentielles Backoff unter Verwendung des Headers Retry-After
3. Verwende einen dedicated endpoint, wenn du isolierte Inferenzkapazität benötigst

FAQ#