> ## 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. # API-Schlüssel verwalten > Erstellen, begrenzen, überwachen, aktualisieren und widerrufen Sie Venice-API-Schlüssel per Code mit einem Admin-Schlüssel. Ein Admin-Schlüssel kann alle Ihre anderen API-Schlüssel über die API verwalten. Geben Sie jeder App, jeder Umgebung und jedem Kunden einen eigenen Inference-Schlüssel, begrenzen Sie, wie viel jeder davon ausgeben darf, verfolgen Sie die Nutzung pro Schlüssel und ändern oder widerrufen Sie Schlüssel, ohne das Dashboard zu öffnen. > [card] [Erstellen](#create-a-key) > > Einen Schlüssel mit Ausgabenlimit ausstellen > [card] [Überwachen](#track-usage) > > Sehen, was jeder Schlüssel ausgibt > [card] [Ändern](#change-limits-and-settings) > > Ein Limit erhöhen oder ein Ablaufdatum verlängern > [card] [Widerrufen](#revoke-or-rotate-a-key) > > Einen Schlüssel sofort sperren ## So funktioniert es Admin-Schlüssel Ihr Steuerungsschlüssel Erstellt, ändert und widerruft Schlüssel Liest Nutzung und Abrechnung Bleibt auf Ihrem Server Inference cust:acme 50 \$ / Monat Nur private Modelle Inference cust:globex 5 \$ / Monat Nur von 11.22.33.0/24 Inference staging 10 \$ / Tag Läuft am 30. Juni ab Admin-Schlüssel können jeden Endpunkt aufrufen, einschließlich derjenigen, die Schlüssel verwalten und Abrechnungsdaten lesen. Inference-Schlüssel können Modelle aufrufen, aber weder Schlüssel verwalten noch Abrechnungsdaten lesen – daher sind sie die Schlüssel, die Sie weitergeben. | | Admin | Inference | | - | :-: | :-: | | Modelle und andere Inferenz-Endpunkte aufrufen | ✓ | ✓ | | Eigenes Guthaben und eigene Ratenlimits prüfen (`GET /api_keys/rate_limits`) | ✓ | ✓ | | Schlüssel erstellen, aktualisieren und widerrufen (`/api_keys`) | ✓ | | | Nutzung und Abrechnung lesen (`/billing/*`) | ✓ | | > [!NOTE] > > Erstellen Sie Ihren ersten Admin-Schlüssel im Dashboard: Folgen Sie der Anleitung [API-Schlüssel generieren](https://docs.venice.ai/de/guides/getting-started/generating-api-key.md) und wählen Sie **Admin** als Schlüsseltyp. Bewahren Sie ihn in einem serverseitigen Secret-Speicher auf, niemals in Client-Code. Die Beispiele auf dieser Seite lesen den Admin-Schlüssel aus `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", }; ``` ## Einen Schlüssel erstellen Dies erstellt einen Inference-Schlüssel für einen Kunden, begrenzt auf 50 \$ pro Monat und mit Ablauf am 30. Juni 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` ist der geheime Wert des Schlüssels, und diese Antwort ist das einzige Mal, dass Sie ihn sehen. Speichern Sie ihn sofort. Wenn er verloren geht, widerrufen Sie den Schlüssel und erstellen Sie einen neuen. Bewahren Sie auch `data.id` auf: Jeder andere Aufruf auf dieser Seite verwendet sie. ### Schlüsseleinstellungen Legen Sie diese beim Erstellen eines Schlüssels fest oder ändern Sie sie später mit `PATCH /api_keys`. Der Request-Body wird strikt geprüft, daher gibt ein unbekanntes Feld `400` zurück. | Feld | Werte | Funktion | | - | - | - | | `apiKeyType` | `INFERENCE` oder `ADMIN` | Beim Erstellen erforderlich. Kann später nicht geändert werden. | | `description` | Bis zu 64 Zeichen | Beim Erstellen erforderlich. Die Nutzungsanalyse beschriftet den Schlüssel damit, also tragen Sie hier Ihre eigene Kennung ein, z. B. `cust:acme`. | | `consumptionLimit` | `{ "usd": 50 }` | Ausgabenlimit für jede `limitPeriod`, in `usd`, `diem` oder beidem. Lassen Sie eine Währung weg oder setzen Sie sie auf `null`, um kein Limit festzulegen. Das USD-Limit zählt USD, gebündelte Credits und verdiente Credits zusammen. | | `limitPeriod` | `EPOCH`, `MONTH`, `LIFETIME` | Wann das Limit zurückgesetzt wird. `EPOCH` (Standard) wird täglich um 00:00 UTC zurückgesetzt, `MONTH` am 1. jedes Monats (UTC) und `LIFETIME` nie. | | `expiresAt` | `"2027-06-30"` | Ein Datum oder eine UTC-Zeit wie `"2027-06-30T23:59:59Z"`. Ein Datum allein bedeutet 00:00 UTC an diesem Tag. Lassen Sie es weg, damit der Schlüssel nie abläuft. | | `modelPrivacy` | `ALL`, `PRIVATE_TEXT`, `PRIVATE_ONLY` | `ALL` (Standard) erlaubt jedes Modell. `PRIVATE_TEXT` erfordert Private-, TEE- oder E2EE-Modelle für Text und Embeddings. `PRIVATE_ONLY` erfordert dies für jedes Modell. | | `ipAllowlist` | `["11.22.33.0/24"]` | Bis zu 100 öffentliche IPv4- oder IPv6-Adressen oder CIDR-Bereiche. Eine leere Liste erlaubt jede IP. | Sie können bis zu 20 Schlüssel pro Minute erstellen und bis zu 500 aktive Schlüssel besitzen. Wenden Sie sich an den Support, wenn Sie mehr benötigen. > [!TIP] > > Sie entwickeln einen Agenten? Eine Wallet mit gestakten VVV auf Base kann ihren eigenen Schlüssel ohne Venice-Konto erstellen. Siehe [Erstellung von API-Schlüsseln für autonome Agenten](https://docs.venice.ai/de/guides/integrations/generating-api-key-agent.md). ## Nutzung überwachen | Um herauszufinden | Aufruf | Feld | | - | - | - | | Was ein Schlüssel in diesem Zeitraum ausgegeben hat | `GET /api_keys/{id}` | `currentPeriodUsage` | | Was jeder Schlüssel in den letzten 7 Tagen ausgegeben hat | `GET /api_keys` | `usage.trailingSevenDays` | | Ausgaben pro Schlüssel, nach Tag | `GET /billing/usage-analytics` | `byKey`, `byKeyDaily` | | Jede Belastung mit dem Schlüssel, dem sie berechnet wurde | `GET /billing/usage-history` | `apiKeyId` | | Ob ein Schlüssel gerade Ausgaben tätigen kann | `GET /api_keys/rate_limits`, aufgerufen mit diesem Schlüssel | `accessPermitted`, `balances` | | Welche Schlüssel Ratenlimits erreichen | `GET /api_keys/rate_limits/log` | `apiKeyId`, `modelId` | ### Ein Schlüssel ```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" } } ``` Dieser Schlüssel hat 12,50 $seiner 50$ für den Monat verbraucht. `currentPeriodUsage` erscheint nur bei Schlüsseln mit einem USD- oder DIEM-Limit, und Nutzungsbeträge sind Strings mit vier Dezimalstellen. Antworten geben `consumptionLimits` (Plural) zurück, während Anfragen `consumptionLimit` (Singular) senden. ### Ausgaben pro Schlüssel im Zeitverlauf `GET /billing/usage-analytics` gibt Summen pro Schlüssel in `byKey` und eine Zeile pro Tag in `byKeyDaily` zurück – bereit für Diagramme. Übergeben Sie `lookback` (standardmäßig `7d`, bis zu `90d`) oder ein Paar aus `startDate` und `endDate`, das bis zu 90 Tage umfasst. Ergebnisse werden 10 Minuten lang zwischengespeichert. ```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 } ] } ``` ### Jede Belastung pro Schlüssel `GET /billing/usage-history` listet jede Belastung auf, und jeder Eintrag enthält die `apiKeyId`, der sie berechnet wurde. Verwenden Sie dies, um Ausgaben abzugleichen oder Ihre eigenen Kunden abzurechnen. Einträge werden beginnend mit dem ältesten zurückgegeben. Senden Sie `nextCursor` allein als `cursor` zurück, bis der Wert `null` ist. Senden Sie `Accept: text/csv`, um stattdessen CSV zu erhalten. ```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"]} ``` Belastungen haben einen negativen `amount`, daher zieht die Schleife ihn ab, um eine positive Summe pro Schlüssel und Währung zu erhalten. Einträge ohne `apiKeyId` stammen aus der Venice-Web-App oder sind Kontoeinträge wie Credit-Käufe. ### Ob ein Schlüssel gerade Ausgaben tätigen kann `GET /api_keys/rate_limits` funktioniert mit jedem Schlüssel und gibt Auskunft über den Schlüssel, der ihn aufruft. `accessPermitted` gibt an, ob der Schlüssel gerade Ausgaben tätigen kann, und `balances` zeigt, wie viel er noch ausgeben kann. ```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` gibt mit einem Admin-Schlüssel Ihre letzten 50 Ratenlimit-Treffer zurück, jeweils mit `apiKeyId` und `modelId`. ## Limits und Einstellungen ändern Senden Sie die `id` des Schlüssels und nur die Felder, die Sie ändern möchten. Alles andere bleibt unverändert. Dies erhöht das Limit auf 100 \$ pro Monat: ```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 } }), }); ``` Senden Sie stattdessen eines dieser Felder, um andere Änderungen vorzunehmen: | Ziel | Senden | | - | - | | Limit entfernen | `"consumptionLimit": { "usd": null }` | | Limit monatlich statt täglich zurücksetzen | `"limitPeriod": "MONTH"` | | Limit zu einem einmaligen Budget machen | `"limitPeriod": "LIFETIME"` | | Ablaufdatum verlängern | `"expiresAt": "2027-12-31"` | | Ablaufdatum entfernen | `"expiresAt": null` | | Nur Anfragen von Ihren Servern akzeptieren | `"ipAllowlist": ["11.22.33.0/24"]` | | Wieder Anfragen von jeder IP akzeptieren | `"ipAllowlist": []` | | Nur private Modelle erlauben | `"modelPrivacy": "PRIVATE_ONLY"` | | Schlüssel umbenennen | `"description": "cust:acme-prod"` | Eine neue `limitPeriod` gilt sofort, sodass ein Wechsel zu `LIFETIME` alle bisherigen Ausgaben des Schlüssels auf das Limit anrechnet. `apiKeyType` kann nicht geändert werden; erstellen Sie stattdessen einen neuen Schlüssel. ## Einen Schlüssel widerrufen oder rotieren ```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 }); ``` Die Antwort lautet `{ "success": true }`. Der Widerruf erfolgt sofort: Die nächste Anfrage des Schlüssels erhält `401 Authentication failed`, und der Schlüssel erscheint nicht mehr in `GET /api_keys`. Seine bisherigen Belastungen bleiben im Nutzungsverlauf erhalten. So rotieren Sie einen Schlüssel ohne Ausfallzeit: **1. Ersatz erstellen** Erstellen Sie einen neuen Schlüssel mit denselben Einstellungen und speichern Sie seinen geheimen Wert. **2. Bereitstellen** Stellen Sie Ihre App auf den neuen geheimen Wert um. **3. Alten Schlüssel widerrufen** Sobald sich `lastUsedAt` des alten Schlüssels in `GET /api_keys` nicht mehr ändert, löschen Sie ihn. ## Fehler, die Ihre Aufrufer sehen können | Status | Meldung | Maßnahme | | - | - | - | | `402` | `API key USD spend limit exceeded...` oder dasselbe für DIEM | Erhöhen oder entfernen Sie das Limit oder warten Sie auf den nächsten Zeitraum. Das Konto selbst kann noch Guthaben haben. | | `403` | Das Modell ist durch die Datenschutzeinstellung des Schlüssels nicht erlaubt | Verwenden Sie ein Private-, TEE- oder E2EE-Modell oder ändern Sie `modelPrivacy`. | | `403` | `This API key is restricted to configured IP addresses...` | Fügen Sie die IP des Aufrufers zu `ipAllowlist` hinzu. | | `401` | `Authentication failed` | Der Schlüssel ist widerrufen, abgelaufen oder falsch eingegeben. | | `401` | `Admin API key required` | Ein Inference-Schlüssel hat einen Endpunkt zur Schlüsselverwaltung oder Abrechnung aufgerufen. | | `429` | `Too many API key creation requests...` | Die Schlüsselerstellung ist auf 20 pro Minute begrenzt. Warten Sie und versuchen Sie es dann erneut. | | `400` | `Maximum number of active API keys (500) reached...` | Widerrufen Sie Schlüssel, die Sie nicht mehr verwenden, oder wenden Sie sich an den Support. | Siehe [Fehlercodes](https://docs.venice.ai/de/api-reference/error-codes.md) für die vollständige Liste. ## Best Practices * Bewahren Sie Admin-Schlüssel auf Ihrem Server auf und geben Sie nur Inference-Schlüssel weiter. * Geben Sie jeder App, jeder Umgebung und jedem Kunden einen eigenen Schlüssel, damit jeder einzeln überwacht und widerrufen werden kann. * Tragen Sie Ihre eigene Kennung in `description` ein. Die Nutzungsanalyse beschriftet Schlüssel damit. * Versehen Sie jeden Schlüssel, den Sie an andere weitergeben, mit einem Limit und einem Ablaufdatum, und beschränken Sie Server-zu-Server-Schlüssel mit `ipAllowlist` auf Ihre IPs. ## API-Referenz > [card] [API-Schlüssel erstellen](https://docs.venice.ai/de/api-reference/endpoint/api_keys/create.md) > > Alle beim Erstellen akzeptierten Felder. > [card] [API-Schlüssel aktualisieren](https://docs.venice.ai/de/api-reference/endpoint/api_keys/update.md) > > Limits, Ablaufdatum, Datenschutz und IPs ändern. > [card] [API-Schlüssel auflisten](https://docs.venice.ai/de/api-reference/endpoint/api_keys/list.md) > > Jeder aktive Schlüssel mit seiner Nutzung. > [card] [API-Schlüssel löschen](https://docs.venice.ai/de/api-reference/endpoint/api_keys/delete.md) > > Einen Schlüssel widerrufen. > [card] [Nutzungsanalyse](https://docs.venice.ai/de/api-reference/endpoint/billing/usage-analytics.md) > > Ausgaben nach Schlüssel, Modell und Tag. > [card] [Nutzungsverlauf](https://docs.venice.ai/de/api-reference/endpoint/billing/usage-history.md) > > Jede Belastung mit ihrem API-Schlüssel. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.