> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-ce69695c.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Einführung
> Vollständige Venice API-Referenz zu Bearer-Authentifizierung, OpenAI-Kompatibilität, Response-Headern, Fehlerbehandlung und allen REST-Endpunkten.
Die Venice API bietet HTTP-basierte REST- und Streaming-Schnittstellen für die Entwicklung von KI-Anwendungen mit unzensierten Modellen und privater Inferenz. Sie können Texterzeugung, Bildgenerierung, Embeddings und mehr erstellen — alles ohne restriktive Inhaltsrichtlinien. Integrationsbeispiele und SDKs sind in der [Dokumentation](/overview/getting-started) verfügbar. Unsere API-Referenz ist auch als [OpenAPI-YAML-Spezifikation](https://api.venice.ai/doc/api/swagger.yaml) verfügbar.
## Authentifizierung
Die Venice API verwendet API-Schlüssel zur Authentifizierung. Erstellen und verwalten Sie Ihre API-Schlüssel in Ihren [API-Einstellungen](https://venice.ai/settings/api?utm_source=venice-api-documentation).
Die meisten API-Anfragen erfordern HTTP-Bearer-Authentifizierung. Einige Discovery-Endpunkte — darunter `GET /models`, `GET /models/traits`, `GET /models/compatibility_mapping` und `GET /image/styles` — sind ohne Schlüssel lesbar:
```
Authorization: Bearer VENICE_API_KEY
```
Ihr API-Schlüssel ist ein Geheimnis. Geben Sie ihn nicht weiter und legen Sie ihn nicht in clientseitigem Code offen.
### Schlüsseltypen
Schlüssel sind entweder `INFERENCE` oder `ADMIN`. Inference-Schlüssel können die Inferenz-Endpunkte aufrufen — Chat, Bild, Video, Audio, Embeddings und die Augmentierungs-Endpunkte. Kontoverwaltungs-Endpunkte erfordern einen `ADMIN`-Schlüssel:
| Endpunkt | Erforderlicher Schlüssel |
| - | - |
| `GET/POST/PATCH/DELETE /api_keys`, `GET /api_keys/{id}` | `ADMIN` |
| `GET /api_keys/rate_limits/log` | `ADMIN` |
| `GET /api_keys/rate_limits` | Beide |
| `GET /billing/balance`, `/billing/usage-history`, `/billing/usage-analytics` | `ADMIN` |
Der Aufruf eines Admin-only-Endpunkts mit einem Inference-Schlüssel gibt `401` mit `{"error":"Admin API key required"}` zurück. Beachten Sie, dass `GET /api_keys/rate_limits` die einzige Ausnahme in dieser Gruppe ist — er funktioniert mit beiden Schlüsseltypen.
## OpenAI-Kompatibilität
Die API von Venice implementiert die OpenAI-API-Spezifikation und stellt damit die Kompatibilität mit bestehenden OpenAI-Clients und -Tools sicher. So können Sie Venice über die gewohnte OpenAI-Schnittstelle einbinden und gleichzeitig auf die einzigartigen Funktionen von Venice und seine unzensierten Modelle zugreifen.
### Setup
Konfigurieren Sie Ihren Client so, dass er die Base-URL von Venice (`https://api.venice.ai/api/v1`) verwendet, und stellen Sie Ihre erste Anfrage:
```bash curl theme={null}
curl https://api.venice.ai/api/v1/chat/completions \
-H "Authorization: Bearer $VENICE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "venice-uncensored",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```javascript JavaScript theme={null}
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.VENICE_API_KEY,
baseURL: "https://api.venice.ai/api/v1",
});
const response = await client.chat.completions.create({
model: "venice-uncensored",
messages: [{ role: "user", content: "Hello!" }]
});
console.log(response.choices[0].message.content);
```
```python Python theme={null}
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ.get("VENICE_API_KEY"),
base_url="https://api.venice.ai/api/v1"
)
response = client.chat.completions.create(
model="venice-uncensored",
messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)
```
## Venice-spezifische Funktionen
### System-Prompts
Venice stellt Standard-System-Prompts bereit, die unzensierte und natürliche Modellantworten gewährleisten sollen. Sie haben zwei Optionen zum Umgang mit System-Prompts:
1. **Standardverhalten**: Ihre System-Prompts werden an die Defaults von Venice angehängt
2. **Benutzerdefiniertes Verhalten**: Die System-Prompts von Venice vollständig deaktivieren
#### Venice-System-Prompts deaktivieren
Verwenden Sie die Option `venice_parameters`, um die Standard-System-Prompts von Venice zu entfernen:
```bash curl theme={null}
curl https://api.venice.ai/api/v1/chat/completions \
-H "Authorization: Bearer $VENICE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "venice-uncensored",
"messages": [
{"role": "system", "content": "Your custom system prompt"},
{"role": "user", "content": "Why is the sky blue?"}
],
"venice_parameters": {
"include_venice_system_prompt": false
}
}'
```
```javascript JavaScript theme={null}
const completion = await client.chat.completions.create({
model: "venice-uncensored",
messages: [
{
role: "system",
content: "Your custom system prompt",
},
{
role: "user",
content: "Why is the sky blue?",
},
],
venice_parameters: {
include_venice_system_prompt: false,
},
});
```
```python Python theme={null}
response = client.chat.completions.create(
model="venice-uncensored",
messages=[
{"role": "system", "content": "Your custom system prompt"},
{"role": "user", "content": "Why is the sky blue?"}
],
extra_body={
"venice_parameters": {
"include_venice_system_prompt": False
}
}
)
```
### Venice-Parameter
Das Objekt `venice_parameters` ermöglicht den Zugriff auf Venice-spezifische Funktionen, die in der Standard-OpenAI-API nicht verfügbar sind:
| Parameter | Typ | Beschreibung | Standard |
| - | - | - | - |
| `character_slug` | string | Der Character-Slug eines öffentlichen Venice-Characters (auf der veröffentlichten Character-Seite als "Public ID" auffindbar) | - |
| `strip_thinking_response` | boolean | Entfernt ``-Blöcke aus der Antwort (Modelle, die das ältere ``-Tag-Format verwenden). Siehe [Reasoning-Modelle](/guides/features/reasoning-models). | `false` |
| `disable_thinking` | boolean | Bei unterstützten Reasoning-Modellen wird das Thinking deaktiviert und die ``-Blöcke werden aus der Antwort entfernt | `false` |
| `enable_web_search` | string | Web-Search für diese Anfrage aktivieren (`off`, `on`, `auto` — auto aktiviert je nach Ermessen des Modells)
Es fallen zusätzliche nutzungsbasierte Kosten an, siehe [Preise](/overview/pricing#web-search-and-scraping). | `off` |
| `enable_web_scraping` | boolean | Aktiviert das Web-Scraping von bis zu 5 URLs, die in der Benutzernachricht erkannt werden. Gescrapter Inhalt ergänzt Antworten und umgeht die Web-Search. Nur erfolgreich gescrapte URLs werden berechnet.
Es fallen zusätzliche nutzungsbasierte Kosten an, siehe [Preise](/overview/pricing#web-search-and-scraping). | `false` |
| `enable_x_search` | boolean | Aktiviert die native Suche von xAI (Web + X/Twitter) für unterstützte Grok-Modelle (z. B. `grok-4-20-beta`). Liefert qualitativ hochwertigere Suchergebnisse durch Nutzung der xAI-Suchinfrastruktur. Bei Aktivierung wird die Standard-Web-Search von Venice umgangen.
Es fallen zusätzliche nutzungsbasierte Kosten an, siehe [Preise](/overview/pricing#web-search-and-scraping). | `false` |
| `enable_web_citations` | boolean | Wenn Web-Search aktiviert ist, fordert dies das LLM auf, seine Quellen mit hochgestellten Caret-Zeichen zu zitieren — `^1^` für eine einzelne Quelle und `^1,2^` für mehrere. Klammerformen wie `[1]`, `(1)` und `1` werden explizit unterdrückt | `false` |
| `include_search_results_in_stream` | boolean | Experimentell: Suchergebnisse als ersten ausgegebenen Chunk in den Stream aufnehmen | `false` |
| `return_search_results_as_documents` | boolean | Suchergebnisse als OpenAI-kompatiblen Tool-Call namens `venice_web_search_documents` für die LangChain-Integration bereitstellen | `false` |
| `include_venice_system_prompt` | boolean | Ob die Standard-System-Prompts von Venice zusätzlich zu den angegebenen System-Prompts eingebunden werden sollen | `true` |
Diese Parameter können auch als Modell-Suffixe an den Modellnamen angehängt werden (z. B. `zai-org-glm-5:enable_web_search=auto`). Details siehe [Model Feature Suffixes](/api-reference/endpoint/chat/model_feature_suffix).
### Prompt Caching
Venice unterstützt Prompt Caching auf ausgewählten Modellen, um Latenz und Kosten für wiederholten Inhalt zu reduzieren. Für unterstützte Modelle cached Venice System-Prompts automatisch — es sind keine Code-Änderungen erforderlich. Sie können Inhalte auch manuell zum Caching markieren, indem Sie die Eigenschaft `cache_control` am Nachrichteninhalt verwenden.
| Parameter | Typ | Beschreibung |
| - | - | - |
| `prompt_cache_key` | string | Optionaler Routing-Hinweis, um Cache-Hit-Raten zu verbessern. Wenn angegeben, leitet Venice Anfragen an dieselbe Backend-Infrastruktur weiter und erhöht so die Wahrscheinlichkeit von Cache-Treffern bei mehrstufigen Konversationen. |
Siehe [Prompt Caching](/guides/features/prompt-caching) für Details zur Funktionsweise des Caching, zur Abrechnung und zu Best Practices.
## Response-Header-Referenz
Alle Antworten der Venice API enthalten HTTP-Header, die Metadaten zur Anfrage, Rate-Limits, Modellinformationen und Kontoguthaben bereitstellen. Zusätzlich zu Fehlercodes aus API-Antworten können Sie diese Header prüfen, um die eindeutige ID einer bestimmten API-Anfrage zu erhalten, Rate-Limits zu überwachen und Ihr Kontoguthaben zu verfolgen.
Venice empfiehlt, Request-IDs (`CF-RAY`-Header) in Produktivumgebungen zu protokollieren, um die Problemanalyse mit unserem Support-Team bei Bedarf effizienter zu gestalten.
Die folgende Tabelle bietet eine umfassende Referenz aller Header, denen Sie begegnen können:
| Header | Typ | Zweck | Wann zurückgegeben |
| - | - | - | - |
| **Standard-HTTP-Header** | | | |
| `Content-Type` | string | MIME-Typ des Response-Body (`application/json`, `text/csv`, `image/png` etc.) | Immer |
| `Content-Encoding` | string | Verwendete Kodierung zur Komprimierung des Response-Body (`gzip`, `br`) | Wenn der Client den Header `Accept-Encoding` sendet |
| `Content-Disposition` | string | Wie der Inhalt angezeigt werden soll (z. B. `attachment; filename=export.csv`) | Beim Herunterladen von Dateien oder Exporten |
| `Date` | string | Zeitstempel im RFC-7231-Format, wann die Antwort generiert wurde | Immer |
| **Request-Identifikation** | | | |
| `CF-RAY` | string | Eindeutiger Identifier für diese API-Anfrage, verwendet für Troubleshooting und Support-Anfragen | Immer |
| `x-venice-version` | string | Aktuelle Version/Revision des Venice-API-Dienstes (z. B. `20250828.222653`) | Immer |
| `x-venice-timestamp` | string | Server-Zeitstempel, wann die Anfrage verarbeitet wurde (ISO-8601-Format) | Wenn Timestamp-Tracking aktiviert ist |
| `x-venice-host-name` | string | Hostname des Servers, der die Anfrage verarbeitet hat | Fehlerantworten und Debugging-Szenarien |
| **Modellinformationen** | | | |
| `x-venice-model-id` | string | Eindeutiger Identifier des für die Anfrage verwendeten KI-Modells (z. B. `venice-01-lite`) | Inferenz-Endpoints, die KI-Modelle verwenden |
| `x-venice-model-name` | string | Anzeigename des verwendeten KI-Modells (z. B. `Venice Lite`) | Inferenz-Endpoints, die KI-Modelle verwenden |
| `x-venice-model-router` | string | Router/Backend-Dienst, der die Modell-Inferenz abgewickelt hat | Inferenz-Endpoints, wenn Routing-Info verfügbar ist |
| `x-venice-model-deprecation-warning` | string | Warnmeldung für Modelle, die zur Deprecation vorgesehen sind | Bei Verwendung eines deprecated Modells |
| `x-venice-model-deprecation-date` | string | Datum, an dem das Modell deprecated wird (ISO-8601-Datum) | Bei Verwendung eines deprecated Modells |
| **Rate-Limit-Informationen** | | | |
| `x-ratelimit-limit-requests` | number | Maximale Anzahl von Anfragen im aktuellen Zeitfenster | Alle authentifizierten Anfragen |
| `x-ratelimit-remaining-requests` | number | Anzahl der im aktuellen Zeitfenster verbleibenden Anfragen | Alle authentifizierten Anfragen |
| `x-ratelimit-reset-requests` | number | Unix-Zeitstempel, wann das Request-Rate-Limit zurückgesetzt wird | Alle authentifizierten Anfragen |
| `x-ratelimit-limit-tokens` | number | Maximale Anzahl von Tokens (Prompt + Completion), die im Zeitfenster erlaubt sind | Alle authentifizierten Anfragen |
| `x-ratelimit-remaining-tokens` | number | Anzahl der im aktuellen Zeitfenster verbleibenden Tokens | Alle authentifizierten Anfragen |
| `x-ratelimit-reset-tokens` | number | Dauer in Sekunden bis zum Zurücksetzen des Token-Rate-Limits | Alle authentifizierten Anfragen |
| `x-ratelimit-type` | string | Art des angewendeten Rate-Limits (`user`, `api_key`, `global`) | Wenn Rate-Limiting durchgesetzt wird |
| **Paginierungs-Header** | | | |
| `x-pagination-limit` | number | Anzahl der Elemente pro Seite | Paginierte Endpoints |
| `x-pagination-page` | number | Aktuelle Seitenzahl (1-basiert) | Paginierte Endpoints |
| `x-pagination-total` | number | Gesamtanzahl der Elemente über alle Seiten | Paginierte Endpoints |
| `x-pagination-total-pages` | number | Gesamtanzahl der Seiten | Paginierte Endpoints |
| **Kontoguthaben-Informationen** | | | |
| `x-venice-balance-diem` | string | Ihr DIEM-Token-Guthaben vor der Verarbeitung der Anfrage | Alle authentifizierten Anfragen |
| `x-venice-balance-usd` | string | Ihr USD-Credit-Guthaben vor der Verarbeitung der Anfrage | Alle authentifizierten Anfragen |
| **Content-Safety-Header** | | | |
| `x-venice-is-blurred` | string | Gibt an, ob das generierte Bild aufgrund von Inhaltsrichtlinien unscharf gemacht wurde (`true`/`false`) | Bildgenerierung mit aktiviertem Safe Venice |
| `x-venice-is-content-violation` | string | Gibt an, ob der Inhalt gegen die Inhaltsrichtlinien von Venice verstößt (`true`/`false`) | Endpoints für Inhaltsgenerierung |
| `x-venice-is-adult-model-content-violation` | string | Gibt an, ob der Inhalt gegen die Inhaltsrichtlinien für Adult-Modelle verstößt (`true`/`false`) | Endpoints für Bildgenerierung |
| `x-venice-contains-minor` | string | Gibt an, ob das Bild Minderjährige enthält (`true`/`false`) | Endpoints für Bildanalyse mit Altersbestimmung |
| **Client-Informationen** | | | |
| `x-venice-middleface-version` | string | Version des Venice-Middleface-Clients | Anfragen von Venice-Middleface-Clients |
| `x-venice-mobile-version` | string | Version der Venice-Mobile-App | Anfragen aus mobilen Anwendungen |
| `x-venice-request-timestamp-ms` | number | Vom Client bereitgestellter Request-Zeitstempel in Millisekunden | Wenn der Client einen Zeitstempel in der Anfrage angibt |
| `x-venice-control-instance` | string | Control-Instance-Identifier zum Debugging | Endpoints für Bildgenerierung zum Debugging |
| **Authentifizierungs-Header** | | | |
| `x-auth-refreshed` | string | Gibt an, ob der Authentifizierungs-Token während der Anfrage aktualisiert wurde (`true`/`false`) | Wenn Authentifizierungs-Tokens automatisch aktualisiert werden |
| `x-retry-count` | number | Anzahl der Wiederholungsversuche für die Anfrage | Wenn Wiederholungen der Anfrage auftreten |
### Wichtige Hinweise
* **Header-Namens-Schreibweise**: HTTP-Header sind case-insensitive, aber Venice verwendet aus Konsistenzgründen Kleinschreibung mit Bindestrichen
* **String-Werte**: Boolesche Werte in Headern werden als Strings zurückgegeben (`"true"` oder `"false"`)
* **Numerische Werte**: Große Zahlen und Guthabenwerte können als Strings zurückgegeben werden, um Genauigkeitsverlust zu vermeiden
* **Optionale Header**: Nicht alle Header werden in jeder Antwort zurückgegeben; die Verfügbarkeit hängt vom Endpoint und Request-Kontext ab
* **Komprimierung**: Verwenden Sie `Accept-Encoding: gzip, br` in Anfragen, um dort, wo unterstützt, komprimierte Antworten zu erhalten
### Beispiel: Auf Response-Header zugreifen
```javascript theme={null}
// After making an API request, access headers from the response object
const requestId = response.headers.get('CF-RAY');
const remainingRequests = response.headers.get('x-ratelimit-remaining-requests');
const remainingTokens = response.headers.get('x-ratelimit-remaining-tokens');
const usdBalance = response.headers.get('x-venice-balance-usd');
// Check for model deprecation warnings
const deprecationWarning = response.headers.get('x-venice-model-deprecation-warning');
if (deprecationWarning) {
console.warn(`Model Deprecation: ${deprecationWarning}`);
}
```
## Best Practices
1. **Rate-Limiting**: Überwachen Sie die Header `x-ratelimit-remaining-requests` und `x-ratelimit-remaining-tokens` und implementieren Sie exponentielles Backoff
2. **Guthaben-Überwachung**: Verfolgen Sie die Header `x-venice-balance-usd` und `x-venice-balance-diem`, um Dienstunterbrechungen zu vermeiden
3. **System-Prompts**: Testen Sie mit und ohne Venice-System-Prompts, um die beste Anpassung an Ihren Use Case zu finden
4. **API-Schlüssel**: Halten Sie Ihre API-Schlüssel sicher und rotieren Sie sie regelmäßig
5. **Request-Logging**: Protokollieren Sie die Werte des `CF-RAY`-Headers zur Problemanalyse mit dem Support
6. **Modell-Deprecation**: Prüfen Sie bei der Modellnutzung auf `x-venice-model-deprecation-warning`-Header
## Unterschiede zur OpenAI-API
Während Venice eine hohe Kompatibilität mit der OpenAI-API-Spezifikation aufrechterhält, gibt es einige wesentliche Unterschiede:
1. **venice\_parameters**: Zusätzliche Konfigurationen wie `enable_web_search`, `character_slug` und `strip_thinking_response` für erweiterte Funktionalität
2. **System-Prompts**: Venice hängt Ihre System-Prompts an Defaults an, die auf unzensierte Antworten optimiert sind (deaktivieren mit `include_venice_system_prompt: false`)
3. **Modell-Ökosystem**: Venice bietet eine eigene [Modell-Auswahl](/overview/models) inklusive unzensierter und Reasoning-Modelle — verwenden Sie Venice-Modell-IDs statt OpenAI-Mappings
4. **Response-Header**: Einzigartige Header für Guthaben-Tracking (`x-venice-balance-usd`, `x-venice-balance-diem`), Modell-Deprecation-Warnungen und Content-Safety-Flags
5. **Inhaltsrichtlinien**: Großzügigere Richtlinien mit dedizierten unzensierten Modellen und optionaler Inhaltsfilterung
6. **Embeddings-Eingabe**: `input` muss ein String oder ein Array von Strings sein. Token-ID-Arrays werden mit HTTP 400 abgelehnt. Bei LangChain `OpenAIEmbeddings` muss `check_embedding_ctx_length=False` gesetzt werden
## API-Stabilität
Venice gewährleistet Abwärtskompatibilität für v1-Endpoints und -Parameter. Für die Modell-Lifecycle-Policy, Deprecation-Hinweise und Migrations-Anleitung siehe [Deprecations](/overview/deprecations).
## OpenAPI-Spezifikation & Rohdaten
Für den programmatischen Zugriff auf die Venice-API-Dokumentation und -Daten — einschließlich der Nutzung mit RAG (Retrieval-Augmented Generation) — stehen die folgenden Ressourcen zur Verfügung:
* [OpenAPI-Spec (YAML)](https://api.venice.ai/doc/api/swagger.yaml) — die vollständige API-Spezifikation im YAML-Format
* [API-Docs-Quelle](https://github.com/veniceai/api-docs/archive/refs/heads/main.zip) — alle Dokumentationsseiten (`.mdx`-Format) als herunterladbares Archiv
***
Request-Felder, die in dieser Dokumentation nicht aufgeführt sind, können durchgereicht werden, sind aber nicht validiert und ihr Verhalten ist nicht garantiert.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.