Rerank

kenari menyediakan endpoint rerank bergaya Cohere untuk mengurutkan dokumen berdasarkan relevansinya terhadap sebuah query. Endpoint ini hanya melayani model rerank di katalog. Memanggilnya dengan model chat biasa akan mengembalikan status 400. Rerank tidak memiliki wire standar OpenAI, jadi ini adalah kontrak kenari sendiri, bukan passthrough dari satu provider tertentu.

Model yang tersedia

Daftar model rerank bersifat dinamis. Panggil GET /v1/models?modality=rerank (publik, tanpa key) untuk membaca id yang sedang aktif. GET /v1/models tanpa parameter hanya mendaftar model chat, sehingga model rerank tidak muncul di sana.

Per 29 Juli 2026 katalog publik menampilkan bge-reranker-base sebagai model rerank yang aktif. Contoh di bawah memakai id tersebut. Kalau suatu saat id itu tidak lagi dijual, ganti dengan id yang dikembalikan ?modality=rerank.

Endpoint

POST /v1/rerank

Kirim query dan documents, gateway mengembalikan documents yang sama diurutkan dari yang paling relevan.

Parameter request

Field	Tipe	Wajib	Keterangan
`model`	string	ya	Id model rerank dari katalog.
`query`	string	ya	Query yang dijadikan acuan relevansi. Maks 8192 byte.
`documents`	array of string	ya	Dokumen yang diurutkan, sesuai urutan pengiriman. Maks 100 dokumen, masing-masing maks 8192 byte, total maks 512 KiB.
`top_n`	integer	tidak	Batasi jumlah hasil yang dikembalikan (1 sampai jumlah `documents`). Default: semua dokumen.
`return_documents`	boolean	tidak	Sertakan teks dokumen pada tiap hasil. Default: `false`.

Penagihan

Penagihan dihitung per token input, dari jumlah karakter query ditambah seluruh documents (kira-kira empat karakter per token, dibulatkan ke atas), lalu dipotong dari saldo Rupiah. Biaya dihitung sebelum permintaan diteruskan ke provider dan tidak bergantung pada angka usage yang dilaporkan provider. Lihat Penagihan untuk detail saldo dan pemotongan.

Bentuk response

object bernilai "list", model mengembalikan id model yang kamu minta (bukan nama internal provider), dan array results berisi satu entri per dokumen yang relevan, diurutkan dari skor tertinggi. index menunjuk ke posisi dokumen pada documents yang kamu kirim. document hanya muncul kalau return_documents bernilai true.

{
  "object": "list",
  "model": "bge-reranker-base",
  "results": [
    { "index": 2, "relevance_score": 0.91 },
    { "index": 0, "relevance_score": 0.42 }
  ],
  "usage": { "prompt_tokens": 24, "total_tokens": 24 }
}

Contoh

curl

curl https://kenari.id/v1/rerank \
  -H "Authorization: Bearer kn-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-reranker-base",
    "query": "resep nasi goreng pedas",
    "documents": [
      "cara membuat kopi susu",
      "tutorial menanam cabai di pot",
      "resep nasi goreng pedas ala rumahan"
    ],
    "top_n": 2
  }'

Python

import requests

resp = requests.post(
    "https://kenari.id/v1/rerank",
    headers={"Authorization": "Bearer kn-..."},
    json={
        "model": "bge-reranker-base",
        "query": "resep nasi goreng pedas",
        "documents": [
            "cara membuat kopi susu",
            "tutorial menanam cabai di pot",
            "resep nasi goreng pedas ala rumahan",
        ],
        "top_n": 2,
    },
)
print(resp.json()["results"])

JavaScript

const resp = await fetch("https://kenari.id/v1/rerank", {
  method: "POST",
  headers: {
    Authorization: "Bearer kn-...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "bge-reranker-base",
    query: "resep nasi goreng pedas",
    documents: [
      "cara membuat kopi susu",
      "tutorial menanam cabai di pot",
      "resep nasi goreng pedas ala rumahan",
    ],
    top_n: 2,
  }),
});
const { results } = await resp.json();