BYOK

BYOK (bring your own key) memungkinkan kamu mendaftarkan key dari akun provider milikmu sendiri dan memakainya lewat endpoint kenari dan key kn- yang sama. Provider menagih token ke kamu, saldo kenari tidak terpotong, dan pemakaian tetap muncul di analitik dengan biaya Rp 0. Biaya per pencarian untuk Server tools seperti web search tetap berlaku.

Tambah key

Buka BYOK & Rute di dashboard, lalu tab BYOK.
Klik Tambah API Key.
Pilih Provider, tempel key, tambahkan Label (opsional) jika perlu, lalu klik Simpan.

kenari memeriksa key sesaat setelah kamu menyimpannya dan menampilkan hasilnya di baris key.

Provider tidak ada di daftar

Pilih Custom (endpoint sendiri) lalu isi:

Nama provider: nama unik seperti my-proxy. kenari mengubahnya menjadi huruf kecil dan mengganti spasi dengan tanda hubung. Kamu memakai nama ini di id model byok/ dan saat menyusun rute.
Base URL: base URL endpoint-mu.
Jenis API: Kompatibel OpenAI atau Anthropic.

Kelola key

Setiap provider yang kamu pakai tampil sebagai kartu, dengan key-nya berurutan sesuai prioritas.

Kontrol	Fungsinya
Periksa	Menjalankan pemeriksaan ulang key ke provider.
Lihat model	Menampilkan model yang bisa dijangkau key ini, lengkap dengan Salin ID untuk tiap model.
Menu baris	Ubah API Key, Nonaktifkan atau Aktifkan, Hapus API Key. Jika satu provider punya dua key atau lebih, ada juga Naikkan prioritas dan Turunkan prioritas.

Status key

Setiap baris menampilkan satu status.

Status	Artinya
Aktif	Key lulus pemeriksaan, atau pemeriksaan tidak bisa memastikan tetapi key melayani request dalam 7 hari terakhir. Baris bisa menambahkan “dipakai 2 jam lalu” atau “belum pernah dipakai”.
Jeda N menit	Provider membatasi key (rate limit), sedang ada gangguan sementara, atau kuota key habis. Key otomatis dapat digunakan kembali setelah jeda berakhir.
Gagal	Provider menolak key. Tidak ada request yang lewat key ini sampai kamu memperbaikinya.
Status tidak diketahui	Provider tidak bisa diperiksa otomatis, misalnya endpoint custom tanpa daftar model. Key menjadi Aktif setelah ada request yang berhasil lewat key itu.
Belum diperiksa	Key baru yang menunggu pemeriksaan pertamanya.
Nonaktif	Kamu mematikan key ini. Key tidak melayani request sampai kamu klik Aktifkan.

Cadangan saldo kenari

Setiap kartu provider punya sakelar Cadangan saldo kenari. Saat sakelar aktif dan semua key kamu untuk provider itu gagal atau kena limit, kenari menyelesaikan request dengan kapasitasnya sendiri dan memotong saldomu dengan tarif PAYG. Jika semua key kamu gagal dan cadangan mati, request gagal.

Jika sakelar aktif tetapi saldo terlalu rendah, kartu menampilkan peringatan dan tautan Isi saldo. Cadangan tidak bisa menutup request sampai kamu menambah saldo. Lihat Cara penagihan.

Urutan fallback

kenari mencoba key di satu kartu dari atas ke bawah, lalu pindah ke key berikutnya saat satu key gagal atau kena limit. Cadangan saldo, bila aktif, selalu terakhir. Pakai Naikkan prioritas dan Turunkan prioritas untuk mengubah urutan.

Untuk model yang berbeda di tiap langkah, buat rute bernama. Lihat Routing & rute.

Pakai model katalog

Kamu tidak perlu mengubah kode. Kirim request dengan key kn- seperti biasa. Saat model yang kamu minta dilayani provider yang key-nya kamu daftarkan, kenari mencoba key-mu lebih dulu.

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

Pakai model apa pun dari provider-mu

Untuk model apa pun yang dilayani provider-mu, termasuk yang tidak ada di katalog kenari, kirim id-nya dengan awalan byok/:

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

Bagian	Aturan
`byok`	Literal, huruf kecil.
`<provider>`	Provider dari key-mu, atau Nama provider untuk endpoint custom. Pencocokan tidak membedakan huruf besar dan kecil.
Sisanya	Dikirim ke provider apa adanya, termasuk garis miring dan titik dua. Huruf besar dan kecil dipertahankan.

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

Provider bawaan adalah openai, anthropic, deepseek, xai, groq, mistral, dan opencode. Endpoint custom dialamatkan dengan Nama provider yang kamu berikan saat menambahkan key. Misalnya, endpoint custom bernama my-proxy memakai byok/my-proxy/<id-model-di-provider-kamu>.

Untuk mencari id yang tepat, klik Lihat model di baris key lalu pakai Salin ID. Jalur ini tidak pernah memakai saldomu. Jika kamu punya beberapa key untuk provider itu, kenari mencobanya sesuai urutan prioritas.

Error

Status	Kode	Kapan
`400`	`byok_malformed_model_id`	Id setelah `byok/` tidak punya provider atau model.
`400`	`byok_provider_not_found`	Kamu tidak punya key untuk provider itu.
`403`	`byok_credential_unavailable`	Kamu punya key untuk provider itu, tetapi tidak ada yang bisa melayani sekarang karena dinonaktifkan atau sedang jeda.
`403`	`byok_spend_capped_key`	Key `kn-` yang kamu kirim punya batas biaya.

Daftar lengkapnya ada di Error.

Key dengan batas biaya

Key dengan Batas biaya, Rp (opsional) tidak bisa memakai model byok/. Alasannya, dan cara membatasi pemakaian BYOK, ada di Autentikasi & API key.