Documentazione

Autenticazione

Kunavo autentica esattamente come OpenAI: un unico token bearer nell'intestazione Authorization. L'unica differenza rispetto a una tipica integrazione OpenAI è l'URL di base.

Ogni chiamata API viene inviata a https://api.kunavo.com/v1 con Authorization: Bearer sk-kn-XXX. Tutto qui.

URL di base

L'unico endpoint che serve tutti i modelli e tutte le modalità.

Campo	Valore
URL di base	`https://api.kunavo.com/v1`
Regione	Ashburn, Stati Uniti, primario; edge frontale multiregionale
TLS	TLS 1.2 o superiore obbligatorio. Solo HTTPS.

La struttura dei percorsi segue le convenzioni OpenAI:

Modalità	Percorso
Chat	`POST /v1/chat/completions`
Elenca i modelli	`GET /v1/models`
Generazione di immagini	`POST /v1/images/generations`
Modifica immagini / i2i	`POST /v1/images/edits`
Generazione video	`POST /v1/video/generations`
TTS	`POST /v1/audio/speech`
Musica	`POST /v1/audio/music`

Chiavi API

Le chiavi API si generano da /app/keys nella dashboard. Ogni chiave:

Inizia con sk-kn- seguito da almeno 30 caratteri casuali.
Viene mostrata una sola volta al momento della creazione: in seguito Kunavo conserva solo un hash.
Ha un nome leggibile (ad es. prod-web) da visualizzare nella dashboard.
Può essere revocata in qualsiasi momento: subito dopo la revoca, le richieste con la chiave restituiscono 401.
Può avere un limite di spesa mensile e una lista di IP consentiti propri, entrambi configurati da /app/keys e applicati a ogni chiamata.

Limiti di spesa per chiave (facoltativi)

Per ogni chiave puoi impostare un limite di spesa mensile in dollari. Quando l'utilizzo contabilizzato di quella chiave nel mese di calendario corrente comporterebbe il superamento del limite, le chiamate effettuate con essa restituiscono 402 insufficient_quota e non viene addebitato nulla, fino al ripristino del limite all'inizio del mese. Le altre chiavi non ne risentono: è un tetto per una singola credenziale, non per l'account.

È la protezione che serve davvero a un agente non supervisionato: il saldo del wallet è condiviso da tutte le chiavi, quindi da solo non può impedire a un singolo ciclo fuori controllo di esaurire tutto. Assegna all'agente una chiave dedicata con un limite commisurato al lavoro e la spesa massima sarà circoscritta a quella cifra. Un limite di $0 sospende la chiave senza revocarla.

Lista di IP consentiti per chiave (facoltativa)

Puoi anche limitare una chiave a un insieme di indirizzi. Inserisci un indirizzo IPv4/IPv6 o un blocco CIDR per riga (203.0.113.7, 198.51.100.0/24, 2001:db8::/32); le chiamate che presentano quella chiave da qualsiasi altro indirizzo vengono rifiutate con 403 permission_error, su tutti gli endpoint, incluso /v1/models. Lascia il campo vuoto per consentire qualsiasi indirizzo.

Controlliamo l'indirizzo osservato dal nostro proxy edge, non uno che il client può dichiarare in un'intestazione: quindi non è possibile aggirare la lista falsificando X-Forwarded-For. D'altra parte, una chiave con lista di IP consentiti smette di funzionare appena il chiamante passa a un nuovo host, gateway NAT o rete. Limita le liste ai server con un'uscita di rete stabile, non ai portatili.

Intestazioni delle richieste

Una richiesta minima include queste due intestazioni:

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

Ogni endpoint legge la chiave anche dall'intestazione x-api-key, quella inviata dagli SDK Anthropic, al posto di Authorization; così un client creato per l'API Anthropic raggiunge ogni route, incluso /v1/models, senza un'intestazione personalizzata. Se una richiesta contiene entrambe, viene letta Authorization. Il limite di spesa e la lista di IP consentiti della chiave si applicano a prescindere dall'intestazione usata per inviarla.

Facoltativo ma consigliato: User-Agent per identificare la tua app. Nella dashboard /app/usage registriamo gli user-agent per aiutare a individuare l'origine delle richieste.

Uso dell'SDK OpenAI

La maggior parte dei team continua a usare l'SDK ufficiale OpenAI e sostituisce soltanto base_url. Funziona così sia con Python (v1.x+) sia con 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",
});

In Node l'SDK OpenAI usa baseURL, mentre in Python usa base_url. Entrambi puntano allo stesso endpoint.

Rotazione delle chiavi

Buona prassi: ruota le chiavi API ogni trimestre o ogni volta che è possibile che una chiave sia stata esposta. Kunavo consente di avere più chiavi per account contemporaneamente, quindi la rotazione prevede una semplice sovrapposizione e non un passaggio brusco.

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

Una chiave revocata restituisce subito 401. Non c'è alcun periodo di tolleranza: assicurati che il traffico usi la nuova chiave prima di revocare quella vecchia.

Note di sicurezza

Non esporre mai le chiavi lato client. Il codice del browser e i pacchetti per dispositivi mobili sono pubblici. Passa sempre dal tuo server.
Limita attentamente l'ambito delle chiavi. Usa chiavi diverse per ogni progetto, così puoi revocarle senza influire sugli altri carichi di lavoro; ciascuna può inoltre avere un proprio limite di spesa e una lista di IP consentiti, circoscrivendo sia il costo sia l'origine in caso di divulgazione.
Monitora la dashboard. La pagina /app/usage mostra il traffico suddiviso per chiave: è più facile individuare attività inattese.
Segnala le possibili divulgazioni. Scrivi a support@kunavo.com e ti aiuteremo a invalidare la chiave e a esaminare l'incidente.