BYOK (key sendiri)

BYOK berarti bring your own key: daftarkan key provider milikmu sendiri, lalu pakai lewat kenari. Pemakaian model lewat key milikmu tidak memotong saldo. kamu tetap memakai satu endpoint, satu key kn-..., dan analitik yang sama seperti biasa. Biaya per pencarian web search tetap berlaku seperti request model berbayar lainnya.

Cara kerja

Saat kamu mengirim request dengan key kn-..., kenari mencoba key BYOK kamu lebih dulu untuk model yang diminta. Tagihan provider masuk ke akun provider kamu sendiri. Pemakaian tetap muncul di analitik dengan biaya nol untuk model, sehingga token dan request terlihat seperti biasa.

Daftar dan kelola key

Buka BYOK di dashboard. Setiap provider yang kamu pakai tampil sebagai kartu dengan deretan key dalam urutan prioritas.

Tambah API key: tombol di kanan atas halaman.
Periksa: tombol di tiap baris key, menjalankan pengecekan ulang ke provider.
Ubah, Nonaktifkan/Aktifkan, Hapus, Naikkan prioritas, Turunkan prioritas: semuanya lewat menu tindakan di ujung baris. Pengaturan prioritas pindah ke menu karena hanya relevan ketika kartu punya lebih dari satu key.

Saat key ditambah, kenari langsung menyimpan lalu memeriksa key itu di latar belakang. Hasil pemeriksaan ditulis ke baris dan menggerakkan status baris. Penekanan tombol Periksa menjalankan pemeriksaan yang sama secara sinkron dan langsung memperbarui baris.

Provider tidak ada di daftar

Pilih Custom, isi nama provider, base URL endpoint yang kompatibel dengan OpenAI atau Anthropic, lalu pilih jenis API (OpenAI-compatible atau Anthropic-compatible). Tempel key milikmu.

Status tiap key

Tiap baris punya satu status dalam satu baris. Titik di depan label menggunakan tiga warna: brick untuk key yang tidak akan melayani permintaan, hijau untuk key yang akan melayani, abu-abu untuk key yang belum bisa dipastikan.

Status	Artinya
Aktif	Key lulus pemeriksaan dan siap melayani. Bisa ditambah keterangan “dipakai 2 jam lalu” atau “belum pernah dipakai”.
Jeda	Key sementara tidak dipakai, biasanya karena kena rate limit, gangguan provider, atau kuota habis. Pulih sendiri setelah cooldown berakhir.
Gagal	Provider menolak key. Permintaan tidak akan lewat key ini sampai kamu memperbaikinya.
Status tidak diketahui	Provider tidak bisa dicek lewat probe otomatis, atau base URL custom tidak menyediakan endpoint models. Key seperti ini tetap berubah menjadi Aktif begitu ada request yang benar-benar berhasil melewatinya.
Belum diperiksa	Key baru yang menunggu hasil pemeriksaan pertama.
Nonaktif	Key sengaja dimatikan lewat menu Nonaktifkan. Tidak melayani permintaan sampai diaktifkan lagi.

Cadangan saldo kenari

Di header tiap kartu provider ada sakelar Cadangan saldo kenari. Sakelar ini menambahkan satu entri kenari di urutan terakhir sebagai cadangan. Saat sakelar aktif, kalau semua key kamu untuk provider itu gagal atau kena limit, kenari melanjutkan request lewat pool berbayarnya dan memotong saldo dengan tarif PAYG. Saat sakelar mati, request ikut gagal bila semua key kamu gagal.

Saat sakelar aktif tapi saldo tidak cukup, tampilan menunjukkan peringatan di samping sakelar dan tautan Isi saldo ke halaman top up. Cadangan tidak bisa menutup request sampai saldo terisi, karena pool berbayar akan menolak request saat saldo kurang.

Urutan fallback

Key dalam kartu dicoba dari atas ke bawah. Key pertama yang sehat dipakai, kalau gagal atau kena limit kenari lanjut ke key berikutnya. Entri kenari, ketika ada, selalu di urutan paling akhir.

Urutan langkah ini adalah satu-satunya default. Untuk kontrol per langkah yang lebih detail (misalnya beda model di tiap langkah, atau kondisi tambahan), buka halaman Rute dan buat rute bernama. Rute dikirim sebagai nilai model, sama seperti memanggil model biasa.

Pakai seperti biasa

Tidak ada perubahan kode. Kirim request dengan key kn-... seperti biasa, dan kenari memilih key BYOK kamu lebih dulu ketika model yang diminta tersedia di sana.

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

Model yang tidak ada di katalog kenari

Cara di atas bekerja untuk model yang ada di katalog kenari. Untuk model apa pun yang dilayani provider kamu sendiri, termasuk yang tidak ada di katalog, kirim ID model dengan awalan byok/. Tidak perlu membuat rute, tidak perlu mendaftarkan model.

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

Contoh:

byok/openrouter/deepseek/deepseek-v4-flash-0731
byok/groq/llama-4-70b
byok/ollama-local/qwen3:32b

Segmen	Aturan
`byok`	ditulis apa adanya, huruf kecil
`<provider>`	tipe provider key kamu, bukan label. Huruf besar kecil tidak dibedakan
sisanya	diteruskan apa adanya ke provider kamu, termasuk garis miring dan titik dua, huruf besar kecil dipertahankan

Request lewat jalur ini tidak memotong saldo. Baris pemakaian tetap tercatat dengan biaya 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"}
    ]
  }'

Tiga langkah dari key ke jawaban

Buka /byok, klik Tambah, pilih provider, tempel key, Simpan. Status key langsung diperiksa.
Di baris key yang baru, klik Lihat model, cari model yang kamu mau, salin ID lengkapnya.
Tempel ID itu ke kolom model di aplikasi kamu.

Kalau ada yang salah

Keadaan	Status	Kode
Format ID tidak lengkap	400	`byok_malformed_model_id`
Tidak ada key untuk provider itu	400	`byok_provider_not_found`
Key ada, tetapi tidak ada yang bisa dipakai (nonaktif atau sedang cooldown)	403	`byok_credential_unavailable`
Key API memakai batas biaya	403	`byok_spend_capped_key`

Kalau kamu punya beberapa key untuk satu provider, kenari memakainya berurutan sesuai prioritas di /byok, sama seperti fallback di atas.

Key API dengan batas biaya

Key API yang memakai batas biaya tidak bisa memakai model BYOK. Batas biaya dihitung dari Rupiah yang tercatat di kenari, sedangkan pemakaian BYOK tercatat Rp 0, jadi batas itu tidak akan pernah tercapai dan tidak membatasi apa pun.

Untuk membatasi pemakaian BYOK pada key yang kamu bagikan, pakai batas token. Token adalah satuan yang benar-benar dipakai model BYOK.