> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestire le API key

> Crea, limita, monitora, aggiorna e revoca le API key di Venice dal codice con una chiave Admin.

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.

> [card] [Crea](#create-a-key)
>
> Emetti una chiave con un limite di spesa

> [card] [Monitora](#track-usage)
>
> Scopri quanto spende ogni chiave

> [card] [Modifica](#change-limits-and-settings)
>
> Aumenta un limite o estendi una scadenza

> [card] [Revoca](#revoke-or-rotate-a-key)
>
> Disattiva subito una chiave

## Come funziona

Chiave Admin
La tua chiave di controllo
Crea, modifica e revoca le chiavi
Legge utilizzo e fatturazione
Resta sul tuo server

Inference
cust:acme

\$50 / mese
Solo modelli privati

Inference
cust:globex

\$5 / mese
Solo da 11.22.33.0/24

Inference
staging

\$10 / giorno
Scade 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/*`) | ✓ | |

> [!NOTE]
>
> Crea la tua prima chiave Admin dalla dashboard: segui [Generare una API key](https://docs.venice.ai/it/guides/getting-started/generating-api-key.md) 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`:

```bash cURL theme={"system"}
export VENICE_ADMIN_KEY="your-admin-key"
```

```python Python theme={"system"}
import os
import requests

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

```javascript Node.js theme={"system"}
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:

```bash cURL theme={"system"}
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"
  }'
```

```python Python theme={"system"}
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"]
```

```javascript Node.js theme={"system"}
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;
```

```json Response theme={"system"}
{
  "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": []
  }
}
```

> [!WARNING]
>
> `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ù.

> [!TIP]
>
> 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](https://docs.venice.ai/it/guides/integrations/generating-api-key-agent.md).

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

```bash cURL theme={"system"}
curl https://api.venice.ai/api/v1/api_keys/e28e82dc-9df2-4b47-b726-d0a222ef2ab5 \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"
```

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

```javascript Node.js theme={"system"}
const res = await fetch(`${BASE}/api_keys/${keyId}`, { headers });
const { data: key } = await res.json();
```

```json Response (trimmed) theme={"system"}
{
  "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.

```bash cURL theme={"system"}
curl "https://api.venice.ai/api/v1/billing/usage-analytics?lookback=30d" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"
```

```json Response (trimmed) theme={"system"}
{
  "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.

```bash cURL theme={"system"}
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"
```

```python Python theme={"system"}
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.

```bash cURL theme={"system"}
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:

```bash cURL theme={"system"}
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 }
  }'
```

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

```javascript Node.js theme={"system"}
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

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

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

```javascript Node.js theme={"system"}
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:

**1. Crea la sostituta**

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

**2. Distribuiscila**

Fai passare la tua app al nuovo segreto.

**3. 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](https://docs.venice.ai/it/api-reference/error-codes.md) 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

> [card] [Crea API key](https://docs.venice.ai/it/api-reference/endpoint/api_keys/create.md)
>
> Tutti i campi accettati alla creazione.

> [card] [Aggiorna API key](https://docs.venice.ai/it/api-reference/endpoint/api_keys/update.md)
>
> Modifica limiti, scadenza, privacy e IP.

> [card] [Elenca API key](https://docs.venice.ai/it/api-reference/endpoint/api_keys/list.md)
>
> Ogni chiave attiva con il relativo utilizzo.

> [card] [Elimina API key](https://docs.venice.ai/it/api-reference/endpoint/api_keys/delete.md)
>
> Revoca una chiave.

> [card] [Analisi di utilizzo](https://docs.venice.ai/it/api-reference/endpoint/billing/usage-analytics.md)
>
> Spesa per chiave, modello e giorno.

> [card] [Cronologia di utilizzo](https://docs.venice.ai/it/api-reference/endpoint/billing/usage-history.md)
>
> Ogni addebito, con la relativa API key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.