Server tools

kenari punya server tool: tool yang dijalankan di server kenari dan bisa dipakai di model apa pun. Tambahkan ke array tools. Model memutuskan kapan memanggil, kenari menjalankannya, lalu hasilnya disisipkan kembali ke percakapan. Mirip pola openrouter:* di OpenRouter.

Tool yang tersedia

Tool	Tipe	Fungsi	Biaya
kenari:web_search	pencarian web	Cari web, hasil disisipkan ke konteks model.	per pencarian
kenari:x_search	pencarian X	Cari X (Twitter) langsung, jawaban plus sumber x.com disisipkan.	per pencarian
kenari:web_fetch	ambil halaman	Ambil isi halaman web tertentu.	per pengambilan
kenari:datetime	waktu sekarang	Tanggal dan waktu sekarang.	gratis

Cara pakai

Sertakan tool di array tools dengan tipe kenari:<nama>. Model melihat tool sebagai fungsi biasa dan memanggilnya saat dibutuhkan.

curl https://kenari.id/v1/chat/completions \
  -H "Authorization: Bearer kn-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "tools": [{"type": "kenari:web_search"}],
    "messages": [{"role": "user", "content": "Berita teknologi terbaru minggu ini?"}]
  }'

Kamu bisa memakai beberapa tool sekaligus dalam satu request:

curl https://kenari.id/v1/chat/completions \
  -H "Authorization: Bearer kn-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "tools": [{"type": "kenari:web_search"}, {"type": "kenari:datetime"}],
    "messages": [{"role": "user", "content": "Apa yang terjadi hari ini di dunia AI?"}]
  }'

kenari:web_search

Cari web, lalu sisipkan hasilnya (judul, URL, ringkasan isi) sebagai tool result. Model bisa mencari beberapa kali sebelum menjawab (agentic). Bisa dipakai di model apa pun, bukan hanya model yang punya pencarian bawaan. Ditagih per pencarian.

Berlaku untuk respons non-streaming maupun streaming. Pada stream: true, model dapat memilih memanggil tool ini secara real-time. Gateway menjalankan pencarian server-side, hasilnya disisipkan ke pesan, lalu gateway membuka turn berikutnya sampai model menjawab (atau sampai batas dua round). Pelanggan tetap melihat satu pesan utuh tanpa tool call.

kenari:x_search

Cari X (Twitter) langsung. kenari menjalankan pencarian, lalu menyisipkan jawaban ringkas plus tautan sumber x.com sebagai tool result. Bisa dipakai di model apa pun, bukan hanya model dengan pencarian bawaan. Ditagih per pencarian.

Sama seperti kenari:web_search, jalan di respons non-streaming maupun streaming dengan loop agentic yang sama (model memilih, gateway menjalankan).

Filter opsional lewat x_search_filter:

• allowed_x_handles atau excluded_x_handles: batasi ke akun tertentu (maksimal 20, tidak bisa dipakai bersamaan).
• from_date, to_date: rentang tanggal YYYY-MM-DD.
• enable_image_understanding, enable_video_understanding: baca media di dalam post.

curl https://kenari.id/v1/chat/completions \
  -H "Authorization: Bearer kn-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "tools": [{"type": "kenari:x_search"}],
    "messages": [{"role": "user", "content": "Apa yang dibicarakan di X soal rilis AI terbaru?"}]
  }'

kenari:web_fetch

Ambil isi halaman web dari URL tertentu. Berguna saat model butuh teks penuh dari satu halaman. Biaya per pengambilan sama dengan pencarian, berbagi jatah harian langganan.

kenari:datetime

Mengembalikan tanggal dan waktu sekarang (UTC + zona yang diminta). Gratis. Model butuh ini supaya tahu “hari ini” tanpa menebak dari data latihan.

Parameter opsional: timezone (zona IANA, default Asia/Jakarta).

Server tool vs tool bawaan provider

Selain kenari:*, kamu juga bisa memakai tool bawaan provider:

• web_search_preview (OpenAI) atau web_search_20250305 (Anthropic): diteruskan ke upstream. Hanya jalan kalau model upstream mendukung pencarian bawaan.
• web_search_options (field OpenAI): sama, diteruskan apa adanya.

Bedanya dengan kenari:web_search: kenari menjalankan pencariannya sendiri, jadi bisa dipakai di model apa pun. Pilih kenari:web_search kalau model upstream tidak punya pencarian bawaan. Pilih tool bawaan provider kalau model upstream sudah punya pencarian sendiri dan kamu mau memakai itu.

Tool fungsi biasa yang kamu definisikan sendiri (misalnya fungsi bernama web_search yang klien kamu eksekusi) tetap diteruskan apa adanya. kenari tidak mencegat tool milik user.

Penagihan

kenari:web_search dan kenari:web_fetch ditagih per panggilan, di luar token request. Kalau kamu berlangganan, paketmu sudah termasuk jatah harian (pencarian dan ambil halaman dihitung dalam satu jatah). Setelah jatah habis, sisanya mengikuti overflow PAYG. kenari:datetime gratis.

kenari:x_search ditagih per pencarian dengan tarif tetap, langsung dari saldo (bukan bagian dari jatah langganan). Kalau saldo tidak cukup, pencarian tidak dijalankan dan tidak ada biaya.

Lihat Penagihan untuk detail cara token dan biaya tambahan dihitung.

Panggil langsung

Kamu juga bisa memanggil pencarian dan pengambilan halaman kenari secara langsung, tanpa menyertakan model. Hasilnya dikembalikan sebagai JSON.

Cari di web:

curl https://kenari.id/v1/web/search \
  -H "Authorization: Bearer kn-..." \
  -H "Content-Type: application/json" \
  -d '{"query":"versi stabil Rust terbaru","max_results":5}'

Ambil isi halaman:

curl https://kenari.id/v1/web/fetch \
  -H "Authorization: Bearer kn-..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://blog.rust-lang.org/2025/05/15/Rust-1.87.0.html"}'

Cari di X:

curl https://kenari.id/v1/x/search \
  -H "Authorization: Bearer kn-..." \
  -H "Content-Type: application/json" \
  -d '{"query":"kabar rilis AI terbaru","x_search_filter":{"from_date":"2026-01-01"}}'

Balasannya berisi answer (jawaban ringkas) plus citations (tautan sumber x.com). Ketiga endpoint butuh key kn- dan ditagih dengan tarif per panggilan. Kalau gagal, tidak ada biaya.