Autenticação

Todas as chamadas à API vão para https://api.kunavo.com/v1 com Authorization: Bearer sk-kn-XXX. É só isso.

URL base

O único endpoint que atende todos os modelos e modalidades.

A estrutura dos caminhos segue as convenções da OpenAI:

Chaves de API

As chaves de API são emitidas em /app/keys no painel. Cada chave:

• Começa com sk-kn- seguido de 30 ou mais caracteres aleatórios.
• É exibida uma única vez ao ser criada — depois disso, o Kunavo armazena apenas um hash.
• Tem um nome legível por humanos (por exemplo, prod-web) no painel.
• Pode ser revogada a qualquer momento — após a revogação, a chave retorna 401 imediatamente.
• Pode ter seu próprio limite mensal de gastos e uma lista de IPs permitidos, ambos definidos em /app/keys e aplicados em todas as chamadas.

Limites de gastos por chave (opcional)

Você pode definir um limite mensal de gastos em dólares para cada chave. Se o uso liquidado da chave no mês-calendário atual for ultrapassar esse limite, as chamadas feitas com ela retornam 402 insufficient_quota e nada é cobrado até o limite ser redefinido no início do mês. As outras chaves não são afetadas — esse é um teto para uma credencial, não para a conta.

Esse é o controle de contenção de que um agente sem supervisão realmente precisa: o saldo da carteira é compartilhado por todas as chaves e, sozinho, não impede que um único ciclo descontrolado gaste tudo. Dê ao agente uma chave própria com um limite dimensionado para a tarefa, e o pior caso fica restrito a esse valor. Um limite de $0 pausa uma chave sem revogá-la.

Lista de IPs permitidos por chave (opcional)

Também é possível restringir uma chave a um conjunto de endereços. Informe um endereço IPv4/IPv6 ou bloco CIDR por linha (203.0.113.7, 198.51.100.0/24, 2001:db8::/32); chamadas que apresentarem essa chave de qualquer outro local serão recusadas com 403 permission_error, em todos os endpoints, inclusive /v1/models. Deixe em branco para permitir qualquer endereço.

Cabeçalhos de solicitação

Uma solicitação mínima inclui estes dois cabeçalhos:

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

Todos os endpoints também leem a chave de um cabeçalho x-api-key — o cabeçalho enviado pelos SDKs da Anthropic — em vez de Authorization, de modo que um cliente criado para a API da Anthropic acesse todas as rotas, inclusive /v1/models, sem um cabeçalho personalizado. Se uma solicitação incluir ambos, será lido Authorization. O limite de gastos e a lista de IPs permitidos da chave se aplicam independentemente do cabeçalho usado.

Opcional, mas recomendado: User-Agent para identificar seu aplicativo. Registramos os user agents no painel /app/usage para ajudar a depurar a origem das solicitações.

Usando o SDK da OpenAI

A maioria das equipes continua usando o SDK oficial da OpenAI e apenas troca base_url. Isso funciona tanto com Python (v1.x+) quanto com 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",
});

Rotação de chaves

Prática recomendada: faça a rotação das chaves de API trimestralmente ou sempre que houver a possibilidade de uma chave ter sido exposta. O Kunavo permite ter várias chaves simultaneamente por conta, então a rotação é uma sobreposição organizada, não uma troca repentina.

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

Observações de segurança

• Nunca exponha chaves no cliente. O código do navegador e os pacotes para dispositivos móveis são públicos. Sempre encaminhe as solicitações pelo seu servidor.
• Restrinja o escopo das chaves. Usar chaves diferentes por projeto permite revogar uma sem afetar outras cargas de trabalho — e atribuir a cada uma seu próprio limite de gastos e lista de IPs permitidos, limitando tanto o custo quanto a origem caso uma chave vaze.
• Acompanhe o painel. A página /app/usage mostra o tráfego discriminado por chave — assim, é mais fácil identificar atividades inesperadas.
• Comunique possíveis vazamentos. Envie um e-mail para support@kunavo.com e ajudaremos a invalidar a chave e analisar o incidente.

Próximos passos

• Referência de geração de respostas de chat
• Códigos de erro e estratégia de novas tentativas