Gestire le API key

Una chiave Admin può gestire tutte le tue altre API key tramite l’API. Assegna a ogni app, ambiente o cliente la propria chiave Inference, limita quanto ciascuna può spendere, monitora l’utilizzo per chiave e modifica o revoca le chiavi senza aprire la dashboard.

Crea

Emetti una chiave con un limite di spesa

Monitora

Scopri quanto spende ogni chiave

Modifica

Aumenta un limite o estendi una scadenza

Revoca

Disattiva subito una chiave

Come funziona

Chiave AdminLa tua chiave di controlloCrea, modifica e revoca le chiaviLegge utilizzo e fatturazioneResta sul tuo server

Inferencecust:acme$50 / meseSolo modelli privati

Inferencecust:globex$5 / meseSolo da 11.22.33.0/24

Inferencestaging$10 / giornoScade il 30 giu

Le chiavi Admin possono chiamare ogni endpoint, compresi quelli che gestiscono le chiavi e leggono la fatturazione. Le chiavi Inference possono chiamare i modelli ma non possono gestire chiavi né leggere la fatturazione, quindi sono le chiavi da distribuire.

	Admin	Inference
Chiamare i modelli e gli altri endpoint di inferenza	✓	✓
Verificare il proprio saldo e i propri limiti di frequenza (`GET /api_keys/rate_limits`)	✓	✓
Creare, aggiornare e revocare chiavi (`/api_keys`)	✓
Leggere utilizzo e fatturazione (`/billing/*`)	✓

Crea la tua prima chiave Admin dalla dashboard: segui Generare una API key e scegli Admin come tipo di chiave. Conservala in un archivio di segreti lato server, mai nel codice client.

Gli esempi in questa pagina leggono la chiave Admin da VENICE_ADMIN_KEY:

export VENICE_ADMIN_KEY="your-admin-key"

import os
import requests

BASE = "https://api.venice.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['VENICE_ADMIN_KEY']}"}

const BASE = "https://api.venice.ai/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.VENICE_ADMIN_KEY}`,
  "Content-Type": "application/json",
};

Creare una chiave

Questo crea una chiave Inference per un cliente, con un limite di $50 al mese e scadenza il 30 giugno 2027:

curl https://api.venice.ai/api/v1/api_keys \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKeyType": "INFERENCE",
    "description": "cust:acme",
    "consumptionLimit": { "usd": 50 },
    "limitPeriod": "MONTH",
    "expiresAt": "2027-06-30"
  }'

resp = requests.post(f"{BASE}/api_keys", headers=HEADERS, json={
    "apiKeyType": "INFERENCE",
    "description": "cust:acme",
    "consumptionLimit": {"usd": 50},
    "limitPeriod": "MONTH",
    "expiresAt": "2027-06-30",
})
resp.raise_for_status()
key = resp.json()["data"]
key_id, secret = key["id"], key["apiKey"]

const res = await fetch(`${BASE}/api_keys`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    apiKeyType: "INFERENCE",
    description: "cust:acme",
    consumptionLimit: { usd: 50 },
    limitPeriod: "MONTH",
    expiresAt: "2027-06-30",
  }),
});
const { data: key } = await res.json();
const { id: keyId, apiKey: secret } = key;

Response

{
  "success": true,
  "data": {
    "id": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
    "apiKey": "VENICE_INFERENCE_KEY_...",
    "apiKeyType": "INFERENCE",
    "description": "cust:acme",
    "consumptionLimit": { "usd": 50, "vcu": null, "diem": null },
    "limitPeriod": "MONTH",
    "modelPrivacy": "ALL",
    "expiresAt": "2027-06-30T00:00:00.000Z",
    "ipAllowlist": []
  }
}

data.apiKey è il segreto della chiave, e questa risposta è l’unico momento in cui lo vedrai. Conservalo subito. Se lo perdi, revoca la chiave e creane una nuova. Conserva anche data.id: tutte le altre chiamate in questa pagina lo usano.

Impostazioni della chiave

Imposta questi campi quando crei una chiave, oppure modificali in seguito con PATCH /api_keys. Il corpo della richiesta è rigoroso, quindi un campo sconosciuto restituisce 400.

Campo	Valori	Cosa fa
`apiKeyType`	`INFERENCE` or `ADMIN`	Obbligatorio alla creazione. Non può essere modificato in seguito.
`description`	Fino a 64 caratteri	Obbligatorio alla creazione. Le analisi di utilizzo etichettano la chiave con questo valore, quindi inserisci qui il tuo identificatore, ad esempio `cust:acme`.
`consumptionLimit`	`{ "usd": 50 }`	Limite di spesa per ogni `limitPeriod`, in `usd`, `diem` o entrambi. Ometti una valuta, o impostala a `null`, per non avere limiti. Il limite in USD conteggia insieme USD, crediti in bundle e crediti guadagnati.
`limitPeriod`	`EPOCH`, `MONTH`, `LIFETIME`	Quando il limite si azzera. `EPOCH`, il valore predefinito, si azzera ogni giorno alle 00:00 UTC, `MONTH` il 1° di ogni mese (UTC) e `LIFETIME` mai.
`expiresAt`	`"2027-06-30"`	Una data, oppure un orario UTC come `"2027-06-30T23:59:59Z"`. Una data da sola indica le 00:00 UTC di quel giorno. Omettilo per una chiave che non scade mai.
`modelPrivacy`	`ALL`, `PRIVATE_TEXT`, `PRIVATE_ONLY`	`ALL`, il valore predefinito, consente qualsiasi modello. `PRIVATE_TEXT` richiede modelli di testo ed embedding Private, TEE o E2EE. `PRIVATE_ONLY` lo richiede per ogni modello.
`ipAllowlist`	`["11.22.33.0/24"]`	Fino a 100 indirizzi IPv4 o IPv6 pubblici o intervalli CIDR. Un elenco vuoto consente qualsiasi IP.

Puoi creare fino a 20 chiavi al minuto e mantenere fino a 500 chiavi attive. Contatta il supporto se te ne servono di più.

Stai costruendo un agente? Un wallet che detiene VVV in staking su Base può generare la propria chiave senza un account Venice. Consulta Creazione di API key per agenti autonomi.

Monitorare l’utilizzo

Per sapere	Chiama	Leggi
Quanto ha speso una chiave in questo periodo	`GET /api_keys/{id}`	`currentPeriodUsage`
Quanto ha speso ogni chiave negli ultimi 7 giorni	`GET /api_keys`	`usage.trailingSevenDays`
Spesa per chiave, giorno per giorno	`GET /billing/usage-analytics`	`byKey`, `byKeyDaily`
Ogni addebito, con la chiave a cui è stato fatturato	`GET /billing/usage-history`	`apiKeyId`
Se una chiave può spendere in questo momento	`GET /api_keys/rate_limits`, chiamato con quella chiave	`accessPermitted`, `balances`
Quali chiavi stanno raggiungendo i limiti di frequenza	`GET /api_keys/rate_limits/log`	`apiKeyId`, `modelId`

Una chiave

curl https://api.venice.ai/api/v1/api_keys/e28e82dc-9df2-4b47-b726-d0a222ef2ab5 \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"

key = requests.get(f"{BASE}/api_keys/{key_id}", headers=HEADERS).json()["data"]

const res = await fetch(`${BASE}/api_keys/${keyId}`, { headers });
const { data: key } = await res.json();

Response (trimmed)

{
  "data": {
    "id": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
    "description": "cust:acme",
    "consumptionLimits": { "usd": 50, "diem": null, "vcu": null },
    "limitPeriod": "MONTH",
    "currentPeriodUsage": { "usd": "12.5000", "diem": "0.0000" },
    "usage": { "trailingSevenDays": { "usd": "4.2000", "diem": "0.0000", "vcu": "0.0000" } },
    "lastUsedAt": "2026-11-03T14:05:00.000Z"
  }
}

Questa chiave ha usato $12.50 dei suoi $50 per il mese. currentPeriodUsage compare solo sulle chiavi con un limite in USD o DIEM, e gli importi di utilizzo sono stringhe con quattro cifre decimali. Le risposte restituiscono consumptionLimits (plurale), mentre le richieste inviano consumptionLimit (singolare).

Spesa per chiave nel tempo

GET /billing/usage-analytics restituisce i totali per chiave in byKey e una riga al giorno in byKeyDaily, pronti per essere rappresentati in un grafico. Passa lookback (7d per impostazione predefinita, fino a 90d) oppure una coppia startDate e endDate che copra fino a 90 giorni. I risultati vengono memorizzati nella cache per 10 minuti.

cURL

curl "https://api.venice.ai/api/v1/billing/usage-analytics?lookback=30d" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"

Response (trimmed)

{
  "byKey": [
    {
      "apiKeyId": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
      "description": "cust:acme",
      "totalUsd": 12.5,
      "totalDiem": 0,
      "totalUnits": 1830000
    }
  ]
}

Ogni addebito, per chiave

GET /billing/usage-history elenca ogni addebito, e ogni voce riporta l’apiKeyId a cui è stato fatturato. Usalo per riconciliare la spesa o per fatturare ai tuoi clienti. Le voci vengono restituite a partire dalla più vecchia. Rimanda nextCursor come cursor, da solo, finché non è null. Invia Accept: text/csv per ottenere invece un CSV.

curl -G https://api.venice.ai/api/v1/billing/usage-history \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  --data-urlencode "startTimestamp=2026-10-01T00:00:00Z" \
  --data-urlencode "endTimestamp=2026-11-01T00:00:00Z"

from collections import defaultdict

spend = defaultdict(float)
params = {"startTimestamp": "2026-10-01T00:00:00Z", "endTimestamp": "2026-11-01T00:00:00Z"}
while True:
    page = requests.get(f"{BASE}/billing/usage-history", headers=HEADERS, params=params).json()
    for entry in page["data"]:
        if entry["apiKeyId"]:
            spend[(entry["apiKeyId"], entry["currency"])] -= entry["amount"]
    if page["nextCursor"] is None:
        break
    params = {"cursor": page["nextCursor"]}

Gli addebiti hanno un amount negativo, quindi il ciclo lo sottrae per ottenere un totale positivo per chiave e valuta. Le voci senza apiKeyId provengono dalla web app di Venice, oppure sono voci dell’account come gli acquisti di crediti.

Se una chiave può spendere in questo momento

GET /api_keys/rate_limits funziona con qualsiasi chiave e riporta i dati della chiave che lo chiama. accessPermitted indica se la chiave può spendere in questo momento, e balances mostra quanto le resta da spendere.

cURL

curl https://api.venice.ai/api/v1/api_keys/rate_limits \
  -H "Authorization: Bearer $VENICE_API_KEY"

GET /api_keys/rate_limits/log, con una chiave Admin, restituisce gli ultimi 50 superamenti dei limiti di frequenza, ciascuno con il proprio apiKeyId e modelId.

Modificare limiti e impostazioni

Invia l’id della chiave e solo i campi che vuoi modificare. Tutto il resto rimane invariato. Questo aumenta il limite a $100 al mese:

curl -X PATCH https://api.venice.ai/api/v1/api_keys \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
    "consumptionLimit": { "usd": 100 }
  }'

requests.patch(f"{BASE}/api_keys", headers=HEADERS, json={
    "id": key_id,
    "consumptionLimit": {"usd": 100},
}).raise_for_status()

await fetch(`${BASE}/api_keys`, {
  method: "PATCH",
  headers,
  body: JSON.stringify({ id: keyId, consumptionLimit: { usd: 100 } }),
});

Invia invece uno di questi campi per apportare altre modifiche:

Per	Invia
Rimuovere il limite	`"consumptionLimit": { "usd": null }`
Azzerare il limite ogni mese anziché ogni giorno	`"limitPeriod": "MONTH"`
Trasformare il limite in un budget una tantum	`"limitPeriod": "LIFETIME"`
Estendere la scadenza	`"expiresAt": "2027-12-31"`
Rimuovere la scadenza	`"expiresAt": null`
Accettare richieste solo dai tuoi server	`"ipAllowlist": ["11.22.33.0/24"]`
Accettare di nuovo richieste da qualsiasi IP	`"ipAllowlist": []`
Consentire solo modelli privati	`"modelPrivacy": "PRIVATE_ONLY"`
Rinominare la chiave	`"description": "cust:acme-prod"`

Un nuovo limitPeriod si applica immediatamente, quindi passare a LIFETIME conteggia nel limite tutta la spesa passata della chiave. apiKeyType non può essere modificato; crea invece una nuova chiave.

Revocare o ruotare una chiave

curl -X DELETE \
  "https://api.venice.ai/api/v1/api_keys?id=e28e82dc-9df2-4b47-b726-d0a222ef2ab5" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"

requests.delete(f"{BASE}/api_keys", headers=HEADERS, params={"id": key_id}).raise_for_status()

await fetch(`${BASE}/api_keys?id=${keyId}`, { method: "DELETE", headers });

La risposta è { "success": true }. La revoca è immediata: la richiesta successiva della chiave riceve 401 Authentication failed, e la chiave scompare da GET /api_keys. I suoi addebiti passati restano nella cronologia di utilizzo. Per ruotare una chiave senza interruzioni del servizio:

Crea la sostituta

Crea una nuova chiave con le stesse impostazioni e conservane il segreto.

Distribuiscila

Fai passare la tua app al nuovo segreto.

Revoca la vecchia chiave

Quando il lastUsedAt della vecchia chiave in GET /api_keys smette di cambiare, eliminala.

Errori che i tuoi chiamanti potrebbero ricevere

Stato	Messaggio	Cosa fare
`402`	`API key USD spend limit exceeded...`, o lo stesso per DIEM	Aumenta o rimuovi il limite, oppure attendi il periodo successivo. L’account potrebbe comunque avere ancora fondi.
`403`	Il modello non è consentito dall’impostazione di privacy della chiave	Usa un modello Private, TEE o E2EE, oppure modifica `modelPrivacy`.
`403`	`This API key is restricted to configured IP addresses...`	Aggiungi l’IP del chiamante a `ipAllowlist`.
`401`	`Authentication failed`	La chiave è revocata, scaduta o digitata in modo errato.
`401`	`Admin API key required`	Una chiave Inference ha chiamato un endpoint di gestione delle chiavi o di fatturazione.
`429`	`Too many API key creation requests...`	La creazione di chiavi è limitata a 20 al minuto. Attendi, poi riprova.
`400`	`Maximum number of active API keys (500) reached...`	Revoca le chiavi che non usi più, oppure contatta il supporto.

Consulta Codici di errore per l’elenco completo.

Buone pratiche

Mantieni le chiavi Admin sul tuo server e distribuisci solo chiavi Inference.
Assegna a ogni app, ambiente e cliente la propria chiave, così che ciascuna possa essere monitorata e revocata singolarmente.
Inserisci il tuo identificatore in description. Le analisi di utilizzo etichettano le chiavi con questo valore.
Imposta un limite e una scadenza per ogni chiave che dai a qualcun altro, e vincola le chiavi server-to-server ai tuoi IP con ipAllowlist.

API reference

Crea API key

Tutti i campi accettati alla creazione.

Aggiorna API key

Modifica limiti, scadenza, privacy e IP.

Elenca API key

Ogni chiave attiva con il relativo utilizzo.

Elimina API key

Revoca una chiave.

Analisi di utilizzo

Spesa per chiave, modello e giorno.

Cronologia di utilizzo

Ogni addebito, con la relativa API key.

Documentazione

Per iniziare

Testo e chat

Immagini

Video

Audio

Ricerca e RAG

Agenti e integrazioni

Strumenti di sviluppo

Strumenti per agenti

SDK e framework

Crea

Monitora

Modifica

Revoca

Come funziona

Creare una chiave

Impostazioni della chiave

Monitorare l’utilizzo

Una chiave

Spesa per chiave nel tempo

Ogni addebito, per chiave

Se una chiave può spendere in questo momento

Modificare limiti e impostazioni

Revocare o ruotare una chiave

Errori che i tuoi chiamanti potrebbero ricevere

Buone pratiche

API reference

Crea API key

Aggiorna API key

Elenca API key

Elimina API key

Analisi di utilizzo

Cronologia di utilizzo

Crea

Monitora

Modifica

Revoca

​Come funziona

​Creare una chiave

​Impostazioni della chiave

​Monitorare l’utilizzo

​Una chiave

​Spesa per chiave nel tempo

​Ogni addebito, per chiave

​Se una chiave può spendere in questo momento

​Modificare limiti e impostazioni

​Revocare o ruotare una chiave

​Errori che i tuoi chiamanti potrebbero ricevere

​Buone pratiche

​API reference

Crea API key

Aggiorna API key

Elenca API key

Elimina API key

Analisi di utilizzo

Cronologia di utilizzo

Come funziona

Creare una chiave

Impostazioni della chiave

Monitorare l’utilizzo

Una chiave

Spesa per chiave nel tempo

Ogni addebito, per chiave

Se una chiave può spendere in questo momento

Modificare limiti e impostazioni

Revocare o ruotare una chiave

Errori che i tuoi chiamanti potrebbero ricevere

Buone pratiche

API reference