Connecting Zukko to Dify: an OpenAI-compatible API for LLM apps

Dify is a platform for building LLM applications: chatbots, agents and workflows in a visual editor. You connect an OpenAI-compatible API to Dify through the OpenAI-API-compatible provider plugin, and that's exactly how Zukko is added: one fetch_... key gives you Claude, GPT and GLM models for any node. Below is the step-by-step setup, a walkthrough of the form fields, model choice per task, and common errors.

How model providers work in Dify

In current Dify versions, model providers are installed as plugins. For Zukko you need the OpenAI-API-compatible plugin, a generic provider for services with an OpenAI-format API. Once it's installed, you can add any model to it by name.

Only the workspace owner and admins can manage providers. Connected models become available to every app in that workspace.

Connecting an OpenAI-compatible API in Dify, step by step

1. Open Integrations → Model Provider (in older versions, workspace settings → Model Provider).
2. Find OpenAI-API-compatible in the provider install section or the Marketplace and install the plugin.
3. On the provider card, click Add Model.
4. Fill in the form (table below) and save. Dify validates the credentials before making the model available.
5. Repeat for every model you want to use. You don't have to retype the key: Dify stores the provider's keys and lets you pick a saved one (Manage Credentials).

Form fields

Notes on the fields people get wrong most often:

• API Base URL — the hint in the plugin itself looks like https://api.openai.com/v1, i.e. an address with /v1 but without /chat/completions. For Zukko it's exactly https://api.zukko.pro/v1.
• Model context size — the default is 4096. Leave it, and Dify will assume the model accepts only 4096 tokens and report that the request is too long on longer prompts or large knowledge base chunks. Enter the real context: 1,000,000 for claude-opus-5-5, claude-sonnet-5, gpt-5.6-sol and gpt-5.6-luna, and 128,000 for glm-5.3 and glm-5.3-flash. You can set less if you want to cap spending.
• Upper bound for max tokens — also 4096 by default. It's the upper limit of the max tokens slider in nodes; set what you actually need for answers.
• Function calling, Vision and other capabilities — the form has separate settings for tool calls, images and other input types. They're needed for agents and nodes with tools. Enable them only if the model supports them, and verify with a test request.

For the current list of IDs, call GET https://api.zukko.pro/v1/models (see the models documentation↗) or open the "Models" page in the dashboard.

Default models and the knowledge base

The Default Models button in the top-right corner of the providers page sets the models used when an app or node doesn't choose one:

• System Reasoning Model — for general tasks; you can use a Zukko model here;
• Embedding Model and Rerank Model — for indexing and searching the knowledge base.

Zukko currently offers only chat models, with no embedding or rerank models. For the knowledge base, connect a separate embedding provider, and use Zukko models to generate answers.

Model choice and cost

In Dify you choose a model per node, which is handy for saving money. An example workflow with three LLM nodes:

• request classification on glm-5.3-flash, 800 tokens: 800 × $0.04 / 1,000,000 = $0.000032;
• the main answer on claude-sonnet-5, 6,000 tokens: 6,000 × $0.3 / 1,000,000 = $0.0018;
• answer review on gpt-5.6-luna, 1,500 tokens: 1,500 × $0.1 / 1,000,000 = $0.00015.

That's $0.001982 per run, or about $1.98 per 1,000 runs. Check for yourself whether a cheaper model works for a given node: run 20–30 real examples through the node on two models and compare the results and spending in the dashboard's "Usage" section.

Common errors

Dify won't save the model: credential validation failed

Usually it's the address (no /v1, or an extra /chat/completions), a typo in the model ID, or a key copied partially. Check all three fields.

401 and 403

401 means an invalid key: it starts with fetch_ and must be copied in full. 403 model_not_allowed_for_key means the model isn't on this key's allowed list; add it in the key settings in the dashboard.

The query or prompt is too long

Check Model context size: if it's still 4096, raise it to the model's real context. If the request truly exceeds the context, the API returns 413 — shorten the prompt or reduce the number of knowledge base chunks.

400 on Claude models

claude-sonnet-5 and claude-opus-5-5 may reject a request with a 400 error if temperature is anything other than 1 or top_p is below 0.99. In Dify, LLM node parameters are enabled individually: for Claude, leave temperature and top_p switched off.

402 and 429

402 means the balance ran out; top it up in the dashboard. 429 means too many requests; lower the concurrency when running workflows in bulk.

FAQ

Can I split spending by app?

Yes. Create separate keys in the dashboard with their own daily and monthly limits and add them to Dify as different credentials. Spending per key is shown under "Usage"; how limits work is described in the key limits documentation↗.

Does this work in Dify Cloud and self-hosted Dify?

The OpenAI-API-compatible plugin is available in both. For self-hosted Dify, make sure the server can reach api.zukko.pro over the internet.

Do I need a separate provider for Claude models?

No. Zukko converts formats itself, so Claude models go into the same OpenAI-API-compatible provider as GPT and GLM. More in the format selection docs↗.

Where do I start?

Create a key in the Zukko dashboard↗, add one model to Dify, for example claude-sonnet-5, and build a simple chatbot to test the connection.