kenari.
Semua tulisan

Apa itu AI gateway

Tim kenari9 menit baca
Apa itu AI gateway

AI gateway itu satu pintu yang berdiri di depan banyak model. Aplikasimu cukup bicara ke satu endpoint pakai satu key, dan urusan memilih jalur diserahkan ke gateway.

Pertanyaan yang lebih berguna biasanya bukan “apa itu”, tapi “kapan saya butuh”. Jawabannya mulai kelihatan begitu aplikasimu memanggil model dari lebih dari satu provider.

Yang bikin capek itu bukan modelnya

Modelnya sendiri sudah banyak dan sebagian besar bagus. Yang melelahkan justru administrasinya, dan itu bagian yang jarang dibahas orang.

Biasanya mulainya dari OpenAI, karena SDK-nya sudah kamu pakai duluan. Lalu ada satu tugas yang hasilnya lebih enak di Anthropic, jadi kamu daftar lagi. Habis itu Google, DeepSeek, dan entah siapa lagi bulan depan. Tiap provider datang bawa rombongan sendiri: dashboard sendiri, key sendiri, dan limit sendiri.

Punya tujuh akun berarti ada tujuh tempat saldo bisa diam-diam habis tanpa kamu sadari, tujuh key yang harus diganti kalau salah satunya bocor, dan tujuh tagihan yang jatuh tempo sendiri-sendiri. Cara gagalnya pun beda-beda, dan biasanya kamu baru tahu waktu satu request penting balas error di jam sibuk.

Tapi yang paling bikin jengkel bukan itu. Satu provider ngadat, dan seluruh fitur di produkmu ikut diam, bukan karena idenya habis, tapi karena semua request-nya bergantung ke satu vendor yang bukan milikmu.

Kerjaan nggak seharusnya berhenti cuma gara-gara satu provider lagi rewel.

Gateway, dijelaskan tanpa istilah

Aplikasimu nggak perlu tahu provider mana yang lagi sehat pagi ini. Kamu kirim request ke satu alamat, lalu gateway yang membaca model apa yang kamu minta, memilih backend yang bisa melayani model itu, dan mengembalikan jawabannya dalam bentuk yang sudah kamu kenal. Kalau jalur pertama mentok kena limit, timeout, atau error, gateway pindah sendiri ke jalur berikutnya tanpa kamu ganti key dan tanpa kamu nulis try/except untuk tiap merek.

Bentuknya ada dua, dan keduanya sengaja meniru yang sudah ada:

  • OpenAI-compatible. Base URL-nya menggantikan https://api.openai.com/v1, jadi SDK yang sudah kamu pakai tetap jalan. Yang berubah cuma alamat sama key.
  • Anthropic-style. Endpoint Messages, bentuk request-nya mengikuti Anthropic. Ini yang dipakai Claude Code dan klien lain yang bicara protokol itu.

Gateway yang baik nggak maksa kamu belajar format baru, karena keduanya memakai bentuk request yang sudah kamu kuasai.

Langsung ke provider vs lewat gateway

Langsung ke provider Lewat gateway
Akun Satu akun per merek Satu akun di gateway
Key Satu key per merek, kadang per proyek Satu key untuk banyak model
Ganti model Ganti base URL, kadang ganti SDK Ganti isi field model
Kalau satu provider mati Kerjaan berhenti, atau kamu nulis fallback sendiri Gateway pindah jalur
Tagihan Satu invoice per merek Satu sistem billing, satu mata uang
Analitik Terpisah per dashboard Satu riwayat request

Langsung ke provider itu masuk akal selama mereknya memang cuma satu. Gateway baru kelihatan gunanya begitu merek kedua muncul, atau begitu tujuh tab tadi mulai terasa seperti pekerjaan tambahan yang nggak dibayar.

Satu hal yang perlu diluruskan: gateway bukan model baru dan dia nggak lebih pintar dari Claude atau GPT. Yang dia urus cuma routing, key, dan fallback.

Apa yang gateway urus, apa yang nggak

Yang dia urus:

  • Satu autentikasi. Semua request kamu pakai satu key milik gateway.
  • Katalog model. Satu daftar id yang diambil dari endpoint publik, bukan dari hardcode di repo.
  • Routing. Pilih jalur yang sehat, lalu pindah kalau jalur itu gagal.
  • Metering. Input token, output token, dan biaya tercatat per request.

Yang dia nggak urus:

  • Prompt kamu tetap prompt kamu.
  • Kebijakan konten upstream tetap berlaku seperti biasa.
  • Model tetap milik providernya, dan gateway nggak mengubah cara kerjanya.

Jadi kalau kebutuhanmu memang satu merek spesifik, tanpa fallback, tanpa catatan pemakaian terpusat, panggil provider itu langsung saja. Gateway baru terasa berguna waktu kamu nggak mau kerjaan bergantung pada satu provider saja.

Satu key, dua bentuk API

Di atas kertas, “kompatibel dengan OpenAI” kedengarannya sudah cukup menjelaskan. Dalam praktik ada satu jebakan kecil yang hampir semua orang kena minimal sekali.

Klien OpenAI, entah lewat SDK atau curl ke /chat/completions, memakai base URL yang sudah termasuk /v1, misalnya https://contoh.id/v1, lalu SDK-nya yang menempelkan /chat/completions di belakang. Klien Anthropic nggak seseragam itu. Claude Code menempelkan /v1 sendiri, jadi base URL yang kamu isi harus tanpa /v1, sementara sebagian dokumen SDK Anthropic justru memakai base URL yang sudah berakhiran /v1. Salah pasang, dan yang kamu dapat adalah 405, bukan pesan error yang ramah menjelaskan salahnya di mana.

Cukup ingat dua bentuk ini:

  1. OpenAI-compatible: base URL berakhiran /v1.
  2. Claude Code (protokol Anthropic): base URL tanpa /v1.

Key-nya tetap satu untuk keduanya, dan yang berubah cuma alamat yang kamu tempel.

Satu request, dua bentuk, satu key

Request yang isinya sama bisa dikirim ke dua path berbeda tanpa ganti key sama sekali.

OpenAI-compatible:

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

Anthropic-style lewat endpoint Messages, seperti di dokumennya:

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

Yang beda cuma path, bentuk messages, dan bentuk jawabannya. Host, key kn-, dan id model-nya sama persis, karena gateway yang menerjemahkan semuanya ke backend. Kamu nggak perlu pegang tujuh key cuma gara-gara ada dua dialek API di dunia ini.

Kalau kamu bikin rute sendiri di dashboard, isi field model dengan nama rute itu dan bukan id katalog. Contoh di dokumen kami namanya opus-hemat. Sisi klien nggak berubah sedikit pun.

kenari: versi lokal dari ide ini

kenari adalah gateway yang menagih pemakaianmu dalam Rupiah.

Kamu dapat satu key kn-, endpoint OpenAI-compatible di https://kenari.id/v1, dan untuk Claude Code cukup pakai root-nya saja di https://kenari.id tanpa /v1, karena klien itu menambahkan /v1 sendiri. Format Messages ada di POST /v1/messages.

Yang membedakan kami dari gateway pada umumnya ada empat hal:

  • Bayar per token. Saldo terpotong sesuai token yang benar-benar kamu pakai, bukan per bulan.
  • Routing otomatis. Tiap model berbayar sudah punya rutenya sendiri. kenari memilih backend yang sehat, lalu pindah kalau jalur itu mentok, kena limit, atau mendadak lambat.
  • Fallback terakhir. Kalau jalur eksternal habis, pool kenari bisa jadi langkah pamungkas, dan ada juga rute bawaan kenari-free yang mengarah ke model gratis.
  • BYOK. Sudah punya key OpenAI atau Anthropic sendiri? Daftarkan saja. Request yang dilayani key-mu nggak memotong saldo kenari, tapi analitiknya tetap tercatat.

Ini bukan manifesto, cuma satu instansi dari ide tadi: satu endpoint, satu key, satu tagihan.

Satu catatan penting sebelum kamu mulai. Daftar modelnya berubah sewaktu-waktu, jadi tolong jangan di-hardcode. GET https://kenari.id/v1/models sifatnya publik dan nggak butuh key, dan tiap entri di situ membawa id-nya, harga dalam mikro-Rupiah per 1 juta token, plus penanda apakah varian itu :free.

Model :free dan saldo

Satu id model bisa punya dua wajah. step-3-7-flash memotong saldo, sedangkan step-3-7-flash:free nggak, dengan konsekuensi ada limit per menit dan jatah harian per akun. Angka pastinya kami taruh di halaman paket saja, karena operator bisa mengubahnya kapan pun dan kami nggak mau artikel ini jadi sumber informasi basi.

Jalur :free bersifat best-effort, jadi tolong jangan dijadikan satu-satunya tumpuan produksi. Adanya supaya kamu bisa menguji gateway ini dulu tanpa harus isi saldo.

Kalau request berbayar dikirim waktu saldo kosong, server balas HTTP 402 insufficient_balance. Itu bukan bug, memang saldonya lagi nggak cukup.

Kalau kamu belum pernah mengirim request ke kenari sama sekali, langkah-langkahnya ada di request pertama dari nol.

Kapan gateway justru berlebihan

Kalau kamu cuma memanggil satu model dari satu provider dan akunnya sudah jalan, gateway cuma menambah satu hop. Biayanya kecil, tapi kadang memang nggak perlu.

Gateway baru mulai kelihatan gunanya waktu kamu ganti model lebih dari sebulan sekali, atau waktu ada satu provider yang pernah bikin kamu nunggu lama. Sama juga kalau kamu pengin satu riwayat untuk seluruh tim, bukan tujuh file CSV yang harus digabung manual.

Kabar baiknya, kamu nggak perlu pindah semuanya sekaligus. Ganti base URL sama key di satu skrip dulu, dan kalau jawabannya sama, baru pindahkan sisanya.