Docs

Authentication

Kunavo authenticates exactly like OpenAI: a single bearer token in the Authorization header. The only change from a typical OpenAI integration is the base URL.

Esta documentação está em inglês. Para um guia de início rápido em português, veja:Guia em português — Claude API no Brasil →

Every API call goes to https://api.kunavo.com/v1 with Authorization: Bearer sk-kunavo-XXX. That's it.

Base URL

The single endpoint that fronts every model, every modality.

Field	Value
Base URL	`https://api.kunavo.com/v1`
Region	US (Ashburn) primary, multi-region edge fronting
TLS	TLS 1.2+ enforced. HTTPS only.

The path layout follows OpenAI's conventions:

Modality	Path
Chat	`POST /v1/chat/completions`
List models	`GET /v1/models`
Image generation	`POST /v1/images/generations`
Image edit / i2i	`POST /v1/images/edits`
Video generation	`POST /v1/video/generations`
TTS	`POST /v1/audio/speech`
Music	`POST /v1/audio/music`

API keys

API keys are issued from /app/keys in the dashboard. Each key:

Starts with sk-kunavo- followed by 30+ random characters.
Is shown once at creation — Kunavo only stores a hash afterwards.
Has a human-readable name (e.g. prod-web) for the dashboard.
Can be revoked at any time — the key 401s instantly after revocation.

Per-key spend caps (optional)

For each key you can set a monthly spend cap in micro-cents. Once a key's cumulative usage in the current calendar month exceeds the cap, calls authorized by that key return 402 insufficient_quota until the cap resets at month start. Useful for script-callers and CI pipelines where a runaway loop can burn cash.

Request headers

The minimum required headers on every request:

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

Optional but recommended: User-Agent identifying your app. We log user-agents in your /app/usage dashboard for debugging request sources.

Using the OpenAI SDK

Most teams stay on the official OpenAI SDK and just swap base_url. Both Python (v1.x+) and Node (v4.x+) work this way.

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",
});

The OpenAI SDK uses baseURL in Node and base_url in Python. Both point to the same endpoint.

Key rotation

Best practice: rotate API keys quarterly or whenever a key may have leaked. Kunavo lets you have multiple keys per account simultaneously, so rotation is a clean overlap, not a flip.

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

A revoked key 401s immediately. There's no grace period — make sure new key traffic is established before revoking the old one.

Security notes

Never expose keys client-side. Browser code and mobile bundles are public. Always proxy through your server.
Scope keys narrowly. Different keys per project let you revoke without affecting other workloads.
Watch the dashboard. The /app/usage page shows traffic broken down by key — unexpected activity is easier to spot.
Report suspected leaks. Email support@kunavo.com and we'll help with key invalidation and incident review.