Skip to main content
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.
Incolla la chiave esattamente come è stata emessa. Usa il pulsante di copia della finestra di dialogo invece di selezionare il testo a mano, così da non tagliare il primo o l’ultimo carattere e non includere un a capo finale. Quando uno strumento chiede la chiave in un campo di un modulo, inserisci solo la chiave: niente prefisso Bearer, niente virgolette e nessuno spazio iniziale o finale. Poiché la dashboard mostra solo gli ultimi caratteri dopo la chiusura della finestra di dialogo, non cercare mai di ricostruire una chiave persa ridigitando quel valore mascherato.Aggiungi la chiave al tuo ambiente locale o al tuo gestore di segreti:
4

Verifica la chiave

Effettua una richiesta a basso rischio per confermare che l’autenticazione stia funzionando. Get API Key Rate Limits and Balances non ha alcun costo e accetta entrambi i tipi di chiave. Usalo al posto di GET /models, che restituisce il catalogo dei modelli con o senza chiave e quindi ha esito positivo anche quando la chiave è errata:
Una risposta positiva restituisce il tuo livello API, i saldi e i limiti di frequenza, e data.accessPermitted indica se la chiave può utilizzare gli endpoint di inferenza.Un 401 con AUTHENTICATION_FAILED significa che è stata rifiutata la chiave stessa. Stampa il valore memorizzato e confrontalo con gli ultimi caratteri mostrati nella dashboard: le cause abituali sono una copia parziale, un prefisso Bearer o delle virgolette finiti all’interno del valore, oppure uno spazio o un a capo di troppo a una delle due estremità. Verifica anche che l’header sia Bearer <api-key> con esattamente uno spazio tra le due parti.
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.