Chiavi API

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

Crea chiave API

Crea una nuova chiave API:

1. Vai su Impostazioni > Chiavi API
2. Clicca su Crea chiave
3. Inserisci un nome per la chiave (es. "Server di addestramento")
4. Clicca su Crea chiave

Nome 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 una sola volta:

Formato chiave

Le chiavi API seguono questo formato:

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

Sicurezza della chiave

• Le chiavi sono archiviate con crittografia AES-256-GCM
• L'autenticazione utilizza l'hash SHA-256 per una rapida ricerca del prefisso e confronto degli hash
• I valori completi delle chiavi non vengono mai salvati 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

Imposta la chiave utilizzando la YOLO CLI:

yolo settings api_key="YOUR_API_KEY"

Nel codice

Usa la chiave nei tuoi script Python:

import os

# From environment (recommended)
api_key = os.environ.get("ULTRALYTICS_API_KEY")

# Or directly (not recommended for production)
api_key = "YOUR_API_KEY"

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.

pip install "ultralytics>=8.4.35"

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

Vedi Addestramento in cloud per la guida completa all'addestramento remoto.

Gestisci chiavi

Visualizza chiavi

All keys are listed on the Settings > API Keys tab:

Ogni scheda chiave mostra il nome della chiave, il valore completo decriptato della chiave (copiabile), il tempo relativo di creazione e un pulsante per revocarla.

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 nel contesto del team

Quando cambi area di lavoro nella barra laterale, la sezione Chiavi API mostra le chiavi per quell'area di lavoro. Per gestire le chiavi API dell'area di lavoro è richiesto il ruolo di Editor o superiore. Vedi Team per i dettagli sui ruoli.

Best practice di sicurezza

Cosa fare

• Salva le chiavi in 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

• Eseguire il commit delle chiavi nel controllo versione
• Condividere chiavi tra applicazioni
• Registrare le chiavi nell'output dell'applicazione
• 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 chiave non valida

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 usare ultralytics>=8.4.35

Permesso negato

Soluzioni:

1. Verifica di essere il proprietario della risorsa o di avere un 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 frequenza

Soluzioni:

1. Riduci la frequenza delle richieste — vedi la tabella dei limiti di frequenza per i limiti per endpoint
2. Implementa il backoff esponenziale usando l'intestazione Retry-After
3. Usa un endpoint dedicato per un throughput di inferenza illimitato

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 una maggiore sicurezza.

Posso vedere la mia chiave dopo la creazione?

Sì, i valori completi delle chiavi sono visibili nell'elenco delle chiavi in 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?

Pratica consigliata: 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.