Docs

Quickstart

Kunavo is OpenAI-wire-compatible. If you already use the OpenAI SDK, all you change is the base URL. Five minutes from zero to your first frontier-model call.

Questa documentazione è in inglese. Per una guida rapida in italiano, vedi:Guida in italiano — Claude API in Italia →

The whole onboarding is four steps. The first three are one-time. The fourth — making a call — is just base_url swap.

1. Create an account

Sign up at kunavo.com/app/login with Google or email magic link. New accounts get $2 free credit immediately — enough to test text, image and video.

2. Create an API key

Open /app/keys in the dashboard and click New key. Keys start with sk-kunavo- and are shown only once at creation — copy and store securely.

Recommended hygiene:

One key per project / environment (dev, staging, prod).
Rotate keys on incident or every quarter.
Set a per-key monthly spend cap if you script-call from CI.

Treat API keys like passwords. Never commit them to git or ship them in client-side bundles. Use environment variables and a secret store.

3. Fund your wallet

Go to /app/billing and top up via Stripe Checkout. Cards, Apple Pay, Google Pay, ACH, and Stripe's local methods all work. Minimum top-up is $10, and balance never expires.

Pay-as-you-go: usage is deducted from your wallet in real time, no subscription.
Volume bonuses apply: $100 → +$10, $1,000 → +$250, $5,000 → +$2,000.
Statement descriptor on your card: KUNAVO.COM* TOPUP.

4. Make your first call

Pick any enabled model from the catalog. Below: a cheap, fast gemini-3-flash chat call so you can verify the wiring.

Python (OpenAI SDK)

The openai Python package (v1+) works out of the box — just point base_url at Kunavo.

first_call.py

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KUNAVO_API_KEY"],
    base_url="https://api.kunavo.com/v1",
)

resp = client.chat.completions.create(
    model="gemini-3-flash",
    messages=[{"role": "user", "content": "Say hi in one sentence."}],
)
print(resp.choices[0].message.content)

Node.js

first_call.mjs

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KUNAVO_API_KEY,
  baseURL: "https://api.kunavo.com/v1",
});

const resp = await client.chat.completions.create({
  model: "gemini-3-flash",
  messages: [{ role: "user", content: "Say hi in one sentence." }],
});
console.log(resp.choices[0].message.content);

curl

curl https://api.kunavo.com/v1/chat/completions \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-flash",
    "messages": [{"role": "user", "content": "Say hi in one sentence."}]
  }'

If you got a response — congratulations, your account is live. The cost shows up in /app/usage within seconds.

Other modalities

The same SDK handles images and video. Endpoints are OpenAI-named where possible.

Image generation

Use any of the image models — Nano Banana, Nano Banana 2, Nano Banana Pro and GPT-Image-2. See image docs.

img = client.images.generate(
    model="nano-banana",
    prompt="a tiny red origami crane on a white desk",
    size="1024x1024",
)
print(img.data[0].url)

Streaming chat

Set stream=True. Streaming works on every chat model — the full Claude and Gemini families. The response is server-sent events in OpenAI's standard format.

stream = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Tell me a 2-line haiku about CI/CD."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Where to go next

Authentication — full API key + base URL reference.
Chat completions — parameters, streaming, tool calls, vision.
Billing — how the markup formula and credit ledger work.
Errors — HTTP codes and retry strategy.