kenari.
Semua tulisan

Arahkan Dify ke kenari

Tim kenari8 menit baca

Kanvasnya sudah jadi dan node-nya sudah nyambung, tinggal pilih model. Tapi Model Provider cuma menampilkan provider yang Dify kenal, dan kenari nggak ada di daftar itu.

Dify (dan Flowise) sudah mendukung endpoint yang kompatibel dengan OpenAI, jadi yang kamu ganti cuma tiga nilai: API Key diisi kn-, API Base URL diarahkan ke kenari, dan Model Name diisi id yang berakhiran :free.

n8n punya tulisannya sendiri di Arahkan n8n ke kenari, sementara editor coding seperti Claude Code, Codex, atau OpenCode ada di Arahkan editor kamu ke kenari. Yang ini khusus Dify, dengan Flowise nyusul di bawah.

Dify nggak punya kartu “Kenari”

Model di Dify datang dari provider, bukan dari node bermerek, dan kenari memang nggak punya plugin Dify resmi. Yang kamu pakai plugin bawaan Dify bernama OpenAI-API-compatible (langgenius/openai_api_compatible di Marketplace), kartu yang sama buat LM Studio, llama.cpp, atau gateway mana pun yang meniru OpenAI.

Dokumen Dify sekarang menaruhnya di Integrations → Model Provider, UI lama di Settings → Model Providers. Namanya beda, isinya sama: cari kartu OpenAI-API-compatible, lalu Add Model.

Satu jebakan kecil di menit pertama: jangan isi kartu OpenAI native pakai gpt-4 lalu berharap kenari mengenalinya, karena id di katalog kenari memang beda. Plugin compatible yang menerima nama model apa adanya.

Field yang benar-benar ada

Kartunya kelihatan panjang, tapi dari schema plugin OpenAI-API-compatible sekarang, field yang kami sentuh cuma segini:

Field Wajib Isi untuk kenari
Model Name ya id persis dari GET /v1/models, misalnya step-3-7-flash:free
API Key untuk kenari: ya kn-... dari dashboard kenari
API Base URL ya https://kenari.id/v1
Completion mode tidak, default Chat Chat, karena chat kenari lewat /v1/chat/completions
model name for API endpoint tidak kosongkan, atau isi id yang sama
Function Call Type tidak, default Not Support tes chat: biarkan. Agent Dify: Tool Call
Compatibility mode tidak, default strict OpenAI compatible

Placeholder Base URL di plugin itu https://api.openai.com/v1, dan kamu mengganti seluruh nilainya, bukan menempelkan /v1 di belakangnya. Kalau sampai jadi https://kenari.id/v1/v1/..., yang balik biasanya 405.

Sisanya plugin yang urus: dia menempelkan path sendiri di belakang Base URL (/chat/completions untuk mode Chat) lalu mengirim header Authorization: Bearer <API Key>, persis format kenari.

Field lain (context size, thinking, vision, stream usage) biarkan bawaan Dify dulu, cuma jangan nyalakan Web Search Support di kartu ini, karena formatnya ikut tool provider lain dan bukan server tools kenari.

Tiga nilai, lalu tempel ke app

1. Key kn-

Masuk ke dashboard, buka API keys, klik Buat key. Key-nya diawali kn- dan cuma tampil sekali, jadi langsung salin. Satu key berlaku untuk semua model, baik lewat endpoint OpenAI-compatible maupun Anthropic, dan tempatnya di kolom API Key Dify, bukan di prompt aplikasi.

2. API Base URL

https://kenari.id/v1

Itu pengganti langsung https://api.openai.com/v1, dan Dify yang menambahkan /chat/completions di belakangnya.

3. Model :free

Model Name di sini diketik, bukan dipilih dari daftar GPT. Buat tes tanpa saldo, pakai step-3-7-flash:free, yang waktu kami cek masih ada di katalog dengan pricing.free: true dan tool_call: true (flag tool call baru kepakai kalau kamu lanjut ke Agent).

Daftar id-nya berubah sewaktu-waktu, jadi jangan dihafalkan. Cek langsung:

curl https://kenari.id/v1/models

Cari id yang berakhiran :free, atau yang pricing.free: true. Cara memilihnya dan bedanya dengan PAYG atau BYOK sudah kami tulis di Coba dulu pakai model :free.

Pasang di Dify

  1. Buka Integrations → Model Provider, atau Settings → Model Providers kalau UI-mu masih yang lama.
  2. Instal OpenAI-API-compatible dari Marketplace kalau belum ada, lalu buka kartunya dan klik Add Model.
  3. Model type: LLM, dan Model Name: step-3-7-flash:free.
  4. API Key: kn-..., API Base URL: https://kenari.id/v1, Completion mode: Chat.
  5. Simpan. Kalau Dify sempat memvalidasi key ke endpoint itu, 200 berarti Base URL dan key-mu sudah sampai ke gateway.
  6. Di app Chatbot, Chatflow, atau Agent, pilih model itu di node LLM lalu kirim pesan. Begitu ada jawaban, koneksinya hidup.

Enaknya, app lain di workspace yang memakai model itu ikut pindah sendiri, karena kamu nggak mengganti node satu pun.

Kalau app-nya Agent dan modelnya harus memanggil tool Dify, set Function Call Type ke Tool Call, lalu pastikan id yang kamu pakai punya tool_call: true di GET /v1/models. Buat tes pertama tanpa agent, langkah ini bisa dilewati.

Knowledge base belakangan

Knowledge di Dify minta model embedding sendiri, sedangkan GET /v1/models tanpa query cuma mengembalikan model chat, jadi embedding-nya ditanya begini:

curl "https://kenari.id/v1/models?modality=embedding"

Id yang muncul di situ (waktu kami cek ada bge-m3, qwen3-embedding-0.6b, dan sejenisnya) bukan :free, jadi tanpa saldo request embedding-mu bakal balik 402. Buat langkah pertama, tahan dulu nge-index-nya dan cukup pastikan chat LLM-nya jalan.

Plugin yang sama bisa menambah tipe Text Embedding atau Rerank, dan untuk LLM Base URL-nya tetap https://kenari.id/v1. Di sini ada sedikit kekacauan: source plugin langgenius/openai_api_compatible yang kami cek menempelkan /embeddings ke Base URL apa adanya tanpa menambah /v1, sementara sebagian panduan plugin (termasuk contoh Marketplace) justru menyuruh Base URL tanpa /v1 untuk kartu non-LLM. Kalau path-mu dobel dan hasilnya 405, cek versi plugin di kartu itu, dan jangan salin workaround-nya ke kartu LLM.

Flowise: Base Path, bukan plugin

Flowise nggak punya kartu provider seperti Dify. Yang dia pakai node ChatOpenAI, dan dokumentasi Flowise menaruh custom URL di Additional Parameters → Base Path, field yang sama buat OpenRouter atau Together.

Field Isi untuk kenari
Credential (OpenAI API) kn-...
Model Name step-3-7-flash:free (ketik, jangan andalkan dropdown GPT)
Base Path https://kenari.id/v1
Base Options kosongkan
  1. Tarik ChatOpenAI ke kanvas, lalu Connect Credential → Create New dan tempel kn-....
  2. Buka Additional Parameters, isi Base Path dengan https://kenari.id/v1.
  3. Model Name: ketik id kenari langsung. Kalau dropdown menolak string asing, ganti ke node ChatOpenAI Custom, yang docs Flowise sediakan untuk nama di luar daftar OpenAI.
  4. Tempel node itu ke LLM Chain atau Agent, jalankan sekali, dan kalau ada jawaban berarti kelar.

Base Options biarkan kosong, karena kenari nggak minta header ekstra, dan kalau kredensialmu punya kolom Organization ID, kosongkan juga.

Kalau mentok

  • Validasi Dify merah, atau 401: key-nya salah, kepotong, atau masih sk- yang lama. Salin ulang kn-..., dan jangan bingung kalau body 401 kenari cuma teks polos, bukan JSON.
  • model_not_found: id-nya salah ketik, atau Model Name masih terisi gpt-4. Pakai persis id yang keluar dari GET /v1/models.
  • 402 insufficient_balance: kamu memanggil model tanpa :free sementara saldonya Rp 0. Ganti ke id :free, atau isi saldo dulu (Bayar token pakai QRIS).
  • 405: bentuk Base URL-nya salah. Buat LLM harus tepat https://kenari.id/v1, bukan https://kenari.id dan bukan .../v1/v1.
  • 429 dengan free_quota_rpm atau free_quota_daily: kamu kena batas kuota :free, jadi baca Retry-After. Angka kuotanya kami taruh di halaman harga, bukan di artikel ini.
  • Agent Dify diam dan tool-nya nggak pernah terpanggil: Function Call Type-nya masih Not Support. Ganti ke Tool Call, sekalian pastikan id yang kamu pakai tool_call: true.

Dify Cloud dan self-host memakai plugin yang sama, jadi yang berubah cuma nilai field-nya, begitu juga Flowise Cloud maupun self-host: Base Path di Additional Parameters.