Autentikasi

Setiap panggilan API dikirim ke https://api.kunavo.com/v1 dengan Authorization: Bearer sk-kn-XXX. Itu saja.

URL dasar

Satu endpoint yang menjadi gerbang bagi semua model dan semua modalitas.

Susunan path mengikuti konvensi OpenAI:

Kunci API

Kunci API diterbitkan melalui /app/keys di dasbor. Setiap kunci:

• Diawali dengan sk-kn-, diikuti 30+ karakter acak.
• Ditampilkan satu kali saat dibuat — setelah itu, Kunavo hanya menyimpan hash-nya.
• Memiliki nama yang mudah dibaca manusia (misalnya prod-web) untuk ditampilkan di dasbor.
• Dapat dicabut kapan saja — kunci langsung mengembalikan 401 setelah dicabut.
• Dapat memiliki batas pengeluaran bulanan dan daftar izin IP sendiri; keduanya ditetapkan melalui /app/keys dan diberlakukan pada setiap panggilan.

Batas pengeluaran per kunci (opsional)

Untuk setiap kunci, Anda dapat menetapkan batas pengeluaran bulanan dalam dolar. Jika penggunaan yang telah diselesaikan untuk kunci tersebut pada bulan kalender berjalan akan melampaui batas, panggilan yang menggunakannya akan mengembalikan 402 insufficient_quota dan tidak dikenai biaya hingga batas diatur ulang pada awal bulan. Kunci Anda yang lain tidak terpengaruh — ini adalah batas untuk satu kredensial, bukan untuk akun.

Inilah pembatasan yang benar-benar dibutuhkan oleh agen tanpa pengawasan: saldo dompet digunakan bersama oleh semua kunci, sehingga saldo itu saja tidak dapat mencegah satu loop yang tak terkendali menghabiskan semuanya. Beri agen kunci tersendiri dengan batas sesuai kebutuhan tugas, sehingga biaya terburuknya dibatasi oleh angka tersebut. Batas $0 menjeda kunci tanpa mencabutnya.

Kunavo memutuskan apakah suatu panggilan diterima berdasarkan catatan pengeluaran melalui kunci yang dipakai panggilan itu. Catatan ini bisa tertinggal hingga satu menit dan tidak mencakup jumlah yang dicadangkan oleh panggilan yang sedang berjalan. Akibatnya, saat pengeluaran mendekati batas, panggilan bisa tetap diterima meskipun membuat pengeluaran melampaui batas, dengan kelebihan biaya hingga sebesar biaya yang ditagih melalui kunci tersebut dalam satu menit terakhir, dan beberapa panggilan yang berjalan pada saat yang sama bisa bersama-sama melampaui batas. Selain itu, panggilan diterima berdasarkan perkiraan biayanya, dan jumlah yang akhirnya ditagihkan bisa lebih besar daripada perkiraan itu.

GET /v1/balance, yang dipanggil dengan sebuah kunci, mengembalikan batas kunci tersebut, jumlah yang telah dibelanjakan kunci itu pada bulan ini, dan sisa batasnya. Endpoint ini juga mengembalikan saldo dompet akun, yang dapat dibaca oleh setiap kunci pada akun, termasuk kunci yang memiliki batas. Lihat Saldo.

Daftar izin IP per kunci (opsional)

Kunci juga dapat dibatasi ke sekumpulan alamat. Masukkan satu alamat IPv4/IPv6 atau blok CIDR per baris (203.0.113.7, 198.51.100.0/24, 2001:db8::/32); panggilan yang menggunakan kunci tersebut dari alamat lain akan ditolak dengan 403 permission_error, di semua endpoint, termasuk /v1/models. Biarkan kosong untuk mengizinkan alamat mana pun.

Header permintaan

Permintaan minimal memuat dua header berikut:

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

Setiap endpoint juga membaca kunci dari header x-api-key sebagai pengganti Authorization — header yang dikirim Anthropic SDK — sehingga klien yang dibuat untuk API Anthropic dapat mengakses setiap rute, termasuk /v1/models, tanpa header kustom. Jika permintaan memuat keduanya, yang dibaca adalah Authorization. Batas pengeluaran dan daftar izin IP kunci berlaku apa pun header yang digunakan.

Opsional, tetapi disarankan: User-Agent untuk mengidentifikasi aplikasi Anda. Kami mencatat user-agent di dasbor /app/usage untuk membantu menelusuri sumber permintaan.

Menggunakan OpenAI SDK

Sebagian besar tim tetap menggunakan OpenAI SDK resmi dan hanya mengganti base_url. Python (v1.x+) dan Node (v4.x+) sama-sama berfungsi dengan cara ini.

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

Rotasi kunci

Praktik terbaik: rotasi kunci API setiap tiga bulan atau kapan pun ada kemungkinan kunci bocor. Kunavo memungkinkan beberapa kunci aktif secara bersamaan pada satu akun, sehingga rotasi dapat dilakukan dengan masa tumpang tindih yang mulus, tanpa perlu berganti secara langsung.

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

Catatan keamanan

• Jangan pernah mengekspos kunci di sisi klien. Kode browser dan bundel seluler bersifat publik. Selalu teruskan permintaan melalui server Anda.
• Batasi cakupan kunci. Kunci yang berbeda untuk setiap proyek memungkinkan Anda mencabut kunci tanpa memengaruhi beban kerja lain — dan memungkinkan setiap kunci memiliki batas pengeluaran serta daftar izin IP sendiri, sehingga dampak kebocoran kunci dibatasi dari segi biaya maupun asal permintaan.
• Pantau dasbor. Halaman /app/usage menampilkan lalu lintas per kunci — aktivitas yang tidak terduga akan lebih mudah diketahui.
• Laporkan dugaan kebocoran. Kirim email ke support@kunavo.com dan kami akan membantu menonaktifkan kunci serta meninjau insiden.

Langkah selanjutnya

• Referensi Chat Completions API
• Kode kesalahan dan strategi percobaan ulang