Gestion des clés API

Une clé Admin peut gérer toutes vos autres clés API via l’API. Attribuez à chaque application, environnement ou client sa propre clé Inference, plafonnez ce que chacune peut dépenser, suivez l’utilisation par clé, et modifiez ou révoquez des clés sans ouvrir le tableau de bord.

Créer

Émettez une clé avec un plafond de dépense

Suivre

Voyez ce que dépense chaque clé

Modifier

Augmentez un plafond ou prolongez une expiration

Révoquer

Désactivez une clé immédiatement

Fonctionnement

Clé AdminVotre clé de contrôleCrée, modifie et révoque des clésLit l’utilisation et la facturationReste sur votre serveur

Inferencecust:acme50 $ / moisModèles privés uniquement

Inferencecust:globex5 $ / moisUniquement depuis 11.22.33.0/24

Inferencestaging10 $ / jourExpire le 30 juin

Les clés Admin peuvent appeler tous les endpoints, y compris ceux qui gèrent les clés et lisent la facturation. Les clés Inference peuvent appeler les modèles mais ne peuvent ni gérer les clés ni lire la facturation : ce sont donc les clés que vous distribuez.

	Admin	Inference
Appeler les modèles et les autres endpoints d’inférence	✓	✓
Consulter son propre solde et ses limites de débit (`GET /api_keys/rate_limits`)	✓	✓
Créer, mettre à jour et révoquer des clés (`/api_keys`)	✓
Lire l’utilisation et la facturation (`/billing/*`)	✓

Créez votre première clé Admin dans le tableau de bord : suivez Génération d’une clé API et choisissez Admin comme type de clé. Conservez-la dans un gestionnaire de secrets côté serveur, jamais dans du code côté client.

Les exemples de cette page lisent la clé Admin depuis 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",
};

Créer une clé

Cet exemple crée une clé Inference pour un client, plafonnée à 50 $ par mois et expirant le 30 juin 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 est la valeur secrète de la clé, et cette réponse est la seule occasion de la voir. Stockez-la immédiatement. Si vous la perdez, révoquez la clé et créez-en une nouvelle. Conservez également data.id : tous les autres appels de cette page l’utilisent.

Paramètres de la clé

Définissez ces paramètres lors de la création d’une clé, ou modifiez-les ultérieurement avec PATCH /api_keys. Le corps de la requête est strict : un champ inconnu renvoie 400.

Champ	Valeurs	Rôle
`apiKeyType`	`INFERENCE` ou `ADMIN`	Obligatoire à la création. Ne peut pas être modifié par la suite.
`description`	Jusqu’à 64 caractères	Obligatoire à la création. Les analyses d’utilisation étiquettent la clé avec cette valeur : indiquez-y donc votre propre identifiant, par exemple `cust:acme`.
`consumptionLimit`	`{ "usd": 50 }`	Plafond de dépense pour chaque `limitPeriod`, en `usd`, en `diem` ou les deux. Omettez une devise, ou définissez-la à `null`, pour ne pas la plafonner. Le plafond en USD comptabilise ensemble les USD, les crédits groupés et les crédits gagnés.
`limitPeriod`	`EPOCH`, `MONTH`, `LIFETIME`	Moment de réinitialisation du plafond. `EPOCH`, la valeur par défaut, se réinitialise chaque jour à 00:00 UTC, `MONTH` le 1er de chaque mois (UTC), et `LIFETIME` jamais.
`expiresAt`	`"2027-06-30"`	Une date, ou une heure UTC comme `"2027-06-30T23:59:59Z"`. Une date seule correspond à 00:00 UTC ce jour-là. Omettez ce champ pour une clé qui n’expire jamais.
`modelPrivacy`	`ALL`, `PRIVATE_TEXT`, `PRIVATE_ONLY`	`ALL`, la valeur par défaut, autorise n’importe quel modèle. `PRIVATE_TEXT` exige des modèles de texte et d’embedding Private, TEE ou E2EE. `PRIVATE_ONLY` l’exige pour tous les modèles.
`ipAllowlist`	`["11.22.33.0/24"]`	Jusqu’à 100 adresses IPv4 ou IPv6 publiques ou plages CIDR. Une liste vide autorise n’importe quelle IP.

Vous pouvez créer jusqu’à 20 clés par minute et conserver jusqu’à 500 clés actives. Contactez le support si vous avez besoin de davantage.

Vous développez un agent ? Un portefeuille détenant du VVV staké sur Base peut générer sa propre clé sans compte Venice. Consultez Création de clé API pour agent autonome.

Suivre l’utilisation

Pour savoir	Appel	Champ à lire
Ce qu’une clé a dépensé sur la période en cours	`GET /api_keys/{id}`	`currentPeriodUsage`
Ce que chaque clé a dépensé au cours des 7 derniers jours	`GET /api_keys`	`usage.trailingSevenDays`
Les dépenses par clé, jour par jour	`GET /billing/usage-analytics`	`byKey`, `byKeyDaily`
Chaque débit, avec la clé à laquelle il a été facturé	`GET /billing/usage-history`	`apiKeyId`
Si une clé peut dépenser en ce moment	`GET /api_keys/rate_limits`, appelé avec cette clé	`accessPermitted`, `balances`
Quelles clés atteignent les limites de débit	`GET /api_keys/rate_limits/log`	`apiKeyId`, `modelId`

Une clé

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"
  }
}

Cette clé a utilisé 12,50

sur ses 50

du mois. currentPeriodUsage n’apparaît que sur les clés disposant d’un plafond en USD ou en DIEM, et les montants d’utilisation sont des chaînes à quatre décimales. Les réponses renvoient consumptionLimits (au pluriel), tandis que les requêtes envoient consumptionLimit (au singulier).

Dépenses par clé au fil du temps

GET /billing/usage-analytics renvoie les totaux par clé dans byKey et une ligne par jour dans byKeyDaily, prêtes à être représentées dans un graphique. Passez lookback (7d par défaut, jusqu’à 90d) ou une paire startDate et endDate couvrant jusqu’à 90 jours. Les résultats sont mis en cache pendant 10 minutes.

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
    }
  ]
}

Chaque débit, par clé

GET /billing/usage-history liste chaque débit, et chaque entrée porte l’apiKeyId auquel il a été facturé. Utilisez-le pour rapprocher vos dépenses ou facturer vos propres clients. Les entrées sont renvoyées de la plus ancienne à la plus récente. Renvoyez nextCursor en tant que cursor, seul, jusqu’à ce qu’il soit null. Envoyez Accept: text/csv pour obtenir du CSV à la place.

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"]}

Les débits ont un amount négatif : la boucle le soustrait donc pour obtenir un total positif par clé et par devise. Les entrées sans apiKeyId proviennent de l’application web Venice, ou sont des écritures de compte telles que des achats de crédits.

Si une clé peut dépenser en ce moment

GET /api_keys/rate_limits fonctionne avec n’importe quelle clé et renseigne sur la clé qui l’appelle. accessPermitted indique si la clé peut dépenser en ce moment, et balances montre ce qu’il lui reste à dépenser.

cURL

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

GET /api_keys/rate_limits/log, avec une clé Admin, renvoie vos 50 derniers dépassements de limite de débit, chacun avec son apiKeyId et son modelId.

Modifier les limites et les paramètres

Envoyez l’id de la clé et uniquement les champs que vous souhaitez modifier. Tout le reste demeure inchangé. Cet exemple porte le plafond à 100 $ par mois :

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 } }),
});

Envoyez plutôt l’un de ces champs pour effectuer d’autres modifications :

Pour	Envoyez
Supprimer le plafond	`"consumptionLimit": { "usd": null }`
Réinitialiser le plafond chaque mois plutôt que chaque jour	`"limitPeriod": "MONTH"`
Transformer le plafond en budget unique	`"limitPeriod": "LIFETIME"`
Prolonger l’expiration	`"expiresAt": "2027-12-31"`
Supprimer l’expiration	`"expiresAt": null`
N’accepter que les requêtes provenant de vos serveurs	`"ipAllowlist": ["11.22.33.0/24"]`
Accepter de nouveau les requêtes depuis n’importe quelle IP	`"ipAllowlist": []`
N’autoriser que les modèles privés	`"modelPrivacy": "PRIVATE_ONLY"`
Renommer la clé	`"description": "cust:acme-prod"`

Une nouvelle limitPeriod s’applique immédiatement : passer à LIFETIME impute donc toutes les dépenses passées de la clé à son plafond. apiKeyType ne peut pas être modifié ; créez plutôt une nouvelle clé.

Révoquer ou faire tourner une clé

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 réponse est { "success": true }. La révocation est immédiate : la requête suivante de la clé reçoit 401 Authentication failed, et la clé disparaît de GET /api_keys. Ses débits passés restent dans l’historique d’utilisation. Pour faire tourner une clé sans interruption de service :

Créer la clé de remplacement

Créez une nouvelle clé avec les mêmes paramètres et stockez sa valeur secrète.

La déployer

Basculez votre application sur la nouvelle valeur secrète.

Révoquer l'ancienne clé

Une fois que le lastUsedAt de l’ancienne clé dans GET /api_keys ne bouge plus, supprimez-la.

Erreurs que vos appelants peuvent rencontrer

Statut	Message	Que faire
`402`	`API key USD spend limit exceeded...`, ou l’équivalent pour le DIEM	Augmentez ou supprimez le plafond, ou attendez la période suivante. Le compte lui-même peut encore disposer de fonds.
`403`	Le modèle n’est pas autorisé par le paramètre de confidentialité de la clé	Utilisez un modèle Private, TEE ou E2EE, ou modifiez `modelPrivacy`.
`403`	`This API key is restricted to configured IP addresses...`	Ajoutez l’IP de l’appelant à `ipAllowlist`.
`401`	`Authentication failed`	La clé est révoquée, expirée ou mal saisie.
`401`	`Admin API key required`	Une clé Inference a appelé un endpoint de gestion des clés ou de facturation.
`429`	`Too many API key creation requests...`	La création de clés est limitée à 20 par minute. Patientez, puis réessayez.
`400`	`Maximum number of active API keys (500) reached...`	Révoquez les clés que vous n’utilisez plus, ou contactez le support.

Consultez Codes d’erreur pour la liste complète.

Bonnes pratiques

Conservez les clés Admin sur votre serveur et ne distribuez que des clés Inference.
Attribuez à chaque application, environnement et client sa propre clé, afin que chacune puisse être suivie et révoquée individuellement.
Indiquez votre propre identifiant dans description. Les analyses d’utilisation étiquettent les clés avec cette valeur.
Plafonnez et faites expirer chaque clé que vous confiez à un tiers, et restreignez les clés de serveur à serveur à vos IP avec ipAllowlist.

Référence API

Créer une clé API

Tous les champs acceptés à la création.

Mettre à jour une clé API

Modifiez les limites, l’expiration, la confidentialité et les IP.

Lister les clés API

Toutes les clés actives avec leur utilisation.

Supprimer une clé API

Révoquez une clé.

Analyses d'utilisation

Dépenses par clé, par modèle et par jour.

Historique d'utilisation

Chaque débit, avec sa clé API.

Documentation

Démarrage

Texte et chat

Image

Vidéo

Audio

Recherche et RAG

Agents et intégrations

Outils de code

Outils pour agents

SDK et frameworks

Créer

Suivre

Modifier

Révoquer

Fonctionnement

Créer une clé

Paramètres de la clé

Suivre l’utilisation

Une clé

Dépenses par clé au fil du temps

Chaque débit, par clé

Si une clé peut dépenser en ce moment

Modifier les limites et les paramètres

Révoquer ou faire tourner une clé

Erreurs que vos appelants peuvent rencontrer

Bonnes pratiques

Référence API

Créer une clé API

Mettre à jour une clé API

Lister les clés API

Supprimer une clé API

Analyses d'utilisation

Historique d'utilisation

Créer

Suivre

Modifier

Révoquer

​Fonctionnement

​Créer une clé

​Paramètres de la clé

​Suivre l’utilisation

​Une clé

​Dépenses par clé au fil du temps

​Chaque débit, par clé

​Si une clé peut dépenser en ce moment

​Modifier les limites et les paramètres

​Révoquer ou faire tourner une clé

​Erreurs que vos appelants peuvent rencontrer

​Bonnes pratiques

​Référence API

Créer une clé API

Mettre à jour une clé API

Lister les clés API

Supprimer une clé API

Analyses d'utilisation

Historique d'utilisation

Fonctionnement

Créer une clé

Paramètres de la clé

Suivre l’utilisation

Une clé

Dépenses par clé au fil du temps

Chaque débit, par clé

Si une clé peut dépenser en ce moment

Modifier les limites et les paramètres

Révoquer ou faire tourner une clé

Erreurs que vos appelants peuvent rencontrer

Bonnes pratiques

Référence API