> ## 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. # Gestion des clés API > Créez, plafonnez, suivez, mettez à jour et révoquez des clés API Venice depuis votre code avec une clé Admin. 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. > [card] [Créer](#create-a-key) > > Émettez une clé avec un plafond de dépense > [card] [Suivre](#track-usage) > > Voyez ce que dépense chaque clé > [card] [Modifier](#change-limits-and-settings) > > Augmentez un plafond ou prolongez une expiration > [card] [Révoquer](#revoke-or-rotate-a-key) > > Désactivez une clé immédiatement ## Fonctionnement Clé Admin Votre clé de contrôle Crée, modifie et révoque des clés Lit l'utilisation et la facturation Reste sur votre serveur Inference cust:acme 50 \$ / mois Modèles privés uniquement Inference cust:globex 5 \$ / mois Uniquement depuis 11.22.33.0/24 Inference staging 10 \$ / jour Expire 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/*`) | ✓ | | > [!NOTE] > > Créez votre première clé Admin dans le tableau de bord : suivez [Génération d'une clé API](https://docs.venice.ai/fr/guides/getting-started/generating-api-key.md) 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` : ```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", }; ``` ## 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 : ```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` 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. > [!TIP] > > 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](https://docs.venice.ai/fr/guides/integrations/generating-api-key-agent.md). ## 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é ```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" } } ``` 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. ```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 } ] } ``` ### 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. ```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"]} ``` 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. ```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`, 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 : ```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 } }), }); ``` 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é ```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 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 : **1. Créer la clé de remplacement** Créez une nouvelle clé avec les mêmes paramètres et stockez sa valeur secrète. **2. La déployer** Basculez votre application sur la nouvelle valeur secrète. **3. 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](https://docs.venice.ai/fr/api-reference/error-codes.md) 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 > [card] [Créer une clé API](https://docs.venice.ai/fr/api-reference/endpoint/api_keys/create.md) > > Tous les champs acceptés à la création. > [card] [Mettre à jour une clé API](https://docs.venice.ai/fr/api-reference/endpoint/api_keys/update.md) > > Modifiez les limites, l'expiration, la confidentialité et les IP. > [card] [Lister les clés API](https://docs.venice.ai/fr/api-reference/endpoint/api_keys/list.md) > > Toutes les clés actives avec leur utilisation. > [card] [Supprimer une clé API](https://docs.venice.ai/fr/api-reference/endpoint/api_keys/delete.md) > > Révoquez une clé. > [card] [Analyses d'utilisation](https://docs.venice.ai/fr/api-reference/endpoint/billing/usage-analytics.md) > > Dépenses par clé, par modèle et par jour. > [card] [Historique d'utilisation](https://docs.venice.ai/fr/api-reference/endpoint/billing/usage-history.md) > > Chaque débit, avec sa clé API. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.