Dokumentasi

Dify

Dify mengakses endpoint eksternal melalui satu plugin — OpenAI-API-compatible — dan satu kolom wajib, API Base URL. Isi kolom tersebut agar setiap node LLM dalam alur kerja Anda dapat menggunakan ID Claude dan GPT dengan satu kunci.

Satu field wajib — API Base URL, dalam formulir Add Model plugin yang kompatibel dengan OpenAI API — mengarahkan setiap node LLM di workspace Dify ke Kunavo.

Penyedia Model → Kompatibel dengan OpenAI-API → Tambahkan Model

# Integrations → Model Provider → OpenAI-API-compatible → Add Model
Type                          LLM
Model Name                    claude-sonnet-5
Model display name            Kunavo · Claude Sonnet 5
API Key                       sk-kn-...
API Base URL                  https://api.kunavo.com/v1
model name for API endpoint   (leave blank — Model Name is already the id)
Completion mode               Chat
Model context size            1000000
Upper bound for max tokens    (your own ceiling for one reply)
Function Call Type            Tool Call     # defaults to no_call
Vision Support                Support       # only if you will send images
Structured Output             Support       # defaults to not supported

# Model context size is per model, not per endpoint: 1000000 is
# claude-sonnet-5's. The table below carries the rest.

API Base URL tetap menggunakan /v1. Plugin mendeklarasikan endpoint_url dengan label API Base URL, menetapkannya sebagai satu-satunya kolom wajib selain nama model, dan memberinya placeholder “Base URL, misalnya https://api.openai.com/v1” — placeholder itulah yang menjelaskan format kolom tersebut. README plugin itu sendiri menjelaskan pengecualiannya, bukan menyangkalnya: untuk jenis model non-LLM, plugin “menambahkan versi API secara internal”, sehingga jenis tersebut menggunakan origin tanpa tambahan apa pun agar /v1/v1 tidak tergandakan. Tidak ada model Kunavo yang termasuk jenis tersebut, jadi formulir /v1 adalah satu-satunya yang Anda perlukan.

Tiga sakelar secara default nonaktif, dan biasanya inilah penyebab masalah. Function Call Type secara default adalah no_call, sedangkan Structured Output dan Vision Support tidak didukung. Model yang ditambahkan dengan pengaturan default akan menjawab node chat biasa dengan sempurna, lalu gagal di node Agent atau alur kerja yang menggunakan alat — sehingga tampak seperti gangguan endpoint, padahal bukan. Atur opsi tersebut saat menambahkan model, sebelum memeriksa hal lain.

Kunavo tidak menyediakan model embedding, model text-to-speech, model speech-to-text, maupun model reranking — jadi entri provider ini hanya mencakup slot LLM Dify. Basis pengetahuan yang diindeks dalam mode High Quality, URL Rerank Endpoint, atau node suara tetap menggunakan provider yang sudah dipakainya; mengarahkan node LLM ke sini tidak mengalihkan panggilan tersebut.

Konfigurasi ini ditinjau dari daftar plugin dan skema provider Dify sendiri pada tanggal di bawah. Kunavo belum menjalankan workspace Dify menggunakan endpoint-nya — belum ada model yang ditambahkan ke workspace aktif, alur kerja yang dijalankan, ataupun pertukaran bolak-balik alat secara streaming. Halaman penyiapan yang dipublikasikan bukanlah pengujian. Bagian curl di bawah dapat Anda pastikan dalam sepuluh detik; sisanya bergantung pada Anda dan Dify.

Belum punya kunci? Buat akun Kunavo, buat kunci (diawali sk-kn-) dan tambahkan kredit mulai dari $10 — panggilan dibayar dari saldo tersebut, dan panggilan yang gagal tidak ditagihkan. Dasbor kemudian terbuka pada penyiapan Dify.

Langkah demi langkah

Buat key di /app/keys dan salin — key hanya ditampilkan sekali.
Di Dify, buka Integrations → Model Provider, telusuri Install model providers (atau Marketplace), lalu instal OpenAI-API-compatible, yang diterbitkan oleh langgenius. Dokumentasi Dify menyebutkan bahwa hanya pemilik workspace dan admin yang dapat mengelola provider.
Klik Add Model pada kartu provider tersebut. Plugin ini tidak menyediakan model yang sudah ditentukan sebelumnya — ini adalah provider customizable-model — sehingga setiap id yang Anda inginkan harus ditambahkan sebagai entri terpisah.
Isi formulir seperti di atas. Type = LLM, Model Name = id Kunavo persis seperti tertulis, API Key = kunci sk-kn- Anda, API Base URL = https://api.kunavo.com/v1, Completion mode = Chat, dan Model context size sesuai tabel di bawah. Lalu atur Function Call Type, serta Structured Output dan Vision Support jika diperlukan. Simpan.
Buka alur kerja dan pilih model pada node yang akan menggunakannya — Dify menetapkan model per node, bukan per aplikasi, sehingga classifier dan penulis akhir dapat menggunakan id dan harga yang berbeda. Aplikasi dan node yang tidak memilih model akan menggunakan Default Models → System Reasoning Model.
Jalankan satu alur kerja dengan cakupan terbatas, lalu periksa biaya di akun Kunavo Anda, bukan di Dify — lihat catatan tentang tampilan biaya di bawah.

Diperiksa terhadap Halaman plugin OpenAI-API-compatible Dify pada 21 September 2026. Pengaturan pihak ketiga dapat berubah; jika nama bidang di sini tidak lagi sama dengan yang Anda lihat, halaman tersebut adalah acuan, bukan halaman ini.

Ini versi singkatnya. Panduan lengkap — pilihan model, biaya sesi nyata, dan mode kegagalan — ada di panduan biaya Dify.

Verifikasi sebelum men-debug klien

Satu permintaan menentukan apakah masalahnya ada pada endpoint, kunci, atau berkas konfigurasi. Jika ini mengembalikan JSON, base URL dan kunci yang sama berfungsi di Dify.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

ID model yang harus dimasukkan ke bidang

Setiap model teks dapat diakses melalui ID model — daftar terkininya ada di GET /v1/models, dan katalog beserta harga ada di halaman model. Tarif dalam USD per 1 juta token, input / output.

ID model	Kunavo masuk / keluar	Kegunaannya di Dify
`claude-sonnet-5`	$1.40 / $7.00	model kerja untuk node writer dan agent — ukuran konteks 1000000
`claude-opus-5`	$3.50 / $17.50	node yang hasilnya dibaca manusia, atau rencana yang mahal jika keliru — 1000000
`claude-haiku-4-5`	$0.70 / $3.50	node classifier, router, dan extraction, tempat volume panggilan sebenarnya terkumpul — 200000
`gpt-5-6-sol`	$2.00 / $12.00	keluarga model kedua dengan kunci yang sama, sebagai entri model tersendiri — 1050000
`gpt-5-6-terra`	$0.70 / $4.20	node dokumen panjang — 1050000

Penagihan dilakukan per token dari saldo prabayar tanpa biaya bulanan — lihat penagihan. Pada konteks berulang — yang merupakan sebagian besar kiriman editor atau klien obrolan — caching prompt lebih memengaruhi tagihan daripada pilihan model.

Ada dua hal berbeda yang disebut “API Dify”

Halaman ini membahas salah satunya, dan hasil pencarian kerap mencampuradukkan keduanya.

Menghubungkan model ke Dify — itulah yang dilakukan blok penyiapan di atas. Dify adalah klien, Kunavo adalah endpoint, dan kredensial yang Anda tempelkan adalah kunci sk-kn-. Setiap node LLM di semua aplikasi dalam workspace tersebut kemudian dapat menggunakan id yang Anda tambahkan.
Memanggil aplikasi Dify dari kode Anda sendiri — Service API yang disediakan Dify untuk aplikasi yang dipublikasikan, dengan kunci app- tersendiri yang diterbitkan oleh Dify. Kunci itu milik Dify, bukan kami, dan Anda tidak dapat mengarahkannya ke tempat lain. Kunavo tidak terlibat dalam alur tersebut.

Keduanya dapat berjalan bersamaan pada aplikasi yang sama, dan biasanya memang begitu: backend Anda memanggil aplikasi Dify dengan kunci Dify, lalu node aplikasi tersebut memanggil Kunavo dengan kunci Kunavo. Dua kunci, dua tagihan, dua tempat yang perlu diperiksa saat terjadi 401.

Mengapa Dify tidak menampilkan biaya untuk model yang Anda tambahkan

File model bawaan pihak pertama Dify menyertakan blok harga — tarif input dan output, serta satuan per token — lalu Dify mengalikan jumlah token Anda dengan tarif tersebut untuk menampilkan angka di log. Skema provider OpenAI-API-compatible tidak mendeklarasikan kolom harga, satuan, atau mata uang apa pun, sebagaimana diperiksa pada tanggal di atas. Jadi, untuk model yang ditambahkan melalui plugin ini, Dify tidak memiliki tarif untuk dikalikan. Kolom biaya yang kosong bukan diskon yang Anda temukan atau bug yang Anda sebabkan: kolom tersebut memang tidak ada. Lihat angka sebenarnya di catatan penggunaan Kunavo, dan gunakan jumlah token Dify sebagai jumlah token.

Ada satu sakelar terkait yang sebaiknya dibiarkan apa adanya: Include Usage in Stream secara default aktif dan meminta endpoint menyertakan jumlah token prompt dan completion pada bagian akhir stream. Jika dinonaktifkan, jumlah token juga tidak akan Anda terima.

Jika Anda meng-host sendiri Dify

Stack Docker Compose mengarahkan permintaan keluar melalui layanan ssrf_proxy. Karena itu, endpoint harus dapat dijangkau dari dalam jaringan container — bukan sekadar dari browser di laptop Anda. Konfigurasi yang berfungsi di satu tempat tetapi kehabisan waktu di tempat lain biasanya disebabkan hal ini; ini masalah jaringan, bukan kredensial. curl di atas, jika dijalankan dari dalam container, akan langsung menjawabnya.

Pertanyaan umum

Bagaimana cara menghubungkan API kustom yang kompatibel dengan OpenAI ke Dify?

Instal plugin OpenAI-API-compatible yang diterbitkan oleh langgenius dari Integrations → Model Provider → Install model providers atau Dify Marketplace. Klik Add Model pada kartunya, lalu isi formulir: Type, Model Name, Model display name, API Key, API Base URL, Completion mode, dan Model context size, beserta sakelar kapabilitas. Provider ini tidak menyediakan model yang sudah ditentukan sebelumnya — ini adalah provider model yang dapat disesuaikan. Karena itu, setiap id model yang Anda inginkan harus menjadi entri tersendiri, dan masing-masing memiliki base URL serta kuncinya sendiri.

Apakah API Base URL Dify harus diakhiri dengan /v1?

Ya, untuk model chat. Skema provider plugin ini memberi nama kolomnya API Base URL, menandainya sebagai wajib, dan menyediakan placeholder "Base URL, e.g. https://api.openai.com/v1". Jadi, root /v1 adalah format yang didokumentasikan — untuk Kunavo, https://api.kunavo.com/v1. Origin tanpa akhiran tersebut hanya didokumentasikan untuk jenis model yang versi API-nya ditambahkan sendiri oleh plugin; jika tidak, hasilnya akan menjadi jalur /v1/v1 yang berulang. Kunavo tidak menawarkan model jenis tersebut, jadi gunakan format /v1. Jika /v1 tidak disertakan, hasilnya berupa 404, bukan kesalahan autentikasi.

Mengapa node Agent Dify tidak dapat menggunakan alat pada model yang saya tambahkan?

Karena Function Call Type secara default bernilai no_call pada model yang ditambahkan melalui plugin OpenAI-API-compatible, sedangkan Structured Output, Vision Support, Stream function calling, dan Thinking Mode Support semuanya secara default tidak didukung. Pengaturan tersebut adalah deklarasi yang dipercaya Dify, bukan hasil pemeriksaan, sehingga model berkemampuan yang ditambahkan dengan pengaturan default tetap akan ditolak oleh node Agent atau node yang menggunakan alat. Buka konfigurasi model dan atur Function Call Type ke Tool Call — Function Call adalah format lama — lalu uji lagi sebelum menganggap endpoint bermasalah.

Mengapa Dify tidak menampilkan harga model yang ditambahkan melalui plugin kompatibel?

Karena skema provider plugin tersebut sama sekali tidak memiliki kolom harga, sedangkan file model bawaan pihak pertama Dify memilikinya. Karena itu, Dify tidak memiliki tarif per token untuk mengalikan jumlah token Anda, sehingga tidak menampilkan apa pun alih-alih perkiraan. Ambil angka biaya dari catatan penggunaan provider itu sendiri dan perlakukan angka Dify sebagai jumlah token. Biarkan Include Usage in Stream tetap aktif agar jumlah token tersebut tetap diterima.

Apakah menambahkan Kunavo ke Dify sama dengan menyediakan aplikasi Dify sebagai API?

Tidak, keduanya berjalan ke arah yang berlawanan. Dengan menambahkan Kunavo, Dify menjadi klien: node Dify mengirim permintaan ke endpoint yang Anda konfigurasi dengan kunci Kunavo. Dengan Service API Dify, kode Anda menjadi klien: kode tersebut memanggil aplikasi Dify yang dipublikasikan menggunakan kunci yang diterbitkan Dify, dan base URL kami tidak digunakan dalam alur itu. Satu aplikasi biasanya melakukan keduanya sekaligus, sehingga saat terjadi 401, sebaiknya telusuri kunci tertentu terlebih dahulu.

Apakah Kunavo telah menguji konfigurasi ini di Dify?

Belum. Yang diperiksa pada 21 September 2026 adalah materi Dify sendiri — daftar plugin di Dify Marketplace dan skema provider di repositori plugin resmi Dify. Dari sanalah nama kolom, urutannya, tanda wajib, dan nilai default yang disebutkan di sini berasal. Belum ada yang menambahkan model Kunavo ke workspace Dify aktif dan menjalankan alur kerja dengannya, jadi tidak ada klaim tentang streaming, pertukaran bolak-balik alat, atau loop agent berdurasi panjang di klien ini. Satu hal yang dapat Anda pastikan secara terpisah adalah apakah endpoint dan kuncinya berfungsi; curl di halaman ini dapat memastikannya.