Clés API#

Les clés API de Ultralytics Platform permettent un accès programmatique sécurisé à l'entraînement à distance, à l'inférence et à l'automatisation. Crée des clés nommées avec un chiffrement AES-256-GCM pour différents cas d'utilisation.

Créer une clé API#

Crée une nouvelle clé API :

1. Va dans Paramètres > Clés API
2. Clique sur Ajouter une clé et sélectionne Ultralytics comme fournisseur
3. Saisis un nom pour la clé (par exemple, "Serveur d'entraînement")
4. Clique sur Créer une clé

Nom de la clé#

Donne à ta clé un nom descriptif :

• training-server - Pour les machines d'entraînement à distance
• ci-pipeline - Pour l'intégration CI/CD
• local-dev - Pour le développement local

Affichage de la clé#

Après sa création, la clé s'affiche dans une boîte de dialogue de confirmation :

Clés de fournisseur pour les agents#

Le même onglet Paramètres > Clés d'API stocke également les clés des fournisseurs de modèles externes utilisés par les agents. Seul le propriétaire de l'espace de travail peut ajouter, remplacer ou supprimer ces clés ; les membres de l'équipe peuvent voir quels fournisseurs sont connectés. Demande au propriétaire de connecter un fournisseur manquant. Pour connecter un fournisseur en tant que propriétaire :

1. Clique sur Ajouter une clé.
2. Sélectionne le fournisseur correspondant au modèle linguistique ou vision-langage de ton flux de travail.
3. Colle la clé d'API de ce fournisseur dans Clé d'API, puis clique sur Enregistrer la clé. Le lien Obtenir une clé d'API de la boîte de dialogue ouvre la page des clés du fournisseur.

Une clé Ultralytics n'authentifie pas les fournisseurs de modèles externes. L'utilisation des fournisseurs est facturée via le compte de fournisseur associé à la clé enregistrée. Utilise le contrôle de modification de la ligne de clé pour remplacer une clé de fournisseur.

Format de la clé#

Les clés API suivent ce format :

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

• Préfixe : ul_ identifie les clés Ultralytics
• Corps : 40 caractères hexadécimaux aléatoires
• Total : 43 caractères

Sécurité des clés#

• Les clés sont stockées avec un chiffrement AES-256-GCM, jamais en texte brut
• Les 11 premiers caractères (ul_ suivis de 8 caractères hexadécimaux) servent de préfixe d'affichage, afin d'identifier une clé sans l'exposer

Utiliser les clés API#

Variable d'environnement#

Définis ta clé comme variable d'environnement :

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

Valide et enregistre la clé en utilisant la CLI YOLO sur Python>=3.11 :

yolo login YOUR_API_KEY

Supprime la clé enregistrée avec yolo logout.

En-têtes HTTP#

Inclus la clé dans les requêtes API :

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

Ou passe-le au kit de développement logiciel Python SDK (pip install "ultralytics-platform>=0.1.32"), qui lit ULTRALYTICS_API_KEY ou la clé enregistrée par yolo login lorsque api_key est omis :

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

Consulte la référence de l'API REST pour connaître tous les points de terminaison disponibles.

Entraînement distant#

Active la diffusion des métriques avec ta clé.

Installe ou mets à jour le paquet Ultralytics sur Python>=3.11 avant de commencer :

pip install -U ultralytics

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

Consulte Entraînement dans le cloud pour obtenir le guide complet de l'entraînement à distance.

Gérer les clés#

Afficher les clés#

Toutes les clés sont répertoriées dans l'onglet Settings > API Keys :

Chaque carte de clé affiche le nom de la clé, sa valeur copiable, la date relative de création et un bouton de révocation.

Révoquer une clé#

Révoque une clé qui a été compromise ou dont tu n'as plus besoin :

1. Trouve la clé dans la section Clés API
2. Clique sur le bouton Révoquer (corbeille)
3. Confirme la révocation

Régénérer une clé#

Si une clé est compromise :

1. Crée une nouvelle clé avec le même nom
2. Mets à jour tes applications
3. Révoque l'ancienne clé

Clés API de l'espace de travail#

Les clés API sont limitées à l'espace de travail actuellement actif :

• Espace de travail personnel : les clés authentifient ton compte personnel
• Espace de travail d'équipe : les clés authentifient le propriétaire de l'espace de travail d'équipe et disposent de toutes les autorisations du propriétaire dans cet espace

Lorsque tu changes d'espace de travail dans la barre latérale, la section Clés API affiche les clés de cet espace. Comme une clé d'espace de travail confère les autorisations du propriétaire, seul le propriétaire de l'espace de travail peut en créer, consulter ou révoquer une. Consulte Équipes pour en savoir plus sur les rôles.

Clés des workers On Premise#

La connexion d'un hôte On Premise génère une clé de worker distincte. Les clés de worker sont gérées depuis l'intégration On Premise plutôt que depuis cet onglet, ne sont jamais répertoriées avec tes clés API et sont révoquées en déconnectant l'hôte, ce qui annule également les tâches de cet hôte qui sont en file d'attente ou en cours d'exécution.

Bonnes pratiques de sécurité#

À faire#

• Stocke les clés dans des variables d'environnement
• Utilise des clés distinctes pour les différents environnements
• Révoque rapidement les clés inutilisées
• Fais régulièrement tourner les clés
• Utilise des noms descriptifs pour identifier l'utilisation des clés

À ne pas faire#

• Intégrer les clés au contrôle de version
• Partager les clés entre les applications
• Consigner les clés dans la sortie de l'application
• Intégrer les clés au code côté client

Rotation des clés#

Fais régulièrement tourner les clés pour renforcer la sécurité :

1. Crée une nouvelle clé avec le même nom
2. Mets à jour les applications pour utiliser la nouvelle clé
3. Vérifie que les applications fonctionnent correctement
4. Révoque l'ancienne clé

Dépannage#

Erreur de clé non valide#

Error: Invalid API key

Solutions :

1. Vérifie que la clé a été correctement copiée (y compris le préfixe ul_)
2. Vérifie que la clé n'a pas été révoquée
3. Confirme que la variable d'environnement est définie
4. Assure-toi d'utiliser Python>=3.11 et ultralytics>=8.4.120

Autorisation refusée#

Error: Permission denied for this operation

Solutions :

1. Vérifie que tu es le propriétaire de la ressource ou que tu disposes des accès appropriés à l'espace de travail
2. Vérifie que la clé appartient au bon espace de travail
3. Si tu gères les clés dans un espace de travail d'équipe, confirme que tu en es le propriétaire : les autres rôles obtiennent Workspace owner access required
4. Crée une nouvelle clé si nécessaire

Limitation du débit#

Error: Rate limit exceeded

Solutions :

1. Réduis la fréquence des requêtes : consulte le tableau des limites de débit pour connaître les limites par catégorie
2. Mets en œuvre un backoff exponentiel à l'aide de l'en-tête Retry-After
3. Utilise un point de terminaison dédié lorsque tu as besoin d'une capacité d'inférence isolée

FAQ#