Chiavi API#

Le chiavi API di Ultralytics Platform consentono un accesso programmatico sicuro per l'addestramento remoto, l'inferenza e l'automazione. Crea chiavi con nome dotate di crittografia AES-256-GCM per diversi casi d'uso.

Crea chiave API#

Crea una nuova chiave API:

1. Vai su Settings > API Keys
2. Clicca su Create Key
3. Inserisci un nome per la chiave (ad esempio, "Training Server")
4. Clicca su Create Key

Nome della chiave#

Dai alla tua chiave un nome descrittivo:

• training-server - Per macchine di addestramento remoto
• ci-pipeline - Per l'integrazione CI/CD
• local-dev - Per lo sviluppo locale

Visualizzazione chiave#

Dopo la creazione, la chiave viene mostrata in una finestra di dialogo di conferma:

Formato della chiave#

Le chiavi API seguono questo formato:

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

• Prefisso: ul_ identifica le chiavi Ultralytics
• Corpo: 40 caratteri esadecimali casuali
• Totale: 43 caratteri

Sicurezza delle chiavi#

• Le chiavi vengono memorizzate con crittografia AES-256-GCM, mai in chiaro
• I primi 11 caratteri (ul_ più 8 caratteri esadecimali) fungono da prefisso di visualizzazione, in modo che una chiave possa essere identificata senza esporla

Utilizzo delle chiavi API#

Variabile d'ambiente#

Imposta la tua chiave come variabile d'ambiente:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

Valida e salva la chiave usando il YOLO CLI:

yolo login YOUR_API_KEY

Rimuovi la chiave salvata con yolo logout.

Intestazioni HTTP#

Includi la chiave nelle richieste API:

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

Oppure passalo al Python SDK (pip install "ultralytics-platform>=0.1.5"), che legge anche ULTRALYTICS_API_KEY:

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

Consulta la REST API Reference per tutti gli endpoint disponibili.

Addestramento Remoto#

Abilita lo streaming delle metriche con la tua chiave.

Installa o aggiorna il pacchetto Ultralytics prima di iniziare:

pip install -U ultralytics

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

Consulta Cloud Training per la guida completa all'addestramento remoto.

Gestisci chiavi#

Visualizza chiavi#

Tutte le chiavi sono elencate nella scheda Settings > API Keys:

Ogni scheda chiave mostra il nome della chiave, il valore della chiave copiabile, il tempo di creazione relativo e un pulsante di revoca.

Revoca chiave#

Revoca una chiave compromessa o non più necessaria:

1. Trova la chiave nella sezione Chiavi API
2. Clicca sul pulsante Revoca (cestino)
3. Conferma la revoca

Rigenera chiave#

Se una chiave è compromessa:

1. Crea una nuova chiave con lo stesso nome
2. Aggiorna le tue applicazioni
3. Revoca la vecchia chiave

Chiavi API dell'area di lavoro#

Le chiavi API sono limitate all'area di lavoro attualmente attiva:

• Area di lavoro personale: Le chiavi autenticano come il tuo account personale
• Team workspace: le chiavi si autenticano come il proprietario del team workspace, con autorizzazioni complete da proprietario in quel workspace

Quando passi da un workspace all'altro nella barra laterale, la sezione API Keys mostra le chiavi per quel workspace. Poiché una chiave del workspace comporta autorizzazioni da proprietario, solo il proprietario del workspace può crearla, visualizzarla o revocarla. Vedi Teams per i dettagli sui ruoli.

On Premise Worker Keys#

La connessione di un host On Premise genera una worker key separata. Le worker keys sono gestite dall'integrazione On Premise anziché da questa scheda, non vengono mai elencate insieme alle tue API keys e vengono revocate disconnettendo l'host, il che annulla anche i processi in coda e in esecuzione di quell'host.

Best practice di sicurezza#

Cosa fare#

• Memorizza le chiavi nelle variabili d'ambiente
• Usa chiavi separate per ambienti diversi
• Revoca prontamente le chiavi inutilizzate
• Ruota le chiavi periodicamente
• Usa nomi descrittivi per identificare gli scopi delle chiavi

Cosa non fare#

• Non inviare le chiavi al controllo versione
• Non condividere le chiavi tra applicazioni
• Non registrare le chiavi nell'output dell'applicazione
• Non incorporare le chiavi nel codice lato client

Rotazione delle chiavi#

Ruota le chiavi periodicamente per sicurezza:

1. Crea una nuova chiave con lo stesso nome
2. Aggiorna le applicazioni per usare la nuova chiave
3. Verifica che le applicazioni funzionino correttamente
4. Revoca la vecchia chiave

Risoluzione dei problemi#

Errore di chiave non valida#

Error: Invalid API key

Soluzioni:

1. Verifica che la chiave sia copiata correttamente (incluso il prefisso ul_)
2. Controlla che la chiave non sia stata revocata
3. Conferma che la variabile d'ambiente sia impostata
4. Assicurati di utilizzare ultralytics>=8.4.120

Accesso negato#

Error: Permission denied for this operation

Soluzioni:

1. Verifica di essere il proprietario della risorsa o di avere l'accesso appropriato all'area di lavoro
2. Controlla che la chiave appartenga all'area di lavoro corretta
3. Se stai gestendo le chiavi in un team workspace, conferma di essere il proprietario del workspace: gli altri ruoli ricevono Workspace owner access required
4. Crea una nuova chiave se necessario

Limite di velocità raggiunto#

Error: Rate limit exceeded

Soluzioni:

1. Riduci la frequenza delle richieste: consulta la rate limit table per i limiti per categoria
2. Implementa il backoff esponenziale utilizzando l'intestazione Retry-After
3. Usa un dedicated endpoint quando ti serve una capacità di inferenza isolata

FAQ#