Routing & rute

Setiap model yang kamu panggil lewat kenari sudah dirutekan secara otomatis. Kalau kamu ingin menentukan urutannya sendiri, buat rute bernama di dashboard lalu kirim namanya di field model. Kode klienmu tidak berubah dalam kedua kasus.

Routing otomatis

Untuk setiap model, kenari memilih provider yang sehat dan mengirim request ke sana. Jika provider itu mengembalikan error, kena limit, atau lambat, kenari pindah ke provider berikutnya. Dalam satu sesi, kenari cenderung tetap memakai provider yang sama selama provider itu sehat, sehingga latensi dan gaya jawaban lebih stabil.

Kamu tidak perlu mengatur apa pun, dan response tidak pernah menyebut provider mana yang melayani request. Lihat Error untuk tampilan error saat semua provider gagal.

Rute bernama

Rute adalah daftar langkah yang berurutan. Setiap langkah berisi satu model dan satu kredensial: key yang kamu tambahkan di BYOK, atau Saldo kenari (PAYG). Kamu memanggil rute dengan namanya, dan kenari menjalankan langkahnya satu per satu.

Rute bisa dipakai di Chat completions, Messages, dan Responses. Hanya model chat yang bisa menjadi langkah. Model gambar, audio, embedding, rerank, dan moderasi tidak bisa.

Buat rute

Buka BYOK & Rute di dashboard, lalu tab Rute.
Klik Buat Rute, lalu pilih Rute kustom.
Isi Nama Rute seperti cheap-first, lalu klik Buat.
Klik Edit pada rute baru, lalu Tambah Langkah untuk setiap langkah. Pilih Kredensial dan Model di tiap langkah.
Klik Simpan.

Nama rute harus unik di akunmu dan maksimal 64 karakter. kenari-free dan nama yang diawali byok/ sudah dicadangkan.

Dialog pembuatan juga menawarkan Rute per model, yang membuat rute untuk satu model: rute ini mencoba key BYOK kamu yang memenuhi syarat lebih dulu, lalu kenari. Kamu perlu menambahkan key di BYOK terlebih dahulu.

Pilih strategi

Pengaturan Strategi menentukan langkah mana yang dicoba pertama. Jika satu langkah gagal atau kena limit, kenari melanjutkan ke langkah sisanya.

Strategi	Langkah pertama pada tiap request
Fallback	Selalu langkah 1. Langkah berikutnya dipakai hanya saat langkah sebelumnya gagal. Ini default.
Round Robin	Langkah berikutnya secara bergilir, sehingga request berputar di seluruh daftar.
Acak	Satu langkah acak.
Berbobot	Satu langkah yang dipilih acak sesuai proporsi Bobot-nya.
Latensi	Langkah dengan latensi terendah belakangan ini. Langkah yang belum punya data latensi dicoba lebih dulu.

Panggil rute

Kirim nama rute sebagai model, persis seperti id model.

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

Karena rute hanya mengganti nilai model, kamu bisa mengubah urutan langkah atau menambah cadangan tanpa menyentuh kode klien.

Pola umum

Pola	Langkah	Kapan dipakai
Key sendiri dulu	Langkah 1: key BYOK kamu. Langkah 2: Saldo kenari (PAYG)	Kamu ingin memakai kuota provider sendiri lebih dulu dan menjadikan kenari cadangan.
Murah dulu	Langkah 1: model murah. Langkah 2: model yang lebih kuat sebagai cadangan ketersediaan	Kamu ingin memakai model murah untuk setiap request dan model yang lebih kuat hanya saat model murah gagal atau kena limit. Memilih model berdasarkan tingkat kesulitan tugas membutuhkan logika di aplikasimu sendiri.
Bagi beban	Strategi Round Robin di beberapa key	Kamu ingin membagi trafik ke beberapa key.

Rute kenari-free

Setiap akun punya rute read-only bernama kenari-free yang melayani model gratis. Lihat Model gratis.

Batasan dan jebakan

Request yang salah bentuk, misalnya body tidak valid, langsung dikembalikan sebagai error. kenari tidak mencobanya lagi di langkah berikutnya karena setiap langkah akan menolaknya juga.
Langkah yang key-nya dinonaktifkan atau dihapus dilewati.
Rute bernama tidak tersedia di key yang punya batas biaya, batas token, atau pembatasan model. Request mengembalikan 400. Pakai key tanpa pembatasan, atau lihat Autentikasi & API key.
Langkah dengan Saldo kenari (PAYG) ditagih menurut aturan pendanaan yang berlaku untuk model langkah itu, jadi langkah yang memenuhi syarat bisa ditanggung kuota paket atau gratis pada model gratis. Selain itu, langkah ditagihkan ke saldomu. Langkah dengan key sendiri ditagih oleh provider kamu. Lihat Cara penagihan.