Dokumentation

Authentifizierung

Kunavo verwendet genau dieselbe Authentifizierung wie OpenAI: ein einzelnes Bearer-Token im Authorization-Header. Gegenüber einer typischen OpenAI-Integration ändert sich nur die Basis-URL.

Jeder API-Aufruf geht an https://api.kunavo.com/v1 und verwendet Authorization: Bearer sk-kn-XXX. Das ist alles.

Basis-URL

Der einzige Endpunkt für jedes Modell und jede Modalität.

Feld	Wert
Basis-URL	`https://api.kunavo.com/v1`
Region	Primärstandort USA (Ashburn), mit vorgeschaltetem Edge-Netzwerk in mehreren Regionen
TLS	TLS 1.2+ ist vorgeschrieben. Nur HTTPS.

Der Pfadaufbau folgt den Konventionen von OpenAI:

Modalität	Pfad
Chat	`POST /v1/chat/completions`
Modelle auflisten	`GET /v1/models`
Bildgenerierung	`POST /v1/images/generations`
Bildbearbeitung / i2i	`POST /v1/images/edits`
Videogenerierung	`POST /v1/video/generations`
TTS	`POST /v1/audio/speech`
Musik	`POST /v1/audio/music`

API-Schlüssel

API-Schlüssel werden im Dashboard unter /app/keys erstellt. Jeder Schlüssel:

Beginnt mit sk-kn-, gefolgt von mindestens 30 zufälligen Zeichen.
Wird bei der Erstellung einmalig angezeigt – danach speichert Kunavo nur noch einen Hash.
Hat einen lesbaren Namen (z. B. prod-web), der im Dashboard angezeigt wird.
Kann jederzeit widerrufen werden – unmittelbar nach dem Widerruf schlägt die Authentifizierung mit dem Schlüssel mit 401 fehl.
Kann ein eigenes monatliches Ausgabenlimit und eine eigene IP-Zulassungsliste haben. Beides wird unter /app/keys festgelegt und bei jedem Aufruf durchgesetzt.

Ausgabenlimits pro Schlüssel (optional)

Für jeden Schlüssel können Sie ein monatliches Ausgabenlimit in US-Dollar festlegen. Sobald die abgerechnete Nutzung des Schlüssels im aktuellen Kalendermonat das Limit überschreiten würde, liefern Aufrufe mit diesem Schlüssel 402 insufficient_quota und es wird nichts berechnet, bis das Limit zu Monatsbeginn zurückgesetzt wird. Ihre anderen Schlüssel sind davon nicht betroffen – das Limit gilt für einzelne Anmeldedaten, nicht für das Konto.

Damit lässt sich ein unbeaufsichtigter Agent wirksam begrenzen: Das Guthaben im Wallet wird von allen Schlüsseln gemeinsam genutzt. Allein kann es daher nicht verhindern, dass eine einzelne außer Kontrolle geratene Schleife das gesamte Guthaben aufbraucht. Geben Sie dem Agenten einen eigenen Schlüssel mit einem auf die Aufgabe abgestimmten Limit; so ist der mögliche Höchstbetrag begrenzt. Ein Limit von $0 pausiert den Schlüssel, ohne ihn zu widerrufen.

IP-Zulassungsliste pro Schlüssel (optional)

Ein Schlüssel kann auf eine bestimmte Menge von Adressen beschränkt werden. Geben Sie pro Zeile eine IPv4- oder IPv6-Adresse oder einen CIDR-Block ein (203.0.113.7, 198.51.100.0/24, 2001:db8::/32). Aufrufe mit diesem Schlüssel von anderen Adressen werden mit 403 permission_error abgelehnt – an jedem Endpunkt, einschließlich /v1/models. Lassen Sie das Feld leer, um alle Adressen zuzulassen.

Wir prüfen die Adresse, die unser Edge-Proxy beobachtet hat, nicht eine Adresse, die ein Client in einem Header angeben kann. Eine Zulassungsliste lässt sich daher nicht durch Fälschen von X-Forwarded-For umgehen. Umgekehrt funktioniert ein Schlüssel mit Zulassungsliste nicht mehr, sobald der Aufrufer zu einem neuen Host, NAT-Gateway oder Netzwerk wechselt. Verwenden Sie Zulassungslisten für Server mit stabilen ausgehenden IP-Adressen, nicht für Laptops.

Anfrageheader

Eine minimale Anfrage enthält diese beiden Header:

Authorization: Bearer sk-kn-...
Content-Type: application/json

Jeder Endpunkt liest den Schlüssel auch aus einem x-api-key-Header – dem Header, den die Anthropic-SDKs senden – statt aus Authorization. So erreicht ein für die Anthropic-API entwickelter Client jede Route, einschließlich /v1/models, ohne benutzerdefinierten Header. Wenn eine Anfrage beide Header enthält, wird Authorization verwendet. Das Ausgabenlimit und die IP-Zulassungsliste des Schlüssels gelten unabhängig davon, über welchen Header er übermittelt wird.

Optional, aber empfohlen: User-Agent zur Kennzeichnung Ihrer App. Wir protokollieren User-Agents in Ihrem /app/usage-Dashboard, damit sich die Herkunft von Anfragen nachvollziehen lässt.

OpenAI-SDK verwenden

Die meisten Teams verwenden weiterhin das offizielle OpenAI-SDK und tauschen lediglich base_url aus. Das funktioniert sowohl mit Python (v1.x+) als auch mit Node (v4.x+).

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KUNAVO_API_KEY"],
    base_url="https://api.kunavo.com/v1",
)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KUNAVO_API_KEY,
  baseURL: "https://api.kunavo.com/v1",
});

Das OpenAI-SDK verwendet in Node baseURL und in Python base_url. Beide verweisen auf denselben Endpunkt.

Schlüsselrotation

Bewährte Praxis: Rotieren Sie API-Schlüssel vierteljährlich oder sobald ein Schlüssel möglicherweise offengelegt wurde. Kunavo ermöglicht mehrere Schlüssel pro Konto gleichzeitig. Dadurch lässt sich die Rotation mit einer reibungslosen Überschneidung durchführen, statt abrupt umzustellen.

# 1. Create a new key in /app/keys, set its name to e.g. "prod-2026-Q2"
# 2. Deploy new key to your servers
# 3. Verify traffic is flowing on the new key (dashboard shows usage)
# 4. Revoke the old key from /app/keys → it 401s immediately

# In code, swap one env var:
export KUNAVO_API_KEY="sk-kn-new-..."

Ein widerrufener Schlüssel schlägt sofort mit 401 fehl. Es gibt keine Übergangsfrist – stellen Sie sicher, dass Anfragen bereits über den neuen Schlüssel laufen, bevor Sie den alten widerrufen.

Sicherheitshinweise

Schlüssel niemals clientseitig offenlegen. Browsercode und mobile App-Bundles sind öffentlich. Leiten Sie Anfragen immer über Ihren Server weiter.
Schlüssel eng begrenzen. Mit separaten Schlüsseln pro Projekt können Sie einen Schlüssel widerrufen, ohne andere Workloads zu beeinträchtigen. Außerdem können Sie jedem Schlüssel ein eigenes Ausgabenlimit und eine eigene IP-Zulassungsliste zuweisen, sodass die Nutzung eines offengelegten Schlüssels sowohl hinsichtlich der Kosten als auch der Herkunft begrenzt ist.
Dashboard überwachen. Auf der Seite /app/usage wird der Datenverkehr nach Schlüssel aufgeschlüsselt angezeigt – so lassen sich ungewöhnliche Aktivitäten leichter erkennen.
Vermutete Offenlegungen melden. Schreiben Sie eine E-Mail an support@kunavo.com. Wir helfen Ihnen beim Ungültigmachen des Schlüssels und bei der Überprüfung des Vorfalls.