Ultralytics YOLO27:

API-Schlüssel#

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

Registerkarte „API-Schlüssel“ mit Schlüsselliste in den Einstellungen der Ultralytics Platform

Nur für Eigentümer

Nur der Workspace-Inhaber kann Ultralytics-API-Schlüssel für den Arbeitsbereich erstellen, anzeigen oder widerrufen, da diese Schlüssel sich als Workspace-Inhaber authentifizieren. Andere Mitglieder können diese Schlüsseliste nicht einsehen. Sie können den Status von Verbindungen externer Anbieter sehen, jedoch keine vollständigen Anbieterschlüssel anzeigen oder diese Verbindungen ändern. API-Schlüssel selbst können keine anderen API-Schlüssel erstellen oder widerrufen. Die einzige Ausnahme sind On-Premise-Worker-Schlüssel, die durch das Trennen des Hosts von der On-Premise-Integration widerrufen werden.

API-Schlüssel erstellen#

Erstelle einen neuen API-Schlüssel:

  1. Gehe zu Einstellungen > API-Schlüssel
  2. Klicke auf Schlüssel hinzufügen und wähle Ultralytics als Anbieter aus.
  3. Gib einen Namen für den Schlüssel ein (z. B. „Trainingsserver“)
  4. Klicke auf Schlüssel erstellen

Dialog zum Erstellen eines API-Schlüssels in der Registerkarte „API-Schlüssel“ der Einstellungen der Ultralytics Platform

Schlüsselname#

Gib deinem Schlüssel einen aussagekräftigen Namen:

  • training-server – Für Rechner zum Remote-Training
  • 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:

Dialog zum Kopieren eines erstellten API-Schlüssels in der Registerkarte „API-Schlüssel“ der Einstellungen der Ultralytics Platform

Schlüssel kopieren

Kopiere deinen Schlüssel nach der Erstellung zum einfachen Nachschlagen. Du kannst auch jederzeit die Kopierschaltfläche in der Schlüsselliste verwenden; die Liste zeigt nur das Präfix jedes Schlüssels an.

Anbieterschlüssel für Agenten#

Dieselbe Registerkarte Einstellungen > API-Schlüssel speichert auch Schlüssel für externe Modell-Anbieter, die von Agenten verwendet werden. Nur der Workspace-Inhaber kann diese Schlüssel hinzufügen, ersetzen oder entfernen; Teammitglieder können sehen, welche Anbieter verbunden sind. Bitte den Inhaber, einen fehlenden Anbieter zu verbinden. Um einen Anbieter als Inhaber zu verbinden:

  1. Klicke auf Schlüssel hinzufügen.
  2. Wähle den Anbieter aus, der zum Sprach- oder Vision-Language-Modell deines Workflows passt.
  3. Füge den API-Schlüssel dieses Anbieters in API-Schlüssel ein und klicke dann auf Schlüssel speichern. Der Link Einen API-Schlüssel erhalten im Dialogfeld öffnet die Schlüsselseite des Anbieters.

Ein Ultralytics-Schlüssel authentifiziert keine externen Modell-Anbieter. Die Nutzung von Anbietern wird über das mit dem gespeicherten Schlüssel verknüpfte Anbieterkonto abgerechnet. Verwende das Bearbeitungssteuerelement der Schlüsselzeile, um einen Anbieterschlüssel zu ersetzen.

Dialogfeld zum Hinzufügen eines API-Schlüssels auf der Ultralytics Platform mit ausgewähltem Google Gemini als Anbieter

Schlüsselformat#

API-Schlüssel haben das folgende Format:

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4
  • Präfix: ul_ kennzeichnet Ultralytics-Schlüssel
  • Inhalt: 40 zufällige hexadezimale Zeichen
  • Gesamt: 43 Zeichen

Schlüsselsicherheit#

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

API-Schlüssel verwenden#

Umgebungsvariable#

Lege deinen Schlüssel als Umgebungsvariable fest:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

Validiere und speichere den Schlüssel mit dem YOLO CLI unter Python>=3.11:

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 dem Python SDK (pip install "ultralytics-platform>=0.1.45"), das ULTRALYTICS_API_KEY oder den von yolo login gespeicherten Schlüssel liest, wenn api_key weggelassen wird:

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

Alle verfügbaren Endpunkte findest du in der REST API-Referenz.

Remote-Training#

Aktiviere das Streaming von Metriken mit deinem Schlüssel.

Installiere oder aktualisiere das Ultralytics-Paket unter Python>=3.11 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

Eine vollständige Anleitung für das Remote-Training findest du unter Cloud-Training.

Schlüssel verwalten#

Schlüssel anzeigen#

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

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 kompromittierten oder nicht mehr benötigten Schlüssel:

  1. Suche den Schlüssel im Abschnitt „API-Schlüssel“
  2. Klicke auf die Schaltfläche Widerrufen (Papierkorb)
  3. Bestätige den Widerruf
Sofortige Wirkung

Der Widerruf erfolgt sofort und dauerhaft – der Schlüsseleintrag wird gelöscht und nicht deaktiviert. Alle Anwendungen, die den Schlüssel verwenden, werden nicht mehr funktionieren.

Schlüssel neu erstellen#

Wenn ein Schlüssel kompromittiert wurde:

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

API-Schlüssel eines Workspace#

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

  • Persönlicher Workspace: Schlüssel authentifizieren dein persönliches Konto
  • Team-Workspace: Schlüssel authentifizieren den Eigentümer des Team-Workspace und verfügen über vollständige Eigentümerberechtigungen in diesem Workspace

Beim Wechseln des Workspace in der Seitenleiste zeigt der Abschnitt „API-Schlüssel“ die Schlüssel für diesen Workspace an. Da ein Workspace-Schlüssel Eigentümerberechtigungen besitzt, kann nur der Workspace-Eigentümer ihn erstellen, anzeigen oder widerrufen. Einzelheiten zu den Rollen findest du unter Teams.

On Premise-Worker-Schlüssel#

Beim Verbinden eines On Premise-Hosts wird ein separater Worker-Schlüssel erstellt. Worker-Schlüssel werden über die On Premise-Integration und nicht über diese Registerkarte verwaltet, niemals zusammen mit deinen API-Schlüsseln aufgelistet und durch Trennen des Hosts widerrufen – dabei werden auch die für diesen Host eingereihten und laufenden Aufträge abgebrochen.

Bewährte Sicherheitspraktiken#

Empfohlen#

  • Speichere Schlüssel in Umgebungsvariablen
  • Verwende separate Schlüssel für verschiedene Umgebungen
  • Widerrufe nicht verwendete Schlüssel umgehend
  • Tausche Schlüssel regelmäßig aus
  • Verwende aussagekräftige Namen, um den Zweck der Schlüssel zu kennzeichnen

Nicht empfohlen#

  • Übernimm Schlüssel nicht in die Versionsverwaltung
  • Verwende Schlüssel nicht gemeinsam für mehrere Anwendungen
  • Schreibe Schlüssel nicht in die Anwendungsausgabe
  • Bette Schlüssel nicht in clientseitigen Code ein

Schlüsselaustausch#

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

  1. Erstelle einen neuen Schlüssel mit demselben Namen
  2. Aktualisiere die Anwendungen, sodass sie den neuen Schlüssel verwenden
  3. Überprüfe, dass die Anwendungen ordnungsgemäß funktionieren
  4. Widerrufe den alten Schlüssel
Austauschintervall

Erwäge bei sensiblen Anwendungen, die Schlüssel alle 90 Tage auszutauschen.

Fehlerbehebung#

Fehler wegen ungültigem 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. Überprüfe, ob der Schlüssel nicht widerrufen wurde
  3. Bestätige, dass die Umgebungsvariable festgelegt ist
  4. Stelle sicher, dass du Python>=3.11 und ultralytics>=8.4.120 verwendest.

Zugriff verweigert#

Error: Permission denied for this operation

Lösungen:

  1. Überprüfe, ob du Eigentümer der Ressource bist oder über den entsprechenden Workspace-Zugriff verfügst
  2. Überprüfe, ob der Schlüssel zum richtigen Workspace gehört
  3. Wenn du Schlüssel in einem Team-Workspace verwaltest, bestätige, dass du der Workspace-Eigentümer bist – andere Rollen erhalten Workspace owner access required
  4. Erstelle bei Bedarf einen neuen Schlüssel

Ratenbegrenzung erreicht#

Error: Rate limit exceeded

Lösungen:

  1. Verringere die Anfragehäufigkeit – die Limits pro Kategorie findest du in der Tabelle zur Ratenbegrenzung
  2. Implementiere ein exponentielles Backoff-Verfahren mithilfe des Headers Retry-After
  3. Verwende einen dedizierten Endpunkt, wenn du isolierte Inferenzkapazität benötigst

FAQ#

  • Für API-Schlüssel gibt es kein festes Limit. Erstelle so viele, wie du für verschiedene Anwendungen und Umgebungen benötigst.

  • Schlüssel laufen nicht automatisch ab. Sie bleiben gültig, bis sie widerrufen werden. Erwäge aus Sicherheitsgründen, eine regelmäßige Erneuerung zu implementieren.

  • Ja, die vollständigen Schlüsselwerte sind in der Schlüsselliste unter Settings > API Keys sichtbar. Die Plattform entschlüsselt deine Schlüssel und zeigt sie an, damit du sie jederzeit kopieren kannst.

  • Schlüssel funktionieren regionsübergreifend, greifen aber nur auf Daten in der Region deines Kontos zu.

  • Nein — ein Schlüssel eines Team-Arbeitsbereichs authentifiziert dich als Besitzer des Arbeitsbereichs. Daher kann nur der Besitzer einen solchen Schlüssel erstellen oder anzeigen, und durch das Teilen werden Besitzerberechtigungen übertragen. Lass stattdessen jedes Mitglied einen Schlüssel in seinem eigenen persönlichen Arbeitsbereich erstellen und den Besitzer einen dedizierten Schlüssel des Arbeitsbereichs für gemeinsam genutzte Automatisierungen wie CI erstellen.

  • Nein. Ein Schlüssel gehört zu dem Arbeitsbereich, in dem er erstellt wurde, und ermöglicht nur den Zugriff auf die Ressourcen dieses Arbeitsbereichs. Erstelle für jeden Arbeitsbereich, den du automatisierst, einen eigenen Schlüssel.

Mitwirkende
GLglenn-jocher17RAraimbekovm2SEsergiuwaxmann2LAlaodouya1MYmykolaxboiko1LALaughing-q1

Kommentare