kenari.
Semua tulisan

BYOK lewat kenari

Tim kenari8 menit baca
BYOK lewat kenari

BYOK artinya key provider-mu yang meneruskan request ke model, sementara kenari cuma jadi perantaranya: satu endpoint, satu kn-, plus catatan pemakaian. Token yang diproses lewat key-mu nggak menyentuh saldo kenari, sementara routing dan analytics-nya tetap kamu dapat.

Ini tulisan produk, bukan panduan setup editor. Kalau kamu cuma mau mengarahkan alat, mampir ke Arahkan editor kamu ke kenari, dan kalau belum punya key provider dan belum mau top up, mulai dari Coba dulu pakai model :free.

Kapan BYOK, kapan saldo PAYG

Ada tiga mode penagihan, dan pembedanya cuma satu: siapa pemilik key yang benar-benar memanggil modelnya.

PAYG (metered). Ini yang default. Request-mu jalan di pool key kenari, token-nya dihitung, lalu dipotong dari saldo Rupiah di akunmu. Kalau saldonya nggak cukup, model berbayar balas HTTP 402 insufficient_balance.

BYOK. Request jalan di key provider yang kamu daftarkan sendiri, jadi provider itu yang menagih ke akunmu. kenari tetap mencatat pemakaiannya dengan biaya Rp 0, dan saldo kenari nggak berkurang sepeser pun untuk token tadi.

:free. Masih pool kenari, tetap ditagih Rp 0, dan ada batas per akun. Ini di luar hitungan BYOK dan PAYG.

Pilih BYOK kalau kredit provider-mu udah terlanjur ada dan kamu cuma pengin satu kn- plus analytics tanpa bayar dua kali. Pilih PAYG kalau males ngurus key provider satu per satu, atau kalau modelnya cuma ada di katalog kenari. :free kepakai buat tes koneksi sebelum kamu memutuskan.

BYOK nggak menghapus kn-, karena kn- itu yang mengautentikasi kamu ke gateway, sementara key provider-mu nggak pernah dikirim ke n8n, editor, atau SDK mana pun.

Yang kenari tetap lakukan

Dari sisi klien nggak ada yang berubah, header-nya tetap satu baris:

Authorization: Bearer kn-...

Begitu request masuk, kenari mencoba key BYOK-mu dulu untuk model yang diminta, dan kalau sehat langsung diteruskan. Biayanya tetap ditagihkan langsung oleh provider-mu, sementara baris pemakaian tetap muncul dengan biaya nol, jadi token dan request tetap kelihatan.

Kalau satu provider kamu isi beberapa key, urutan dispatch-nya dari atas ke bawah seperti di kartu. Yang sehat dipakai, dan begitu satu key mentok atau error, kenari turun ke baris berikutnya.

Routing otomatis untuk model berbayar tetap jalan di sisi kenari. Kalau kamu mau urutan sendiri, misalnya model beda tiap langkah atau ada syarat tambahan, susun di Rute, lalu kirim nama rutenya sebagai field model seperti id model biasa.

Base URL https://kenari.id/v1 sama key kn- di klien nggak berubah, dan yang berubah cuma apakah token itu memotong saldo.

Yang tidak ditagih, dan yang tetap ditagih

Dokumen kami sendiri lugas soal ini: Model usage through your own key does not touch your balance. Baris usage-nya tetap tercatat, cuma angkanya Rp 0.

Pengecualiannya satu dan memang tertulis: biaya pencarian web dihitung per-search dan tetap berlaku seperti request metered, karena tool server kenari_web_search bukan token model.

Di luar itu nggak ada “biaya gateway” terpisah untuk meneruskan BYOK, dan yang Rp 0 adalah token yang diproses memakai key-mu. Tapi kalau Cadangan saldo kenari nyala dan semua key-mu gagal, request-nya bisa lanjut ke pool berbayar kenari, dan begitu itu terjadi hitungannya jadi PAYG dengan saldo terpotong sesuai harga katalog.

Langkah di dashboard

Halaman BYOK

Label di bawah ini diambil dari dokumentasi BYOK, dan halaman dashboard-nya ada di /byok.

  1. Buka BYOK. Tiap provider jadi satu kartu, dan baris di dalamnya adalah urutan dispatch.
  2. Klik Tambah di kanan atas (di docs Inggris namanya Add API key), pilih provider, tempel key, lalu Simpan. kenari menyimpannya lalu memeriksa di latar, dan hasil cek itu jadi status barisnya.
  3. Periksa di baris itu menjalankan cek yang sama secara sinkron, jadi statusnya langsung diperbarui.
  4. Menu di ujung baris isinya Edit, Disable/Enable, Delete, Raise priority, dan Lower priority. Naik turun prioritas baru relevan kalau satu kartu punya lebih dari satu key.
  5. Di baris key baru, klik Lihat model, salin id lengkapnya, lalu tempel ke field model di aplikasimu.

Provider yang nggak ada di daftar tinggal pilih Custom, lalu isi namanya, base URL endpoint yang kompatibel OpenAI atau Anthropic, jenis API, dan key-nya.

Status tiap baris diwakili satu titik saja:

Status Artinya
Aktif Lolos cek dan siap dipakai, kadang dengan “used 2 hours ago” atau “never used”.
Jeda Diistirahatkan karena rate limit, insiden provider, atau kuota habis, lalu pulih sendiri setelah cooldown.
Gagal Provider menolak key-nya, jadi request nggak lewat sini sampai kamu perbaiki.
Status tidak diketahui Nggak bisa diprobe, atau base URL custom tanpa endpoint models. Pindah ke Aktif begitu ada request nyata yang berhasil.
Belum diperiksa Key baru, cek pertamanya belum selesai.
Nonaktif Kamu sendiri yang mematikannya lewat Disable, jadi diam sampai dinyalakan lagi.

Titik merah bata berarti key itu nggak melayani request, hijau berarti melayani, dan titik redup berarti statusnya belum pasti.

Cadangan saldo, lalu rute

Tiap kartu provider punya toggle Cadangan saldo kenari di header-nya, dan kerjanya cuma satu: menambah entri kenari di prioritas paling bawah.

  • Nyala, lalu semua key-mu gagal atau kena limit: kenari meneruskan ke pool berbayar dan memotong saldo dengan tarif PAYG.
  • Mati: request-nya ikut gagal bareng key-mu.
  • Nyala tapi saldonya kurang: muncul peringatan merah bata di samping toggle plus tautan Isi saldo, dan cadangan itu nggak bisa melayani apa pun sampai saldonya ada, soalnya pool berbayar menolak kalau saldo nggak cukup.

Urutan di kartu itu default bawaan. Kalau kamu butuh kontrol per langkah, buka Rute, susun langkahnya (kredensial plus model), lalu kirim nama rutenya sebagai model.

Pola yang disebut di docs ada dua: BYOK dulu dengan pool kenari sebagai fallback, atau model murah dulu dan yang lebih kuat menyusul.

Tidak ada perubahan kode

Request-nya biasa saja dan key-nya tetap kn-, lalu kenari memilih BYOK-mu duluan selama modelnya tersedia di key tadi.

curl https://kenari.id/v1/chat/completions \
  -H "Authorization: Bearer kn-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "user", "content": "Halo"}
    ]
  }'

Buat model yang nggak ada di katalog kenari, kamu nggak perlu mendaftarkan apa-apa. Kirim saja id-nya dengan awalan byok/:

byok/<provider>/<model-id-di-provider-kamu>

<provider> di situ adalah tipe provider key-mu dan bukan label kartunya, dengan huruf besar kecil diabaikan. Sisanya diteruskan apa adanya, termasuk garis miring dan titik dua.

Contoh dari docs: byok/openrouter/deepseek/deepseek-v4-flash-0731, byok/groq/llama-4-70b, dan byok/ollama-local/qwen3:32b.

Prefix ini juga nggak menarik saldo, jadi baris usage-nya tetap Rp 0.

curl https://kenari.id/v1/chat/completions \
  -H "Authorization: Bearer kn-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "byok/openrouter/deepseek/deepseek-v4-flash-0731",
    "messages": [
      {"role": "user", "content": "Halo"}
    ]
  }'

Kalau format id-nya rusak kamu dapat 400 byok_malformed_model_id, dan kalau nggak ada key untuk provider itu jawabannya 400 byok_provider_not_found. Key-nya ada tapi nggak satu pun bisa dipakai, entah nonaktif atau lagi cooldown, keluarnya 403 byok_credential_unavailable.

Limit belanja di key kenari

API key kenari yang kamu kasih spend limit (batas Rupiah) tidak bisa dipakai untuk model BYOK. Spend limit menghitung Rupiah yang tercatat di kenari, sementara BYOK selalu mencatat Rp 0, jadi batas itu nggak pernah tercapai dan nggak membatasi apa pun.

Kalau kamu mau membatasi BYOK di key yang kamu bagikan, pakai token limit, soalnya token itulah satuan yang benar-benar dipakai BYOK.

Request dengan key yang kena cap dapat 403 byok_spend_capped_key.