Generare una API key

Le richieste alle API di Venice vengono autenticate con API key Bearer. Questa guida mostra come creare una chiave dalla dashboard di Venice, conservarla in modo sicuro e verificare che funzioni.

Se stai costruendo un agente autonomo che deve generare la propria chiave con un wallet, usa invece la guida Creazione di API key per agenti autonomi.

​

Prima di iniziare

• Accedi al tuo account Venice.
• Assicurati che l’account abbia un saldo spendibile prima di chiamare endpoint a pagamento. Puoi creare una chiave prima di finanziare l’account, ma le richieste ai modelli non andranno a buon fine finché l’account non potrà consumare DIEM, crediti inclusi o USD.

1. Apri le impostazioni API

   Visita https://venice.ai/settings/api. Puoi aprire questa pagina anche dall’app Venice selezionando API nelle tue impostazioni.

   La dashboard delle impostazioni API mostra i tuoi saldi, il tuo API tier, l’utilizzo e le API key esistenti.

2. Avvia una nuova chiave

   Seleziona Generate New API Key, quindi configura la chiave:

   • Description: usa un nome breve che identifichi l’app, l’ambiente o l’integrazione che userà questa chiave.
   • API Key Type: usa Inference Only per le normali richieste ai modelli. Usa Admin solo quando la chiave deve gestire API key in modo programmatico.
   • Expires at: facoltativamente imposta una data di scadenza. Se lasci questo campo vuoto, la chiave non scade automaticamente.
   • Epoch Consumption Limits: facoltativamente limita quanti DIEM o USD questa chiave può spendere durante un’epoca di 24 ore. Se lasci questo campo vuoto, la chiave può usare il saldo disponibile dell’account nei limiti del tuo account.
3. Genera e copia la chiave

   Clicca su Generate. Venice mostrerà l’API key completa una sola volta.

   Copia immediatamente la chiave e conservala in un luogo sicuro. Dopo aver chiuso la finestra di dialogo, Venice mostra solo metadati identificativi come la descrizione e gli ultimi caratteri della chiave. Se perdi il valore segreto, elimina la chiave e creane una nuova.

   Aggiungi la chiave al tuo ambiente locale o al tuo gestore di segreti:

   export VENICE_API_KEY="your-api-key-here"
   
4. Verifica la chiave

   Effettua una richiesta a basso rischio per confermare che l’autenticazione stia funzionando:

   curl --request GET \
     --url https://api.venice.ai/api/v1/models \
     --header "Authorization: Bearer $VENICE_API_KEY"
   

   Una risposta positiva restituisce i modelli disponibili. Se ricevi un errore di autenticazione, verifica che la chiave sia stata copiata per intero e che l’header Authorization sia formattato come Bearer <api-key>.

​

Buone pratiche

• Crea chiavi separate per sviluppo, staging e produzione.
• Preferisci chiavi Inference Only per applicazioni che chiamano solo endpoint dei modelli.
• Mantieni rare le chiavi Admin, limitale strettamente nello scope e conservale solo in ambienti server-side affidabili.
• Non committare mai le API key nel controllo di versione e non esporle nel codice client-side.
• Imposta date di scadenza e limiti di consumo per le chiavi usate in ambienti temporanei, condivisi o a maggior rischio.
• Elimina le chiavi inutilizzate e ruota qualsiasi chiave che potrebbe essere stata esposta.

​

Gestione programmatica delle chiavi

Le chiavi Admin possono gestire le API key tramite gli endpoint dell’API reference:

Crea API key

Crea una nuova API key in stile dashboard a partire da una chiave admin esistente.

Elenca API key

Visualizza le chiavi attive e i loro metadati.

Aggiorna API key

Aggiorna la descrizione di una chiave, la data di scadenza o i limiti di consumo.

Elimina API key

Revoca una chiave che non è più necessaria.