Penalaran (reasoning)

Sebagian model menghasilkan jejak penalaran (reasoning atau extended thinking) sebelum jawaban akhir. kenari meneruskan jejak itu apa adanya dan menagih tokennya sebagai token output biasa. Halaman ini menjelaskan cara meminta penalaran dan di mana membacanya pada response.

Model yang mendukung penalaran

Di GET /v1/models, model yang mendukung penalaran punya flag reasoning: true. Bila tersedia, model itu juga membawa daftar reasoning_options, yaitu level usaha yang bisa kamu pilih (misalnya low, medium, high). Id model penalaran ada di katalog: cari model dengan flag reasoning. Lihat Model & harga.

Meminta penalaran

Caranya tergantung gaya endpoint yang kamu pakai.

Di /v1/chat/completions, pakai field reasoning_effort (misalnya "medium") untuk model yang punya reasoning_options.

curl https://kenari.id/v1/chat/completions -H "Authorization: Bearer kn-..." -H "Content-Type: application/json" -d '{"model":"<model dengan flag reasoning>","reasoning_effort":"medium","messages":[{"role":"user","content":"Hitung 17 * 24 dan jelaskan langkahnya."}]}'

Id model penalaran ada di katalog, ditandai flag reasoning di GET /v1/models. Ganti placeholder model di atas dengan salah satu id tersebut.

Di /v1/messages, pakai field thinking gaya Anthropic.

{
  "model": "step-3-7-flash",
  "max_tokens": 1024,
  "thinking": { "type": "enabled", "budget_tokens": 512 },
  "messages": [
    { "role": "user", "content": "Hitung 17 * 24 dan jelaskan langkahnya." }
  ]
}

Kontrol penalaran terpadu (objek reasoning)

Selain reasoning_effort (flat string) dan blok thinking di /v1/messages, kenari juga menerima objek reasoning gaya OpenRouter langsung di body /v1/chat/completions. Objek ini memberi kontrol yang lebih rinci dan seragam lintas provider.

Field	Tipe	Keterangan
effort	string	Level usaha: low, medium, high, xhigh, atau max. Dipetakan ke reasoning_effort (backend OpenAI/DeepSeek) atau budget_tokens (backend Anthropic).
enabled	boolean	false mematikan penalaran (diterjemahkan ke cara native tiap backend: GLM thinking: {type: "disabled"}, Qwen chat_template_kwargs, OpenAI/DeepSeek reasoning_effort: "none", Anthropic menghilangkan blok thinking). true tanpa effort/max_tokens menyalakan penalaran di level menengah, jadi backend yang defaultnya mati (mis. Anthropic) tetap berpikir.
max_tokens	integer	Batas token penalaran. Dipetakan ke budget_tokens (Anthropic, sebagai bagian dari max_tokens request mengikuti level usaha) atau level usaha terdekat (OpenAI).
exclude	boolean	true menyembunyikan teks jejak penalaran dari response. Token tetap dihasilkan dan ditagih sebagai output. Hanya teksnya yang tidak dikembalikan.

Bila reasoning dan reasoning_effort keduanya ada dalam satu request, objek reasoning yang berlaku.

Contoh: mematikan penalaran

curl https://kenari.id/v1/chat/completions -H "Authorization: Bearer kn-..." -H "Content-Type: application/json" -d '{"model":"<model dengan flag reasoning>","reasoning":{"enabled":false},"messages":[{"role":"user","content":"Jawab singkat: ibu kota Indonesia?"}]}'

kenari menerjemahkan enabled: false ke parameter native backend yang aktif, sehingga kodemu tidak perlu tahu cara tiap provider mematikan penalaran secara terpisah.

Catatan exclude: true hanya menyembunyikan teks penalaran dari response, bukan menghentikan prosesnya. Token yang dihasilkan selama penalaran tetap dihitung dan ditagih sebagai output biasa. Kalau tujuannya menghemat biaya, turunkan effort atau set enabled: false.

Membaca jejak penalaran

Di response /v1/chat/completions, teks penalaran muncul di choices[].message.reasoning. Field yang sama juga disertakan sebagai reasoning_content agar kompatibel dengan tool yang membaca field itu.

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "reasoning": "17 * 24 = 17 * 20 + 17 * 4 ...",
        "reasoning_content": "17 * 24 = 17 * 20 + 17 * 4 ...",
        "content": "Hasilnya 408."
      }
    }
  ]
}

Di /v1/messages, blok thinking diteruskan di dalam content sesuai format Anthropic, terpisah dari blok teks jawaban.

{
  "content": [
    { "type": "thinking", "thinking": "17 * 24 = 408 ..." },
    { "type": "text", "text": "Hasilnya 408." }
  ]
}

Catatan kenari tidak menyaring atau memendekkan jejak penalaran. Teks yang kamu terima sama dengan yang dikeluarkan model upstream.

Penagihan token penalaran

Token penalaran tetap dihitung sebagai output dan ditagih dengan tarif keluaran biasa, sama seperti token jawaban. Memilih level usaha yang lebih tinggi (atau budget_tokens yang lebih besar) berarti lebih banyak token keluaran, jadi biayanya naik. Lihat Penagihan.

Perhatian Level usaha tinggi dapat menghasilkan jejak penalaran yang panjang. Karena ditagih sebagai output, atur reasoning_effort atau budget_tokens sesuai kebutuhan agar biaya tetap terkendali.

max_tokens kecil dan output kosong

Model penalaran memakai sebagian dari max_tokens untuk berpikir sebelum menulis jawaban. Kalau max_tokens diset terlalu kecil, seluruh anggaran itu bisa habis untuk penalaran sebelum ada satu token jawaban pun yang keluar. Hasilnya: response kosong, tapi kenari menandainya dengan jujur, bukan seolah model berhenti sendiri:

• /v1/chat/completions: finish_reason menjadi "length".
• /v1/messages: stop_reason menjadi "max_tokens".
• /v1/responses: status menjadi "incomplete" dengan incomplete_details: {"reason": "max_output_tokens"}.

Token penalaran yang sudah terpakai tetap ditagih seperti biasa, budget yang habis bukan berarti gratis. Untuk model dengan flag reasoning, set max_tokens minimal 512 supaya ada ruang untuk jawaban setelah penalaran selesai.