Dify is one of the most popular open-source platforms for building LLM apps: chatbots, agents, visual workflows and knowledge-base Q&A, all without writing much code. The friction usually starts at the model layer. Each official provider wants its own account and billing, and teams that want Claude, GPT and Gemini in the same workflow end up juggling several keys. Dify solves this with a generic OpenAI-compatible provider type, which lets you point it at any gateway that speaks the OpenAI protocol. This guide shows exactly how to connect Dify to Zivv, what every field means, how Dify versions differ, and how to fix the errors people hit most often.
How Dify Handles Model Providers
Every model in Dify belongs to a model provider. In the settings area you will find official providers such as OpenAI, Anthropic and Gemini, plus a generic one called OpenAI-API-compatible. The generic provider is the important one here: any service that implements the OpenAI chat API can be added as a custom model through it.
Dify reworked its provider system around version 1.0, so the steps depend on what you are running:
| Dify version | Where providers live | What you do |
|---|---|---|
| Older 0.x releases | Built into Settings, Model Provider | Open the provider and configure it |
| 1.x plugin-based releases | Installed from the plugin marketplace | Install the OpenAI-API-compatible plugin, then configure it |
If you cannot find OpenAI-API-compatible in your provider list, you are most likely on a plugin-based release and have not installed that plugin yet. Search the marketplace and install it. Button labels and field order shift between releases, so treat the field descriptions below as the reference and match them to whatever your screen shows.
Before You Start
- Create a Zivv account and top up your balance at register. The recharge rate is ¥1 = $1.
- Create an API key in the console (it starts with
sk-). Name it something like "Dify production" so its usage is easy to separate from your other tools. - Copy the model IDs you plan to use from Model Hub, for example
claude-sonnet-5,gpt-5.5orgemini-3.5-flash.
If you self-host Dify, confirm that the server running it can reach the gateway:
curl https://zivv.pro/v1/models \
-H "Authorization: Bearer sk-your-key-here"A JSON list of models means networking and your key both work. Keep that output handy, because the id values are exactly what you will type into Dify.
Option 1: The OpenAI-API-compatible Provider (Recommended)
This is the most reliable path. Zivv's OpenAI-compatible endpoint serves Claude, GPT and Gemini models through one interface, so a single provider covers almost everything you will build in Dify.
Add a model
Open Settings, go to Model Provider, find OpenAI-API-compatible (install it first on plugin-based versions) and choose to add a model.
Fill in the fields
| Field | Value | Notes |
|---|---|---|
| Model type | LLM | Used by chat apps, agents and workflow LLM nodes |
| Model name | claude-sonnet-5 | Must match the id from /v1/models exactly |
| API key | Your sk- Zivv key | No leading or trailing spaces |
| API endpoint URL | https://zivv.pro/v1 | Stop at /v1 |
| Completion mode | Chat | Modern models all use chat mode |
| Model context size | The model's real context window | See below |
| Max tokens upper bound | The model's output limit | Caps the max output slider |
| Function calling | Enable if the model supports tools | Needed for reliable agents |
| Vision support | Enable if the model accepts images | Needed for image inputs |
Some versions show extra optional fields, such as a display name or a stream delimiter. Leave those at their defaults unless you have a specific reason to change them.
Save and verify
When you save, Dify sends a test request with your credentials. Once it passes, the model shows up in every model dropdown across your workspace. Repeat the process for each model you want; the key and URL stay the same, only the model name changes.
Getting the base URL right
The base URL causes more failed setups than everything else combined. The rule is the same one covered in the Cursor setup guide:
| What you enter | Result |
|---|---|
https://zivv.pro | 404, the /v1 prefix is missing |
https://zivv.pro/v1/chat/completions | Path gets appended twice, request fails |
https://zivv.pro/v1 | Correct |
Context size and max tokens
These two fields do not change what the model can do. They change how Dify uses it. Context size is the threshold Dify uses when trimming conversation history and retrieved knowledge chunks. Max tokens sets the range of the output-length control in your nodes.
Use the model's published context window and output limit, and be conservative if you are unsure. Setting the context too high leads to context-length errors on long conversations. Setting it too low makes Dify trim history early, so the app seems to forget what was said a few turns ago. Check current numbers in Model Hub or the provider's documentation rather than guessing.
Option 2: The Anthropic Provider Plugin
If you want Claude models on the native Anthropic protocol, for example to use Anthropic-specific parameters, look at the Anthropic provider. What matters is whether your version exposes a custom API URL field:
- If it does, enter your Zivv key and set the API URL to
https://zivv.pro. The native Anthropic entry point has no/v1suffix. - If it does not, that version only talks to the official endpoint. Use Option 1 and call Claude models through the OpenAI-compatible endpoint instead.
For most Dify workloads, including support bots, workflows and RAG apps, Option 1 is all you need. When in doubt, pick it: fewer fields, broader compatibility.
What About Knowledge Base Embeddings?
Dify knowledge bases need an embedding model to vectorize documents, and some retrieval setups also use a rerank model. Zivv does not offer an embeddings endpoint, so split the work:
- Connect LLMs (chat, reasoning, workflow nodes) to Zivv
- Use another provider that offers embeddings and rerank, or a self-hosted open-source embedding model, for your knowledge bases
Dify configures these independently. In the system model settings you can pick a default reasoning model and a default embedding model from different providers. When adding models under OpenAI-API-compatible with your Zivv key, choose the LLM type only.
Choosing Models Inside Your Apps
After setup, pick your new models in the LLM node of any chat app, agent or workflow. A sensible default split:
| Use case | Suggested model |
|---|---|
| Support bots, FAQ answering | gemini-3.5-flash or gpt-5.4 |
| Classification and extraction nodes | A mid-tier model |
| Multi-step agents and reasoning | claude-sonnet-5 or gpt-5.5 |
| Hard analysis, long-form writing | claude-opus-4-8 |
Workflows are where Dify really saves money: route intent classification through a cheap model and reserve the strong model for the final answer. The multi-model routing guide covers this pattern in depth.
Troubleshooting Common Errors
Credential validation fails or returns 401. The key was copied incompletely, includes whitespace, or has been disabled. Check the key status and your balance in the console. The 401 troubleshooting guide walks through every check.
404 or model not found. The model name does not match the platform ID, or the model is not in your key's group. Call /v1/models with curl to confirm, then see the 404 model guide.
Context length exceeded. Long conversations or too many retrieved chunks pushed the request past the model's window. Lower the retrieval count, enable history trimming, or check that your context size field is not set higher than the model's real limit.
The agent never calls tools. Make sure you enabled function calling when you added the model. Without it, Dify may fall back to prompt-based tool emulation, which is far less reliable.
Timeouts on self-hosted Dify. Run curl from the Dify server. If curl also times out, it is an outbound networking issue on the server. If curl is fine but Dify times out, check the container's network and proxy settings, and consider raising Dify's own timeouts for long generations.
Occasional 429 or 5xx. Usually short-term congestion on a single model. Add retries to the workflow node or switch models. See the 429 guide.
Running Dify for a Team
Dify is typically a shared platform with many apps and owners, so a little structure pays off:
- Use a separate key per Dify instance or per important app so usage is attributable
- Put keys under Zivv Teams with daily, monthly and total budgets, so a looping workflow cannot drain the balance
- Review usage by key and by model regularly to find nodes that can move to a cheaper model
On privacy: Zivv does not store prompt or response bodies. It only records token usage for billing.
FAQ
Why can't I find the OpenAI-API-compatible provider in Dify? On plugin-based versions you have to install the OpenAI-API-compatible plugin from the marketplace first. Older versions include it under Settings, Model Provider.
Should the Dify API endpoint URL include /v1? Yes. Use https://zivv.pro/v1. Do not enter the bare domain, and do not append /chat/completions.
Can I use a Zivv key for Dify knowledge base embeddings? No. Zivv does not provide an embeddings endpoint. Use another provider for embeddings and rerank, and keep Zivv for LLM inference. Dify lets you mix providers.
Can I add several models under one provider? Yes. Add each model name as its own entry under OpenAI-API-compatible, reusing the same key and URL.
Is the setup different for Dify Cloud and self-hosted Dify? The fields are identical. Self-hosted installs also need outbound access to zivv.pro and sensible proxy and timeout settings.
Wrap-Up
Connecting Dify to a gateway comes down to one OpenAI-API-compatible model entry: URL https://zivv.pro/v1, an sk- key, the exact model ID, and an honest context size. Handle embeddings with a separate provider and let one key cover everything else. For endpoint details, see the API reference, and if you are new to gateways, start with what an AI API gateway is. Ready to try it? Create your key and have Dify running in about ten minutes.