Chiavi API#

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

Crea chiave API#

Crea una nuova chiave API:

1. Vai a Impostazioni > Chiavi API
2. Fai clic su Aggiungi chiave e seleziona Ultralytics come provider
3. Inserisci un nome per la chiave (ad es. "Server di training")
4. Fai clic su Crea chiave

Nome della chiave#

Assegna alla chiave un nome descrittivo:

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

Visualizzazione della chiave#

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

Chiavi dei provider per agenti e annotazione#

La stessa scheda Impostazioni > Chiavi API memorizza anche le chiavi dei provider di modelli esterni usati dagli agenti e dai modelli a pagamento nell'annotazione guidata da classi; l'annotazione legge la chiave salvata nello spazio di lavoro del dataset. Solo il proprietario dello spazio di lavoro può aggiungere, sostituire o rimuovere queste chiavi; i membri del team possono vedere quali provider sono connessi. Chiedi al proprietario di connettere un provider mancante. Per connettere un provider come proprietario:

1. Fai clic su Aggiungi chiave.
2. Seleziona il provider corrispondente al modello linguistico o visione-linguaggio del tuo flusso di lavoro, oppure il modello di annotazione che vuoi eseguire.
3. Incolla la chiave API del provider nel campo Chiave API, quindi fai clic su Salva chiave. Il link Ottieni una chiave API nella finestra di dialogo apre la pagina delle chiavi del provider.

Una chiave Ultralytics non autentica l'accesso ai provider di modelli esterni. L'utilizzo dei provider viene addebitato tramite l'account del provider associato alla chiave salvata. Usa il comando di modifica della riga della chiave per sostituire una chiave del provider.

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, mai in testo non crittografato
• I primi 11 caratteri (ul_ più 8 caratteri esadecimali) fungono da prefisso visualizzato, così è possibile identificare una chiave senza esporla

Usare le chiavi API#

Variabile d'ambiente#

Imposta la chiave come variabile d'ambiente:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

Convalida e salva la chiave usando YOLO CLI con Python>=3.11:

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

In alternativa, passala all'SDK Python (pip install "ultralytics-platform>=0.1.45"), che legge ULTRALYTICS_API_KEY o la chiave salvata da yolo login se api_key è omesso:

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

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 su Python>=3.11 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 la guida completa al training remoto in Training nel cloud.

Gestire le chiavi#

Visualizzare le chiavi#

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

Ogni riga della chiave mostra il nome e il prefisso della chiave, la data di creazione, un pulsante per copiare la chiave completa e un pulsante di rimozione (cestino).

Revocare una chiave#

Revoca una chiave compromessa o non più necessaria:

1. Trova la chiave nella sezione Chiavi API
2. Fai clic sul pulsante di rimozione (cestino)
3. Fai clic su Rimuovi chiave per confermare

Rigenerare una chiave#

Se una chiave è stata compromessa:

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

Chiavi API dello spazio di lavoro#

Le chiavi API sono associate allo spazio di lavoro attualmente attivo:

• Spazio di lavoro personale: le chiavi autenticano come il tuo account personale
• Spazio di lavoro del team: le chiavi autenticano come proprietario dello spazio di lavoro del team, con tutti i permessi del proprietario in quello spazio di lavoro

Quando passi da uno spazio di lavoro all'altro nella barra laterale, la sezione Chiavi API mostra le chiavi dello spazio di lavoro selezionato. Poiché una chiave dello spazio di lavoro dispone dei permessi del proprietario, solo il proprietario dello spazio di lavoro può crearla, visualizzarla o revocarla. Consulta Team per i dettagli sui ruoli.

Chiavi dei worker On Premise#

Connettendo un host On Premise viene generata una chiave worker separata. Le chiavi worker si gestiscono dall'integrazione On Premise anziché da questa scheda, non vengono mai elencate insieme alle chiavi API e vengono revocate disconnettendo l'host, operazione che annulla anche i job in coda e in esecuzione su quell'host.

Best practice di sicurezza#

Da fare#

• Archivia le chiavi nelle variabili d'ambiente
• Usa chiavi separate per ambienti diversi
• Revoca tempestivamente le chiavi inutilizzate
• Ruota periodicamente le chiavi
• Usa nomi descrittivi per identificare lo scopo delle chiavi

Non#

• Non eseguire il commit delle chiavi nel 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#

Per motivi di sicurezza, ruota periodicamente le chiavi:

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

Risoluzione dei problemi#

Errore: chiave non valida#

Error: Invalid API key

Soluzioni:

1. Verifica che la chiave sia stata copiata correttamente (incluso il prefisso ul_)
2. Verifica che la chiave non sia stata revocata
3. Verifica che la variabile d'ambiente sia impostata
4. Assicurati di usare Python>=3.11 e 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. Verifica che la chiave appartenga all'area di lavoro corretta
3. Se gestisci le chiavi in un'area di lavoro del team, verifica di esserne il proprietario: gli altri ruoli ricevono Workspace owner access required
4. Se necessario, crea una nuova chiave

Limite di frequenza raggiunto#

Error: Rate limit exceeded

Soluzioni:

1. Riduci la frequenza delle richieste: consulta la tabella dei limiti di frequenza per i limiti di ciascuna categoria
2. Implementa un backoff esponenziale usando l'header Retry-After
3. Usa un endpoint dedicato quando hai bisogno di capacità di inferenza isolata

Domande frequenti#