Documentation

Authentification

Kunavo utilise exactement le même mécanisme d’authentification qu’OpenAI : un seul jeton Bearer dans l’en-tête Authorization. Seule l’URL de base diffère d’une intégration OpenAI classique.

Chaque appel API est envoyé à https://api.kunavo.com/v1 avec Authorization: Bearer sk-kn-XXX. C’est tout.

URL de base

Le point de terminaison unique qui donne accès à tous les modèles et à toutes les modalités.

Champ	Valeur
URL de base	`https://api.kunavo.com/v1`
Région	Région principale aux États-Unis (Ashburn), desservie par une périphérie multirégionale
TLS	TLS 1.2+ obligatoire. HTTPS uniquement.

La structure des chemins suit les conventions d’OpenAI :

Modalité	Chemin
Conversations	`POST /v1/chat/completions`
Lister les modèles	`GET /v1/models`
Génération d’images	`POST /v1/images/generations`
Édition d’image / image à image	`POST /v1/images/edits`
Génération vidéo	`POST /v1/video/generations`
TTS	`POST /v1/audio/speech`
Musique	`POST /v1/audio/music`

Clés API

Les clés API sont émises depuis /app/keys dans le tableau de bord. Chaque clé :

Commence par sk-kn-, suivi d’au moins 30 caractères aléatoires.
N’est affichée qu’une seule fois lors de sa création — Kunavo ne conserve ensuite qu’un hachage.
Porte un nom lisible par une personne (par ex. prod-web) dans le tableau de bord.
Peut être révoquée à tout moment — la clé renvoie immédiatement une erreur 401 après sa révocation.
Peut avoir sa propre limite de dépenses mensuelle et sa propre liste d’adresses IP autorisées, toutes deux définies depuis /app/keys et appliquées à chaque appel.

Limites de dépenses par clé (facultatif)

Vous pouvez définir une limite de dépenses mensuelle en dollars pour chaque clé. Dès que le montant définitivement comptabilisé pour l’utilisation de cette clé pendant le mois civil en cours dépasserait la limite, les appels effectués avec cette clé renvoient 402 insufficient_quota et aucun montant n’est facturé, jusqu’à la réinitialisation de la limite au début du mois. Vos autres clés ne sont pas affectées : cette limite s’applique à un seul identifiant d’accès, et non au compte.

C’est le garde-fou dont un agent laissé sans surveillance a réellement besoin : le solde du portefeuille est partagé entre toutes les clés et ne peut donc pas, à lui seul, empêcher une boucle incontrôlée de tout dépenser. Attribuez à l’agent sa propre clé avec une limite adaptée à la tâche ; le pire scénario est alors plafonné à ce montant. Une limite de $0 suspend la clé sans la révoquer.

Liste d’adresses IP autorisées par clé (facultatif)

Vous pouvez également restreindre une clé à un ensemble d’adresses. Saisissez une adresse IPv4/IPv6 ou un bloc CIDR par ligne (203.0.113.7, 198.51.100.0/24, 2001:db8::/32) ; les appels utilisant cette clé depuis toute autre adresse sont refusés avec 403 permission_error, sur tous les points de terminaison, y compris /v1/models. Laissez le champ vide pour autoriser toutes les adresses.

L’adresse que nous vérifions est celle observée par notre proxy de périphérie, et non une adresse qu’un client peut déclarer dans un en-tête : une liste d’adresses autorisées ne peut donc pas être contournée en falsifiant X-Forwarded-For. En contrepartie, une clé assortie d’une telle liste cesse de fonctionner dès que son appelant passe à un nouvel hôte, à une nouvelle passerelle NAT ou à un nouveau réseau. Réservez ces listes aux serveurs dont les adresses IP de sortie sont stables, pas aux ordinateurs portables.

En-têtes de requête

Une requête minimale comporte ces deux en-têtes :

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

Chaque point de terminaison accepte aussi la clé dans un en-tête x-api-key à la place de Authorization — l’en-tête envoyé par les SDK Anthropic. Un client conçu pour l’API Anthropic peut ainsi accéder à toutes les routes, y compris /v1/models, sans en-tête personnalisé. Si une requête contient les deux, c’est Authorization qui est lu. La limite de dépenses et la liste d’adresses IP autorisées de la clé s’appliquent quel que soit l’en-tête utilisé.

Facultatif, mais recommandé : User-Agent pour identifier votre application. Nous enregistrons les agents utilisateurs dans votre tableau de bord /app/usage afin de faciliter le débogage des sources de requêtes.

Utiliser le SDK OpenAI

La plupart des équipes continuent d’utiliser le SDK officiel OpenAI et remplacent simplement base_url. Cette méthode fonctionne avec Python (v1.x+) et 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",
});

Le SDK OpenAI utilise baseURL avec Node et base_url avec Python. Les deux pointent vers le même point de terminaison.

Rotation des clés

Bonne pratique : faites tourner les clés API chaque trimestre ou dès qu’une clé risque d’avoir été divulguée. Kunavo vous permet d’avoir simultanément plusieurs clés par compte. La rotation se fait donc avec une période de chevauchement sans interruption.

# 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-..."

Une clé révoquée renvoie immédiatement une erreur 401. Il n’y a aucun délai de grâce : vérifiez que le trafic utilise la nouvelle clé avant de révoquer l’ancienne.

Remarques sur la sécurité

N’exposez jamais les clés côté client. Le code du navigateur et les lots d’applications mobiles sont publics. Faites toujours transiter les requêtes par votre serveur.
Limitez la portée des clés. Des clés distinctes par projet vous permettent de révoquer une clé sans affecter les autres charges de travail. Chacune peut aussi avoir sa propre limite de dépenses et sa propre liste d’adresses IP autorisées, ce qui limite à la fois les coûts et les origines autorisées pour l’utilisation d’une clé divulguée.
Surveillez le tableau de bord. La page /app/usage présente le trafic ventilé par clé, ce qui facilite la détection d’une activité inattendue.
Signalez toute fuite présumée. Écrivez à support@kunavo.com et nous vous aiderons à invalider la clé et à examiner l’incident.