Documentazione

Documentazione

Gruppi di chiavi

Dai a ciascuno dei tuoi clienti le sue chiavi API, raccoglile in un gruppo, leggi quanto hanno speso ogni cliente e ogni chiave in qualsiasi periodo e limita quanto ogni cliente può spendere in un mese. Un account, un saldo.

Un gruppo è una cartella di chiavi API nel tuo account, per esempio una per cliente: CID000001, CID000002. Una chiave in un gruppo chiama l’API come qualsiasi altra, e un gruppo non ha un saldo, ricariche o un accesso propri; può avere un limite di spesa mensile su tutte le sue chiavi. Una chiave è in un gruppo o in nessuno.

Configura i gruppi in tre passaggi

  • Crea un gruppo. Nella pagina Chiavi API, scegli «Nuovo gruppo» e dagli il nome del cliente.
  • Mettici le chiavi. Scegli «Nuova chiave» nell’intestazione del gruppo per creare una chiave al suo interno. Per spostare una chiave che hai già, apri il suo menu e scegli «Sposta in un gruppo».
  • Leggi i dati. La pagina Chiavi API mostra quanto ha speso ogni chiave in questo mese di calendario e il totale di ogni gruppo. La pagina Utilizzo mostra le stesse chiavi sotto i loro gruppi per oggi, gli ultimi 7 o 30 giorni, questo mese, il mese scorso o i giorni che scegli, fino a 90.

Leggere un mese ed esportarlo

Nella pagina Utilizzo, scegli «Mese scorso» (o «Questo mese», o «Personalizzato» per scegliere i giorni) in alto. In «Per chiave API», l’intestazione di ogni gruppo mostra il suo costo e le sue chiamate. Il menu dei gruppi in alto restringe l’intera pagina a un gruppo: i suoi dati, il grafico, i modelli e le chiamate. «Esporta CSV» scarica ciò che mostra la pagina, con lo stesso periodo e lo stesso gruppo, per chiave o per giorno.

Per chiave, il file ha una riga per chiave e gruppo, con un nome come kunavo-cost-by-key_2026-10-01_2026-10-31.csv. Elenca ogni chiave che ha fatto chiamate nel periodo, comprese quelle revocate, sotto il gruppo in cui è stata fatta ogni chiamata, e ogni chiave attiva senza chiamate nel gruppo in cui si trova ora, a 0, così l’elenco delle chiavi di ogni cliente è completo. I gruppi seguono l’ordine della dashboard, le chiavi di ogni gruppo dalla più costosa alla meno costosa e le chiavi senza gruppo per ultime. Per giorno, il file inizia con una colonna date e ha una riga per ogni giorno in cui una chiave ha fatto chiamate in un gruppo.

ColonnaContenuto
groupIl gruppo in cui sono state fatte le chiamate; vuoto per le chiamate fatte fuori da ogni gruppo. Un gruppo eliminato in seguito ha (deleted) dopo il nome.
key_nameIl nome della chiave.
key_prefixL’inizio della chiave, come lo mostra la dashboard. Mai la chiave intera.
key_statusactive o revoked.
callsChiamate effettuate con la chiave nel periodo.
errorsDi queste chiamate, quelle non riuscite. Una chiamata non riuscita non costa nulla.
input_tokensToken di input, letture e scritture della cache incluse.
output_tokensToken di output.
cached_input_tokensDei token di input, quelli letti dalla cache dei prompt.
cache_write_tokensDei token di input, quelli scritti nella cache dei prompt.
cost_usdQuanto è stato addebitato per le chiamate, in dollari statunitensi, con otto cifre decimali.
Nomi che sembrano formule. Un nome di gruppo o di chiave che inizia con =, +, - o @ viene scritto preceduto da un apostrofo, così un foglio di calcolo lo mostra come testo invece di eseguirlo come formula.

Limita quanto spende ogni gruppo in un mese

Apri il menu di un gruppo nella pagina Chiavi API e scegli «Imposta limite mensile». Il limite conta quanto spendono insieme tutte le chiavi del gruppo in un mese di calendario (UTC): le chiamate fatte da ogni chiave mentre era nel gruppo. Una richiesta che porterebbe il gruppo oltre il limite viene rifiutata con un 402 e non viene addebitato nulla. Lascia vuoto il campo per nessun limite, oppure imposta 0 per sospendere tutte le chiavi del gruppo senza revocarne nessuna.

Il limite mensile proprio di ogni chiave resta valido, e il primo limite raggiunto rifiuta la richiesta. L’intestazione del gruppo mostra il suo mese rispetto al limite, con «Limite raggiunto» quando le richieste iniziano a essere rifiutate e «In pausa» quando il limite è 0.

Kunavo scrive all’indirizzo del tuo account quando un gruppo, o una chiave con un limite proprio, ha usato l’80% del limite mensile, e di nuovo quando le richieste iniziano a essere rifiutate per quel limite: al massimo un’email di ciascun tipo al mese per ogni limite.

Come vengono contati gli importi

  • Il costo è quanto è stato addebitato. Il costo di ogni chiamata è l’importo scalato dal tuo saldo quando è terminata. Una chiamata non riuscita non costa nulla.
  • Mesi e giorni sono in UTC. Questo mese inizia il giorno 1 alle 00:00 UTC. A Yangon (UTC+6:30), per esempio, ottobre finisce il 1° novembre alle 06:30, ora locale. La pagina Utilizzo indica le date del periodo che mostra.
  • Una chiamata conta nel gruppo in cui si trovava la sua chiave al momento della chiamata. Se sposti una chiave in un altro gruppo, lì contano solo le sue chiamate da quel momento in poi; quelle precedenti restano dov’erano. Per questo il totale del mese di un gruppo nella pagina Chiavi API può differire dalla somma delle chiavi elencate ora sotto di esso.
  • Una chiave revocata resta nel suo gruppo. Quanto ha speso prima della revoca continua a contare nei totali di quel gruppo e compare nell’esportazione.
  • Un gruppo eliminato conserva le sue chiamate. Restano sotto il suo nome, segnato come eliminato, nella pagina Utilizzo e nell’esportazione, e il nome si può riutilizzare per un nuovo gruppo.
  • Tre punti, un solo importo. Per uno stesso mese di calendario, il totale di un gruppo nella pagina Chiavi API, il suo totale in «Questo mese» nella pagina Utilizzo e la somma delle sue righe nel CSV coincidono al centesimo.

Domande

  • Ogni gruppo ha un saldo proprio? No. Tutti i gruppi attingono all’unico saldo del tuo account. Per limitare quanto può spendere un cliente, imposta un limite mensile sul suo gruppo, o su ciascuna delle sue chiavi.
  • I miei clienti possono accedere per vedere il loro utilizzo? No. I gruppi sono visibili solo a te. Una chiave può leggere il proprio utilizzo con GET /v1/usage, che non mostra il suo gruppo. Se il suo gruppo ha un limite mensile, GET /v1/balance mostra alla chiave quel limite e quanto ha speso l’intero gruppo questo mese, ma non il nome del gruppo.
  • Cosa succede se elimino un gruppo? Scegli tu: le sue chiavi continuano a funzionare, da quel momento senza gruppo, oppure vengono revocate insieme al gruppo. In entrambi i casi, le chiamate che hanno fatto restano sotto il nome del gruppo.
  • E se una chiave passa da un cliente a un altro? Spostala nel gruppo dell’altro cliente: le sue chiamate contano lì da quel momento in poi, e quelle precedenti restano al primo cliente.
  • Posso leggere altri periodi? Sì: scegli «Personalizzato» nella pagina Utilizzo e fino a 90 giorni. Per un programma, GET /v1/usage restituisce il costo giornaliero di una chiave nello stesso periodo.

Per creare, raggruppare, limitare e revocare le chiavi di un cliente dai tuoi strumenti anziché a mano, usa l’API di gestione. Le sue chiavi sono una credenziale separata e funzionano solo su quell’API.