Ultralytics YOLO27:
Get Started

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.

Einstellungen der Ultralytics Platform: Registerkarte „API-Schlüssel“, Schlüsselliste

Nur für den Besitzer

Nur der Besitzer des Arbeitsbereichs kann Ultralytics API-Schlüssel für den Arbeitsbereich erstellen, anzeigen oder widerrufen, da diese Schlüssel den Besitzer des Arbeitsbereichs authentifizieren. Andere Mitglieder können die Schlüsselliste nicht sehen. Sie können den Verbindungsstatus externer Anbieter sehen, aber weder vollständige Anbieterschlüssel anzeigen noch 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 Trennen des Hosts von der On Premise-Integration widerrufen werden.

API-Schlüssel erstellen#

So erstellst du 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

Einstellungen der Ultralytics Platform: Registerkarte „API-Schlüssel“, Dialogfeld zum Erstellen eines API-Schlüssels

Schlüsselname#

Gib deinem Schlüssel einen aussagekräftigen Namen:

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

Schlüsselanzeige#

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

Einstellungen der Ultralytics Platform: Registerkarte „API-Schlüssel“, Dialogfeld zum Kopieren eines erstellten API-Schlüssels

Schlüssel kopieren

Kopiere deinen Schlüssel nach dem Erstellen, damit du ihn leicht zur Hand hast. Du kannst auch jederzeit die Schaltfläche zum Kopieren in der Schlüsselliste verwenden; dort wird nur das Präfix jedes Schlüssels angezeigt.

Anbieterschlüssel für Agents und Annotation#

Auf derselben Registerkarte Einstellungen > API-Schlüssel kannst du auch Schlüssel für externe Modellanbieter speichern, die von Agents und den kostenpflichtigen Modellen für die Annotation mit Klassenprompt verwendet werden. Bei der Annotation wird der im Arbeitsbereich des Datensatzes gespeicherte Schlüssel verwendet. Nur der Besitzer des Arbeitsbereichs kann diese Schlüssel hinzufügen, ersetzen oder entfernen; Teammitglieder können sehen, mit welchen Anbietern eine Verbindung besteht. Bitte den Besitzer, einen fehlenden Anbieter zu verbinden. So verbindest du als Besitzer einen Anbieter:

  1. Klicke auf Schlüssel hinzufügen.
  2. Wähle den Anbieter aus, der zur Sprache oder zum Vision-Language-Modell deines Workflows oder zum gewünschten Annotationsmodell passt.
  3. Füge den API-Schlüssel des Anbieters in das Feld API-Schlüssel ein und klicke dann auf Schlüssel speichern. Über den Link API-Schlüssel abrufen im Dialogfeld gelangst du zur Schlüsselseite des Anbieters.

Ein Ultralytics-Schlüssel authentifiziert dich nicht bei externen Modellanbietern. Die Nutzung des Anbieters wird über das Anbieter-Konto abgerechnet, das mit dem gespeicherten Schlüssel verknüpft ist. Verwende die Bearbeitungsoption in der Schlüsselzeile, um einen Anbieterschlüssel zu ersetzen.

Dialogfeld „API-Schlüssel hinzufügen“ der Ultralytics Platform mit Google Gemini als ausgewähltem Anbieter

Schlüsselformat#

API-Schlüssel haben folgendes Format:

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4
  • Präfix: ul_ kennzeichnet Ultralytics-Schlüssel
  • Schlüsselinhalt: 40 zufällige hexadezimale Zeichen
  • Gesamtlänge: 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, damit sich ein Schlüssel erkennen lässt, ohne ihn offenzulegen

API-Schlüssel verwenden#

Umgebungsvariable#

Lege deinen Schlüssel als Umgebungsvariable fest:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

Prüfe und speichere den Schlüssel mit der 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/...

Du kannst ihn auch an das Python SDK (pip install "ultralytics-platform>=0.1.45") übergeben. Wenn api_key nicht angegeben ist, liest es ULTRALYTICS_API_KEY oder den mit yolo login gespeicherten Schlüssel:

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 mit deinem Schlüssel das Streaming von Metriken.

Installiere oder aktualisiere vor dem Start das Ultralytics-Paket unter Python>=3.11:

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 zum Remote-Training findest du unter Cloud-Training.

Schlüssel verwalten#

Schlüssel anzeigen#

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

In jeder Schlüsselzeile werden der Schlüsselname, das Schlüsselpräfix, das Erstellungsdatum, eine Schaltfläche zum Kopieren des vollständigen Schlüssels und eine Schaltfläche zum Entfernen (Papierkorb) angezeigt.

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 zum Entfernen (Papierkorb)
  3. Klicke zur Bestätigung auf Schlüssel entfernen
Sofortige Wirkung

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

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 für Arbeitsbereiche#

API-Schlüssel gelten für den aktuell aktiven Arbeitsbereich:

  • Persönlicher Arbeitsbereich: Schlüssel authentifizieren dich als dein persönliches Konto
  • Team-Arbeitsbereich: Schlüssel authentifizieren dich als Besitzer des Team-Arbeitsbereichs und gewähren vollständige Besitzerberechtigungen in diesem Arbeitsbereich

Wenn du in der Seitenleiste zwischen Arbeitsbereichen wechselst, zeigt der Abschnitt „API-Schlüssel“ die Schlüssel für den jeweiligen Arbeitsbereich an. Da ein Arbeitsbereichsschlüssel Besitzerberechtigungen gewährt, kann nur der Besitzer des Arbeitsbereichs einen solchen Schlüssel erstellen, anzeigen oder widerrufen. Weitere Informationen zu Rollen findest du unter Teams.

On Premise-Worker-Schlüssel#

Wenn du einen On Premise-Host verbindest, wird ein separater Worker-Schlüssel erstellt. Worker-Schlüssel werden über die On Premise-Integration und nicht über diese Registerkarte verwaltet, erscheinen nie neben deinen API-Schlüsseln in der Liste und werden durch Trennen des Hosts widerrufen. Dabei werden auch die in der Warteschlange befindlichen und laufenden Aufträge dieses Hosts abgebrochen.

Bewährte Sicherheitspraktiken#

Empfehlungen#

  • Speichere Schlüssel in Umgebungsvariablen
  • Verwende separate Schlüssel für verschiedene Umgebungen
  • Widerrufe nicht verwendete Schlüssel umgehend
  • Erneuere Schlüssel regelmäßig
  • Verwende aussagekräftige Namen, anhand derer sich der Zweck der Schlüssel erkennen lässt

Nicht#

  • Schlüssel nicht in die Versionskontrolle einchecken
  • Schlüssel nicht zwischen Anwendungen teilen
  • Schlüssel nicht in Anwendungsausgaben protokollieren
  • Schlüssel nicht in clientseitigen Code einbetten

Schlüsselrotation#

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

  1. Erstelle einen neuen Schlüssel mit demselben Namen
  2. Stelle die Anwendungen auf den neuen Schlüssel um
  3. Prüfe, ob die Anwendungen ordnungsgemäß funktionieren
  4. Widerrufe den alten Schlüssel
Rotationszeitplan

Erwäge, Schlüssel in sensiblen Anwendungen alle 90 Tage zu wechseln.

Fehlerbehebung#

Fehler: Ungültiger Schlüssel#

Error: Invalid API key

Lösungen:

  1. Prüfe, ob der Schlüssel korrekt kopiert wurde (einschließlich des Präfixes ul_)
  2. Prüfe, ob der Schlüssel widerrufen wurde
  3. Prüfe, ob die Umgebungsvariable gesetzt 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. Prüfe, ob du der Eigentümer der Ressource bist oder den entsprechenden Zugriff auf den Arbeitsbereich hast
  2. Prüfe, ob der Schlüssel zum richtigen Arbeitsbereich gehört
  3. Wenn du Schlüssel in einem Teamarbeitsbereich verwaltest, bestätige, dass du der Eigentümer des Arbeitsbereichs 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 Häufigkeit der Anfragen – in der Tabelle zu Ratenbegrenzungen findest du die Limits für die einzelnen Kategorien
  2. Implementiere exponentielles Backoff mithilfe des Headers Retry-After
  3. Verwende einen dedizierten Endpunkt, wenn du isolierte Inferenzkapazität benötigst

Häufig gestellte Fragen#

  • Für API-Schlüssel gibt es kein festes Limit. Erstelle so viele Schlüssel, 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 Rotation einzuführen.

  • Ja. Die Schlüsselliste auf Settings > API Keys zeigt das Präfix jedes Schlüssels an. Über die Schaltfläche zum Kopieren kannst du jederzeit den vollständigen Schlüsselwert kopieren.

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

  • Nein – ein Schlüssel für einen Teamarbeitsbereich authentifiziert dich als Eigentümer des Arbeitsbereichs. Daher kann nur der Eigentümer einen solchen Schlüssel erstellen oder anzeigen. Wenn du den Schlüssel weitergibst, überträgst du damit die Berechtigungen des Eigentümers. Lass stattdessen jedes Mitglied einen Schlüssel im eigenen persönlichen Arbeitsbereich erstellen und bitte den Eigentümer, einen dedizierten Schlüssel für den Teamarbeitsbereich für gemeinsam genutzte Automatisierungen wie CI zu 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-jocher18RAraimbekovm4SEsergiuwaxmann2LAlaodouya1MYmykolaxboiko1LALaughing-q1

Kommentare