Generare una API key

Crea una chiave API Venice dalla dashboard, conserva il bearer token in modo sicuro e verifica una prima chat completion autenticata.

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

Disabilitare la spesa in USD durante la creazione di una chiave API nell’app Venice imposta a zero il limite di spesa in USD per la chiave API in questione. Le chiamate API possono fallire con un errore di saldo insufficiente quando il tuo DIEM disponibile o i crediti in bundle non riescono a coprire la richiesta, anche se il tuo account ha un saldo in USD.

​

Risoluzione degli errori di limite di spesa

I limiti di spesa per chiave sono separati dal saldo del tuo account. Una chiave può essere bloccata dalla spesa anche quando l’account dispone ancora di crediti in USD finanziati, DIEM o crediti in bundle. Se una richiesta restituisce un 402 con uno di questi codici, la causa è il limite della chiave stessa e non il saldo dell’account:

• API_KEY_USD_SPEND_LIMIT_EXCEEDED — il limite di spesa in USD della chiave è impostato a zero (la spesa in USD è stata disabilitata alla creazione) oppure l’epoca corrente ha raggiunto il proprio tetto in USD.
• API_KEY_DIEM_SPEND_LIMIT_EXCEEDED — la chiave ha raggiunto il proprio tetto DIEM per l’epoca di 24 ore corrente.

Per verificare lo stato attuale di una chiave, chiama Get API Key Rate Limits and Balances e ispeziona data.accessPermitted, data.balances e i limiti di consumo per chiave.

Per risolvere l’errore, aumenta o rimuovi gli Epoch Consumption Limits della chiave su venice.ai/settings/api, oppure chiama Update API Key con nuovi consumptionLimits. I saldi a livello di account (USD, DIEM e crediti in bundle) sono fonti di pagamento indipendenti e vengono consumati automaticamente in base alla disponibilità; non è necessario sceglierne uno al momento della richiesta.

Consulta Codici di errore per l’elenco completo delle risposte relative alla fatturazione.

​

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.