Documentación

Autenticación

Kunavo se autentica exactamente igual que OpenAI: con un único token bearer en el encabezado Authorization. El único cambio respecto a una integración habitual con OpenAI es la URL base.

Todas las llamadas a la API se envían a https://api.kunavo.com/v1 con Authorization: Bearer sk-kn-XXX. Eso es todo.

URL base

El único endpoint que da acceso a todos los modelos y todas las modalidades.

Campo	Valor
URL base	`https://api.kunavo.com/v1`
Región	Región principal en EE. UU. (Ashburn), con una capa perimetral multirregional
TLS	TLS 1.2 o superior obligatorio. Solo HTTPS.

La estructura de las rutas sigue las convenciones de OpenAI:

Modalidad	Ruta
Chat	`POST /v1/chat/completions`
Listar modelos	`GET /v1/models`
Generación de imágenes	`POST /v1/images/generations`
Edición de imágenes / i2i	`POST /v1/images/edits`
Generación de vídeo	`POST /v1/video/generations`
TTS	`POST /v1/audio/speech`
Música	`POST /v1/audio/music`

Claves de API

Las claves de API se generan desde /app/keys en el panel de control. Cada clave:

Empieza por sk-kn- y va seguida de 30 o más caracteres aleatorios.
Se muestra una sola vez al crearla; después, Kunavo solo almacena un hash.
Tiene un nombre legible para las personas (por ejemplo, prod-web) en el panel de control.
Se puede revocar en cualquier momento; tras la revocación, la clave devuelve 401 de inmediato.
Puede tener su propio límite de gasto mensual y su propia lista de IP permitidas. Ambos se configuran desde /app/keys y se aplican en cada llamada.

Límites de gasto por clave (opcional)

Puedes establecer un límite de gasto mensual en dólares para cada clave. Cuando el uso liquidado de esa clave durante el mes natural actual vaya a superar el límite, las llamadas hechas con ella devolverán 402 insufficient_quota y no se cobrará nada hasta que el límite se restablezca al comienzo del mes. Las demás claves no se ven afectadas: este límite se aplica a una credencial, no a la cuenta.

Ese es el control que necesita un agente sin supervisión: todas las claves comparten el saldo de la cartera, así que este por sí solo no puede impedir que un bucle descontrolado lo gaste todo. Asigna al agente una clave propia con un límite acorde a la tarea y el peor caso quedará acotado por esa cifra. Un límite de $0 pausa una clave sin revocarla.

Lista de IP permitidas por clave (opcional)

También puedes restringir una clave a un conjunto de direcciones. Introduce una dirección IPv4/IPv6 o un bloque CIDR por línea (203.0.113.7, 198.51.100.0/24, 2001:db8::/32). Las llamadas que presenten esa clave desde cualquier otra dirección se rechazarán con 403 permission_error en todos los endpoints, incluido /v1/models. Déjalo en blanco para permitir cualquier dirección.

Comprobamos la dirección que observa nuestro proxy perimetral, no una que el cliente pueda indicar en un encabezado; por tanto, no se puede eludir la lista falsificando X-Forwarded-For. La contrapartida es que una clave con una lista de IP permitidas deja de funcionar en cuanto quien la usa cambia de host, pasarela NAT o red. Limita las listas a servidores con una salida de red estable, no a portátiles.

Encabezados de solicitud

Una solicitud mínima incluye estos dos encabezados:

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

Todos los endpoints también leen la clave del encabezado x-api-key, que es el que envían los SDK de Anthropic, en lugar de Authorization. Así, un cliente creado para la API de Anthropic llega a todas las rutas, incluida /v1/models, sin un encabezado personalizado. Si una solicitud lleva ambos, se lee Authorization. El límite de gasto y la lista de IP permitidas de la clave se aplican independientemente del encabezado con que se envíe.

Opcional, pero recomendado: User-Agent, que identifica tu aplicación. Registramos los agentes de usuario en el panel de control de /app/usage para facilitar la depuración del origen de las solicitudes.

Uso del SDK de OpenAI

La mayoría de los equipos siguen usando el SDK oficial de OpenAI y solo cambian base_url. Funciona tanto con Python (v1.x+) como 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",
});

El SDK de OpenAI usa baseURL en Node y base_url en Python. Ambos apuntan al mismo endpoint.

Rotación de claves

Práctica recomendada: rota las claves de API cada trimestre o siempre que exista la posibilidad de que una clave se haya filtrado. Kunavo permite tener varias claves activas por cuenta al mismo tiempo, por lo que la rotación se hace mediante un periodo de solapamiento, sin cambios abruptos.

# 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 clave revocada devuelve 401 de inmediato. No hay periodo de gracia: asegúrate de que el tráfico ya use la clave nueva antes de revocar la anterior.

Notas de seguridad

Nunca expongas las claves en el cliente. El código del navegador y los paquetes para móviles son públicos. Usa siempre un proxy en tu servidor.
Limita el ámbito de las claves. Usa claves distintas para cada proyecto, así podrás revocar una sin afectar a otras cargas de trabajo. También podrás asignar a cada clave su propio límite de gasto y su propia lista de IP permitidas, para acotar tanto el coste como el origen si se filtra.
Vigila el panel de control. La página /app/usage desglosa el tráfico por clave, lo que facilita detectar actividad inesperada.
Informa sobre posibles filtraciones. Escribe a support@kunavo.com y te ayudaremos a invalidar la clave y revisar el incidente.