Chiavi API#

Le chiavi API di Ultralytics Platform consentono un accesso programmatico sicuro per addestramento remoto, inferenza e automazione. Crea chiavi denominate con 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 integrazione CI/CD
• local-dev - Per 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 sono archiviate con crittografia AES-256-GCM
• L'autenticazione utilizza un hash SHA-256 per una ricerca indicizzata veloce
• I valori completi delle chiavi non vengono mai memorizzati in testo in chiaro

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/...

Consulta il Riferimento REST API 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 Addestramento nel cloud per la guida completa all'addestramento remoto.

Gestisci chiavi#

Visualizza chiavi#

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

Ciascuna scheda della chiave mostra il nome della chiave, il valore della chiave copiabile, il tempo di creazione relativo, il conteggio degli utilizzi 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
• Area di lavoro del team: Le chiavi autenticano all'interno del contesto del team

Quando passi da un'area di lavoro all'altra nella barra laterale, la sezione Chiavi API mostra le chiavi per quella specifica area di lavoro. È richiesto almeno il ruolo Editor per gestire le chiavi API dell'area di lavoro. Consulta Team per i dettagli sui ruoli.

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.104

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. Crea una nuova chiave se necessario

Limite di velocità raggiunto#

Error: Rate limit exceeded

Soluzioni:

1. Riduci la frequenza delle richieste: consulta la tabella dei limiti di velocità per i limiti per endpoint
2. Implementa un backoff esponenziale utilizzando l'intestazione Retry-After
3. Usa un endpoint dedicato quando ti serve una capacità di inferenza isolata

FAQ#

Quante chiavi posso creare?#

Non c'è un limite rigido alle chiavi API. Creane quante ne servono per diverse applicazioni e ambienti.

Le chiavi scadono?#

Le chiavi non scadono automaticamente. Rimangono valide fino a quando non vengono revocate. Valuta l'implementazione della rotazione per sicurezza.

Posso vedere la mia chiave dopo la creazione?#

Sì, i valori completi delle chiavi sono visibili nell'elenco delle chiavi su Settings > API Keys. La piattaforma decripta e visualizza le tue chiavi in modo che tu possa copiarle in qualsiasi momento.

Le chiavi sono specifiche per regione?#

Le chiavi funzionano in tutte le regioni, ma accedono solo ai dati nella regione del tuo account.

Posso condividere le chiavi con i membri del team?#

Best practice: fai in modo che ogni membro del team crei la propria chiave. Per gli spazi di lavoro del team, ogni membro con ruolo Editor o superiore può creare chiavi limitate a quello spazio di lavoro.