Docs

Dify

Dify reaches an outside endpoint through one plugin — OpenAI-API-compatible — and one required field, API Base URL. Fill it in and every LLM node in your workflows can address Claude, GPT and Gemini ids on a single key.

One required field — API Base URL, in the OpenAI-API-compatible plugin's Add Model form — points every LLM node in a Dify workspace at Kunavo.

Model Provider → OpenAI-API-compatible → Add 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 keeps the /v1. The plugin declares endpoint_url under the label API Base URL, marks it as the one required field beside the model name, and gives it the placeholder “Base URL, e.g. https://api.openai.com/v1” — that placeholder is the sentence that settles the form. The plugin's own README explains the exception rather than contradicting it: for non-LLM model types the plugin “appends the API version internally”, so those take the bare origin to avoid a doubled /v1/v1. No Kunavo model is one of those types, so the /v1 form is the only one you need.

Three switches default to off, and they are the usual bug. Function Call Type defaults to no_call, Structured Output and Vision Support to not supported. A model added with the defaults answers a plain chat node perfectly and then fails in an Agent node or a tool-using workflow — which reads like an endpoint fault and is not one. Set them when you add the model, before you debug anything else.

Kunavo serves no embedding model, no text-to-speech model and no speech-to-text model, and it does not serve reranking either — so this provider entry covers Dify's LLM slot and nothing else. A knowledge base indexed in High Quality mode, a Rerank Endpoint URL, or a voice node keeps whatever provider it already has; pointing an LLM node here does not move those calls.

This configuration was read off Dify's own plugin listing and provider schema on the date below. Kunavo has not run a Dify workspace against its endpoint — no model added to a live workspace, no workflow executed, no streamed tool round-trip. A published setup page is not a test. The curl below is the part you can settle in ten seconds; everything after it is between you and Dify.

Step by step

Create a key at /app/keys and copy it — it is shown once.
In Dify, open Integrations → Model Provider, browse Install model providers (or the Marketplace) and install OpenAI-API-compatible, published by langgenius. Dify's docs note that only the workspace owner and admins can manage providers.
Click Add Model on that provider's card. The plugin offers no predefined models — it is a customizable-model provider — so every id you want is a separate entry.
Fill in the form as above. Type = LLM, Model Name = the Kunavo id exactly, API Key = your sk-kn- key, API Base URL = https://api.kunavo.com/v1, Completion mode = Chat, and Model context size from the table below. Then set Function Call Type, and Structured Output and Vision Support if you need them. Save.
Open a workflow and pick the model on the node that should use it — Dify assigns models per node, not per app, so a classifier and a final writer can sit on different ids and different prices. Apps and nodes that pick nothing fall back to Default Models → System Reasoning Model.
Run one bounded workflow, then read the charge in your Kunavo account rather than in Dify — see the note on cost display below.

Checked against Dify's OpenAI-API-compatible plugin page on September 21, 2026. Third-party settings move; if a field name here no longer matches what you see, that page is the authority, not this one.

This is the short version. The full walkthrough — model choice, what a real session costs, and the failure modes — is in the Dify cost walkthrough.

Verify before you debug the client

One request settles whether a failure is the endpoint, the key, or the configuration file. If this returns JSON, the same base URL and key work in 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-..."

Which model id to put in the field

Every text model is reachable as a model id — the live list is GET /v1/models, and the catalog with prices is on the models page. Rates are USD per 1M tokens, input / output.

Model id	Kunavo in / out	Where it fits in Dify
`claude-sonnet-5`	$2.00 / $10.00	the working model for writer and agent nodes — context size 1000000
`claude-opus-5`	$2.00 / $10.00	the node whose output a human reads, or a plan that is expensive to get wrong — 1000000
`claude-haiku-4-5`	$0.40 / $2.00	classifier, router and extraction nodes, where the call volume actually sits — 200000
`gpt-5-6-sol`	$2.00 / $12.00	a second family on the same key, as its own model entry — 1050000
`gemini-3-1-pro`	$0.70 / $4.20	long-document nodes — 1048576

Billing is per token from a prepaid balance with no monthly fee — see billing. On repeated context — which is most of what an editor or a chat client sends — prompt caching moves the bill more than the model choice does.

Two different things are called “the Dify API”

This page is about one of them, and search results mix them constantly.

Bringing a model into Dify — what the setup block above does. Dify is the client, Kunavo is the endpoint, and the credential you paste is a sk-kn- key. Every LLM node in every app in that workspace can then address the ids you added.
Calling a Dify app from your own code — the Service API that Dify exposes for a published app, with its own app- key issued by Dify. That key is Dify's, not ours, and pointing it anywhere else is not a thing you can do. Kunavo has no part in that direction.

They can run at the same time on the same app, and usually do: your backend calls the Dify app with a Dify key, and the app's nodes call Kunavo with a Kunavo key. Two keys, two bills, two places to look when something 401s.

Why Dify shows no cost for the model you added

Dify's first-party predefined model files carry a pricing block — input and output rates, and a per-token unit — and Dify multiplies your token counts by it to draw a figure in the log. The OpenAI-API-compatible provider schema declares no price, unit or currency field anywhere, checked on the date above. So for a model added through this plugin Dify has no rate to multiply by, and the money column is not a discount you found or a bug you introduced: it is a field that does not exist. Read the real figure from your Kunavo usage, and read Dify's token counts as token counts.

One related switch is worth leaving alone: Include Usage in Stream defaults to enabled and asks the endpoint for prompt and completion token counts in the final stream chunk. Turning it off is how you lose the token counts too.

If you self-host Dify

The Docker Compose stack routes outbound requests through an ssrf_proxy service, so the endpoint has to be reachable from inside the container network — not merely from the browser on your laptop. A configuration that works in one place and times out in the other is usually that, and it is a networking question rather than a credential one. The curl above, run from inside the container, answers it directly.

FAQ

How do I connect a custom OpenAI-compatible API to Dify?

Install the OpenAI-API-compatible plugin, published by langgenius, from Integrations → Model Provider → Install model providers or the Dify Marketplace. Click Add Model on its card and fill in the form: Type, Model Name, Model display name, API Key, API Base URL, Completion mode and Model context size, plus the capability switches. There are no predefined models on this provider — it is a customizable-model provider, so each model id you want is its own entry, and each one carries its own base URL and key.

Does the Dify API Base URL need /v1 at the end?

Yes for a chat model. The plugin's provider schema labels the field API Base URL, marks it required, and gives it the placeholder "Base URL, e.g. https://api.openai.com/v1", so the /v1 root is the documented form — for Kunavo, https://api.kunavo.com/v1. The bare origin is documented only for the model types where the plugin appends the API version itself, which would otherwise produce a doubled /v1/v1 path. Kunavo offers no model of those types, so the /v1 form is the one to use. A missing /v1 shows up as a 404 rather than an authentication error.

Why can't my Dify Agent node use tools on the model I added?

Because Function Call Type defaults to no_call on a model added through the OpenAI-API-compatible plugin, and Structured Output, Vision Support, Stream function calling and Thinking Mode Support all default to not supported. Those are declarations Dify believes rather than probes, so a capable model added with the defaults will still be refused by an Agent or tool-using node. Open the model's configuration and set Function Call Type to Tool Call — Function Call is the older shape — then re-test before assuming the endpoint is at fault.

Why does Dify show no price for a model added through the compatible plugin?

Because that plugin's provider schema carries no pricing fields at all, while Dify's first-party predefined model files do. Dify therefore has no per-token rate to multiply your token counts by, and shows nothing rather than an estimate. Take the money figure from the provider's own usage records and treat Dify's numbers as token counts. Leaving Include Usage in Stream enabled is what keeps those token counts arriving in the first place.

Is adding Kunavo to Dify the same as exposing a Dify app as an API?

No, and they run in opposite directions. Adding Kunavo makes Dify the client: Dify's nodes send requests to an endpoint you configured with a Kunavo key. Dify's Service API makes your code the client: it calls a published Dify app with a key Dify issued, and no base URL of ours belongs in that path. A single app commonly does both at once, which is why a 401 is worth tracing to a specific key before anything else.

Has Kunavo tested this setup in Dify?

No. What was checked on September 21 2026 is Dify's own material — the plugin listing on the Dify Marketplace and the provider schema in Dify's official plugins repository, which is where the field names, their order, the required flags and the defaults quoted here come from. Nobody has added a Kunavo model to a live Dify workspace and run a workflow through it, so nothing about streaming, tool round-trips or long-running agent loops in this client is claimed. The one thing you can settle on its own is whether the endpoint and key work, which the curl on this page does.