Dify integration guide

Low-code platformVisual developmentUpdated: 2025-11-27

Introduction

Dify is an open-source platform for building LLM applications, letting you create capable AI applications without writing code. Backed by SeaWhale AI models, you can build a wide range of intelligent applications quickly.

Key capabilities

🎨 Visual development — drag-and-drop, no programming needed
🤖 Many application types — chatbots, agents, workflows, knowledge bases
🔧 Rich node library — HTTP, databases, code execution and more
📚 RAG knowledge bases — precise answers grounded in your documents
🔌 Plugin ecosystem — a large plugin library for extensibility
🌐 API publishing — expose your app as an API in one click
🎯 Multimodal — text, images, audio and video

Application types

Type	Description	Best for	Difficulty
Chatbot	Conversational interaction	Support bots, Q&A assistants	⭐
Agent	Calls tools autonomously	Smart assistants, task automation	⭐⭐⭐
Chatflow	Visual conversation flows	Complex conversational scenarios	⭐⭐
Workflow	Automated pipelines	Data processing, batch jobs	⭐⭐⭐
Knowledge base	Document-grounded Q&A	Enterprise knowledge, document retrieval	⭐⭐

Why Dify + SeaWhale AI?

A good combination

🚀 Fast to build: Dify's visual builder plus SeaWhale AI's models
💰 Cost effective: pay as you go, pick the model that fits
🎯 Many models: Qwen, DeepSeek, GPT and more
🔒 Self-hostable: deploy locally for data control
🌟 Open source: Dify's core is fully open source

Before you begin

1. Create a Dify account

Deployment	Description	Best for
Dify Cloud	Nothing to deploy, ready to use	Trying it out, small projects
Self-hosted	Full control, no platform limits	Enterprise use, data control

Dify Cloud (recommended for beginners)

Visit the Dify website
Click "Get started for free"
Sign up with GitHub or Google
Open the workspace

Cloud limitations

The free tier allows at most 5 applications
There are monthly usage limits
Self-hosting is recommended for enterprise use

2. Get a SeaWhale AI API key

Open the SeaWhale AI console
Sign up and log in
Generate an API key on the API management page
Make sure your account has enough balance

New user credit

🎁 New accounts receive free credit
💰 Usable across all model inference services

3. Choose a model

Through Dify, SeaWhale AI supports:

Recommended models

Family	Model name	Strengths	Best for
Qwen Plus	`qwen-plus-latest`	• Strong performance • Reasoning mode	Chatbots, agents
Qwen Max	`qwen-max`	• Highest capability • Long context	Complex tasks, knowledge bases
Qwen Turbo	`qwen-turbo`	• Fast responses • Low cost	Simple chat, batch processing
Qwen VL	`qwen-vl-plus`	• Vision understanding • Multimodal	Image analysis, OCR
QVQ	`qvq-72b-preview`	• Visual reasoning • Deep analysis	Visual Q&A, scene understanding
DeepSeek	`deepseek-chat`	• Open model • Strong reasoning	Code generation, logical reasoning

Configuration

1. Install the model provider plugin

Step 1: open the Dify marketplace

Sign in to the Dify workspace
Click "Plugins" in the left sidebar
Select the "Models" tab

Step 2: install the Qwen plugin

Search for "Qwen" (or "Tongyi Qianwen")
Find the Qwen plugin (maintained by Dify)
Click "Install"
Choose the latest (or a stable) version

Important

The Qwen plugin is maintained by Dify, not by Alibaba Cloud or SeaWhale AI
If the latest version errors, try an older release (such as v0.0.40)
Using SeaWhale AI's DeepSeek models also requires the Qwen plugin

Choosing a plugin version

Latest (recommended)

✅ Most complete feature set
✅ Supports the newest models
⚠️ May be less stable

Stable (v0.0.40–v0.0.41)

✅ Reliable
✅ Good compatibility
⚠️ Fewer features

Notes

v0.0.41 validates qwen-turbo permissions
Use an API key from your default workspace
Avoid keys scoped to a sub-workspace

2. Configure the API key

Step 1: open settings

Click your avatar in the top right
Choose "Settings"
Find the "Model providers" section

Step 2: configure Qwen

Find the Qwen card and open its configuration:

Mainland China (recommended)International

text

API Key: sk-xxxxxxxxxxxxxxxx
Use international endpoint: No

text

API Key: sk-intl-xxxxxxxxxxxxxxxx
Use international endpoint: Yes

Step 3: save

Click "Save" to finish.

Common error

Message: Invalid API-key provided

Possible causes:

The API key format is wrong, or the key expired
You used a key scoped to a sub-workspace
The "use international endpoint" setting is wrong
The plugin version is incompatible

Fix:

✅ Check the API key is correct
✅ Confirm the key's region matches the endpoint setting
✅ Try installing an older plugin version (v0.0.40)
✅ Use an API key from the default workspace

3. Enable models

Step 1: open the model list

On the Qwen card, click "Show models".

Step 2: enable what you need

Toggle on the models you plan to use:

Recommended:

Model	Purpose	Enable?
`qwen-plus-latest`	Everyday chat, reasoning mode	✅ Yes
`qwen-max`	Complex tasks, long text	✅ Yes
`qwen-turbo`	Fast responses, cost first	✅ Yes
`qwen-vl-plus`	Image understanding	As needed
`qvq-72b-preview`	Visual reasoning	As needed
`deepseek-chat`	Code generation	As needed

Can't find the newest model?

If the plugin does not include the newest Qwen models yet, configure them through the OpenAI-API-compatible plugin:

Install the OpenAI-API-compatible plugin
Configure:
- API Endpoint URL: https://api.your-domain.com/compatible-mode/v1
- API Key: your SeaWhale AI API key
- Model Name: the specific model (such as qwen3-max)

This gives you access to every model SeaWhale AI supports.

Usage guide

Scenario 1: build a chatbot

The simplest application type, good for getting started.

1. Create the application

In the studio, click "Create blank app"
Choose the "Chatbot" type
Name it (for example "Support assistant")
Click "Create"

2. Select a model

In the top right of the app page:

Open the "Model" dropdown
Choose "Qwen"
Pick a specific model (such as qwen-plus-latest)

3. Configure reasoning mode (optional)

For models that support reasoning:

Find the "Reasoning mode" option in the model configuration
Set it to "True"
Save

4. Test the conversation

Type this in the chat panel on the right:

Who are you?

What to expect:

Reasoning mode on: the model's thought process is shown
Reasoning mode off: you get the answer directly

Models with reasoning support

qwen-plus-latest (Qwen3)
qwen-max
qwen3-235b-a22b
qvq-72b-preview

Scenario 2: build an agent

Agents call tools autonomously to complete complex tasks.

1. Create the agent

In the studio, click "Create blank app"
Choose the "Agent" type
Set a name and description

2. Add tools

Tool calling is what makes an agent useful:

Built-in tools:

🌐 Web search — fetch live information
📄 Document parsing — read PDF, Word and similar
🔢 Calculator — arithmetic
📧 Email — send mail automatically

Custom tools:

HTTP API calls
Database queries
Custom Python code

3. Example: a web search agent

markdown

User: Who won the 2024 Nobel Prize in Physics?

What the agent does:

1. 🔍 Calls the web search tool
2. 📊 Analyzes the results
3. ✍️ Writes a structured answer

Agent's answer:
The 2024 Nobel Prize in Physics was awarded to John J. Hopfield and
Geoffrey E. Hinton for foundational discoveries and inventions that
enable machine learning with artificial neural networks...

Scenario 3: build a workflow

Workflows suit complex automation.

1. Create the workflow

Click "Create blank app"
Choose the "Workflow" type
Open the visual editor

2. Node types

Node type	What it does	Typical use
Start	Receives input	Required
LLM	Calls a model	Generation, analysis
HTTP	Calls an API	Fetch external data
Code	Runs Python	Data processing, math
Conditional	Branches on logic	Flow control
Loop	Repeats work	Batch processing
End	Returns the result	Required

3. Example: a text-to-image workflow

Ready-made templates are available.

Step 1: download a template

Step 2: import the workflow

In the studio, click "Import DSL file"
Select the downloaded template
Click "Import"

Step 3: configure the API key

Find the environment variables icon (⚙️)
Set DASHSCOPE_API_KEY to your API key
Save

Step 4: test it

Enter a description, such as "A cute kitten"
Click "Run"
Wait for generation to finish

Notes

Text-to-image: roughly 5–30 seconds
Text-to-video: roughly 5–10 minutes
Video generation returns a URL you need to download
The template defaults to the wanx2.1-t2i-turbo model

Step 5: publish as a tool (optional)

To reuse it from other applications:

Click "Publish" in the top right
Choose "Publish as tool"
Set a tool name and description
Publish

Scenario 4: build a knowledge base

Knowledge bases use RAG to answer questions grounded in your documents.

1. Create the knowledge base

Click "Knowledge" in the left sidebar
Click "Create knowledge base"
Enter a name
Choose an embedding model

Recommended embedding models:

Model	Dimensions	Characteristics	Best for
`text-embedding-3-small`	1536	Fast, inexpensive	General documents
`text-embedding-3-large`	3072	Higher accuracy	Precise retrieval
`text-embedding-ada-002`	1536	The OpenAI classic	Broad compatibility

2. Upload documents

Supported formats:

📄 Text files: TXT, MD, CSV
📝 Office documents: PDF, Word, Excel, PPT
🌐 Web content: HTML, URLs
💬 Conversation logs: JSON

Steps:

Click "Upload document"
Select or drag in your files
Choose a chunking strategy:
- Automatic (recommended)
- Custom chunk size (500–1000 characters)
Wait for vectorization to finish

3. Create a knowledge base application

Create a new "Chatbot" application
Add the knowledge base under "Context"
Configure retrieval:
- Top K: how many chunks to retrieve (3–5 works well)
- Score threshold: similarity cutoff (0.7 works well)
Test the answers

4. Example conversation

markdown

👤 User: How can Dify be deployed?

🤖 AI (grounded in the knowledge base):
According to the documentation, Dify supports two deployment models:

1. **Cloud**
   - Nothing to deploy, ready to use
   - Good for trying it out and small projects
   - Limitation: the free tier allows at most 5 applications

2. **Self-hosted**
   - Full control, no platform limits
   - Good for enterprise use and data control
   - Supports Docker, Kubernetes and similar

See page 42 of the documentation for more.

Scenario 5: using vision models

Dify can analyze images with vision models.

1. Pick a vision model

Supported models:

Qwen-VL Plus — qwen-vl-plus (general vision understanding)
QVQ — qvq-72b-preview (visual reasoning)
GPT-4V — gpt-4-vision-preview (OpenAI)

2. Enable vision

Select a vision model in your chatbot
A "Vision" toggle appears on the left
Turn it on

3. Upload an image and ask

Click the 📎 image button in the chat panel
Upload an image (JPG, PNG or WebP)
Ask your question

Example:

markdown

👤 User: [uploads a product photo] What are this product's features?

🤖 AI (Qwen-VL Plus):
Based on the image, this is a smartwatch. Key features:

1. **Design**
   - Round face, metal construction
   - Sporty style, suitable for everyday wear

2. **Functionality**
   - Touchscreen display
   - Activity tracking
   - Heart rate monitoring

3. **Who it suits**
   - Fitness enthusiasts
   - People tracking their health

Advanced features

1. Calling models through HTTP nodes

Some models (Qwen-Omni, Qwen-Audio, Qwen-OCR) cannot be configured directly in Dify and need an HTTP node.

How to configure it

Step 1: create a workflow

Add an HTTP request node.

Step 2: configure the request

Qwen-Audio exampleQwen-OCR example

json

{
  "url": "https://api.your-domain.com/v1/audio/transcriptions",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer sk-xxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
  },
  "body": {
    "model": "qwen-audio-turbo",
    "audio": "{{audio_base64}}",
    "prompt": "Transcribe this audio"
  }
}

json

{
  "url": "https://api.your-domain.com/v1/ocr",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer sk-xxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
  },
  "body": {
    "model": "qwen-ocr",
    "image": "{{image_url}}",
    "task": "ocr"
  }
}

Step 3: handle the response

Add a Code node to parse it:

python

import json

def main(response):
    data = json.loads(response)
    result = data.get('result', '')
    return {
        "output": result
    }

Prefer streaming

To reduce the chance of an HTTP node timing out, call the API in streaming mode.

Add this to the request body:

json

{
  "stream": true
}

2. Publishing an API

Publish your application as an API for external callers.

Steps

Click "Publish" in the top right of the app page
Choose "Publish as API"
Configure:
- API name
- Access permissions
- Rate limits
Collect the API key and endpoint documentation

Example call

bash

curl -X POST https://api.dify.ai/v1/chat-messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {},
    "query": "Hello",
    "response_mode": "streaming",
    "user": "user123"
  }'

3. Webhook integration

Connect Dify applications to other systems through webhooks.

Supported platforms:

DingTalk bots
WeCom
Slack
Discord
Custom webhooks

FAQ

Q1: I get an error when configuring the API key

Message: Invalid API-key provided

Common causes and fixes:

Cause 1: an unstable plugin version

Fix:

✅ Uninstall the current plugin
✅ Install an older version (such as v0.0.40)
✅ Reconfigure the API key

Cause 2: a sub-workspace API key

Background:

Plugin v0.0.41 validates permission to call qwen-turbo
Sub-workspaces may not have that permission

Fix:

✅ Use an API key from the default workspace
✅ Or grant qwen-turbo permission to that workspace
✅ Or downgrade to v0.0.40

Cause 3: the wrong endpoint setting

Fix:

✅ Mainland China API key → set "use international endpoint" to No
✅ International API key → set "use international endpoint" to Yes

Q2: How do I use Qwen-Omni / Qwen-Audio / Qwen-OCR?

These models cannot be configured directly in Dify.

Solution:

Call them from an HTTP node inside a Chatflow or workflow.

Key points:

✅ Use an HTTP node to call the API
✅ Prefer streaming to reduce timeout risk
✅ Add error handling

See calling models through HTTP nodes.

Q3: How do I use the image generation models?

Dify does not ship an official plugin for them.

Solution:

Use our workflow templates.

Summary:

Download a template (text-to-image / text-to-video)
Import it into Dify
Set the DASHSCOPE_API_KEY environment variable
Run a test
(Optional) publish it as a tool

See scenario 3: build a workflow.

Notes:

Video generation takes a while (5 minutes or more)
The templates default to wanx2.1-t2i-turbo and wanx2.1-t2v-turbo
You can change the model in the workflow node

Q4: How do I self-host Dify?

Dify Cloud has limits (such as 5 applications), so self-hosting suits enterprise use.

Deployment options

Option	Difficulty	Best for
Docker Compose	⭐⭐	Single host, quick testing
Kubernetes	⭐⭐⭐⭐	Production, high availability
Cloud templates	⭐⭐⭐	Enterprise, one-click deployment

Docker Compose (recommended)

Step 1: prepare the environment

bash

# Install Docker and Docker Compose
curl -fsSL https://get.docker.com | sh

Step 2: download the configuration

bash

git clone https://github.com/langgenius/dify.git
cd dify/docker

Step 3: configure environment variables

Edit the .env file:

bash

# Database configuration
POSTGRES_PASSWORD=your_password
REDIS_PASSWORD=your_password

# Application configuration
SECRET_KEY=your_secret_key
API_URL=http://your-domain.com
CONSOLE_URL=http://your-domain.com/console

# Model configuration (optional)
# OPENAI_API_KEY=sk-xxx

Step 4: start the services

bash

docker-compose up -d

Step 5: open the application

Visit http://localhost in your browser.

Q5: How do I reduce token usage?

Strategies

1. Model selection

Simple tasks: qwen-turbo (lower cost)
Complex tasks: qwen-plus or qwen-max

2. Prompt tuning

Trim the system prompt
Drop unnecessary examples
Use variables instead of repeated text

3. Knowledge base tuning

Lower Top K to retrieve fewer chunks
Raise the score threshold to filter weak matches
Tune the document chunk size

4. Workflow tuning

Remove unnecessary LLM nodes
Use conditional branches to avoid duplicate calls
Cache frequently used results

5. Conversation history

Limit the number of turns (5–10 works well)
Clear conversations you no longer need
Use summarization to compress history

Best practices

1. Prompt design

Structured prompts

A useful format:

## Role
You are a [specific role] skilled at [specific capability].

## Task
Based on the user's input, do the following:
1. [Task 1]
2. [Task 2]

## Requirements
- [Requirement 1]
- [Requirement 2]

## Output format
[The format you expect]

Example prompt

A support bot:

## Role
You are SeaWhale AI's support assistant: professional, friendly and efficient.

## Task
1. Understand the user's question
2. Provide an accurate solution
3. Point to documentation where it helps

## Requirements
- Keep replies concise, under 200 words
- Use a friendly tone
- Include documentation links for technical questions

## Output format
Markdown, containing:
- A restatement of the problem
- The solution
- Related links (if any)

2. Workflow design principles

Modular design

Give each node a single responsibility
Wrap complex logic in sub-workflows
Favor reuse and maintainability

Error handling

Add exception-handling nodes
Set timeouts and retries
Log errors

Performance

Reduce unnecessary LLM calls
Cache where you can
Run independent tasks in parallel

3. Knowledge base management

Document conventions

Use a consistent format and structure
Add metadata (title, tags, date)
Refresh outdated content regularly

Chunking strategy

Chunk semantically so each piece stands alone
Chunk size: 500–1000 characters
Overlap: 50–100 characters

Vectorization

Choose an embedding model that fits your data
Rebuild indexes periodically
Monitor retrieval quality

4. Security recommendations

Security

🔒 Never hard-code secrets in prompts
🔒 Store API keys in environment variables
🔒 Rotate keys periodically
🔒 Set up API access control
🔒 Monitor for unusual calls
🔒 Keep self-hosted deployments updated

Comparing developer tools

Tool	Type	Highlights	Best for	Documentation
Dify	Low-code platform	Visual, many application types	AI app development, enterprise	This guide
Cline	VSCode extension	Plan/Act modes, automation	Code development, project work	Read
Claude Code	CLI	Conversational programming	Scripting, terminal users	Read
Cherry Studio	Desktop app	MCP integration, knowledge bases	Power users, research	Read
Chatbox	All platforms	Simple and approachable	Quick chat, general users	Read

Support

Channel	Response time	Contact
📖 Documentation	Immediate	Read the docs
💬 Live support	Weekdays 9:00–18:00	Contact support
📧 Email support	Within 24 hours	support@atalk-ai.com
🐛 Bug reports	Within 48 hours	Submit feedback

External resources

Going further

1. Developing custom plugins

Dify supports custom plugins for extending its functionality.

Plugin types:

Model providers
Tool nodes
Data source connectors

How to build one:

Read the Dify plugin documentation
Clone the plugin template
Implement the interface methods
Test locally
Publish to the marketplace

2. Multilingual applications

Building AI applications for several languages:

Option 1: separate applications

Create one application per language
Route users based on their language

Option 2: dynamic prompts

Detect the user's language with a variable
Generate the prompt in that language

Option 3: a translation node

Add a translation API node
Process everything in one language internally
Translate back to the user's language at the end

3. Data analysis applications

Building analytics applications with Dify:

Steps:

Connect to a database through an HTTP node
Process the data in a code node
Generate the analysis with an LLM node
Present the results visually

Example use cases:

Sales analysis
User behavior analysis
Financial reporting

Changelog

2025-11-27

✨ Added the full SeaWhale AI integration guide
📝 Expanded the application scenario examples
🔧 Clarified the configuration steps
📖 Added a best practices section
🐛 Reworked the FAQ

2025-10-15

🎉 Initial release

Contributing

Feedback

We welcome suggestions for improving this documentation:

Visit the feedback page
Describe your suggestion or the problem you hit
We review and act on feedback promptly

If you build something good with Dify + SeaWhale AI:

📧 Email support@atalk-ai.com
📝 Include a description and screenshots
🎁 Standout projects get promotion and rewards

Dify integration guide ​

Introduction ​

Key capabilities ​

Application types ​

Why Dify + SeaWhale AI? ​

Before you begin ​

1. Create a Dify account ​

Dify Cloud (recommended for beginners) ​

2. Get a SeaWhale AI API key ​

3. Choose a model ​

Recommended models ​

Configuration ​

1. Install the model provider plugin ​

Step 1: open the Dify marketplace ​

Step 2: install the Qwen plugin ​

2. Configure the API key ​

Step 1: open settings ​

Step 2: configure Qwen ​

Step 3: save ​

3. Enable models ​

Step 1: open the model list ​

Step 2: enable what you need ​

Usage guide ​

Scenario 1: build a chatbot ​

1. Create the application ​

2. Select a model ​

3. Configure reasoning mode (optional) ​

4. Test the conversation ​

Scenario 2: build an agent ​

1. Create the agent ​

2. Add tools ​

3. Example: a web search agent ​

Scenario 3: build a workflow ​

1. Create the workflow ​

2. Node types ​

3. Example: a text-to-image workflow ​

Scenario 4: build a knowledge base ​

1. Create the knowledge base ​

2. Upload documents ​

3. Create a knowledge base application ​

4. Example conversation ​

Scenario 5: using vision models ​

1. Pick a vision model ​

2. Enable vision ​

3. Upload an image and ask ​

Advanced features ​

1. Calling models through HTTP nodes ​

How to configure it ​

2. Publishing an API ​

Steps ​

Example call ​

3. Webhook integration ​

FAQ ​

Q1: I get an error when configuring the API key ​

Cause 1: an unstable plugin version ​

Cause 2: a sub-workspace API key ​

Cause 3: the wrong endpoint setting ​

Q2: How do I use Qwen-Omni / Qwen-Audio / Qwen-OCR? ​

Q3: How do I use the image generation models? ​

Q4: How do I self-host Dify? ​

Deployment options ​

Docker Compose (recommended) ​

Q5: How do I reduce token usage? ​

Strategies ​

Best practices ​

1. Prompt design ​

Structured prompts ​

Example prompt ​

2. Workflow design principles ​

3. Knowledge base management ​

4. Security recommendations ​

Related resources ​

Recommended reading ​

Comparing developer tools ​

Support ​

External resources ​

Going further ​

1. Developing custom plugins ​

2. Multilingual applications ​

3. Data analysis applications ​

Dify integration guide

Introduction

Key capabilities

Application types

Why Dify + SeaWhale AI?

Before you begin

1. Create a Dify account

Dify Cloud (recommended for beginners)

2. Get a SeaWhale AI API key

3. Choose a model

Recommended models

Configuration

1. Install the model provider plugin

Step 1: open the Dify marketplace

Step 2: install the Qwen plugin

2. Configure the API key

Step 1: open settings

Step 2: configure Qwen

Step 3: save

3. Enable models

Step 1: open the model list

Step 2: enable what you need

Usage guide

Scenario 1: build a chatbot

1. Create the application

2. Select a model

3. Configure reasoning mode (optional)

4. Test the conversation

Scenario 2: build an agent

1. Create the agent

2. Add tools

3. Example: a web search agent

Scenario 3: build a workflow

1. Create the workflow

2. Node types

3. Example: a text-to-image workflow

Scenario 4: build a knowledge base

1. Create the knowledge base

2. Upload documents

3. Create a knowledge base application

4. Example conversation

Scenario 5: using vision models

1. Pick a vision model

2. Enable vision

3. Upload an image and ask

Advanced features

1. Calling models through HTTP nodes

How to configure it

2. Publishing an API

Steps

Example call

3. Webhook integration

FAQ

Q1: I get an error when configuring the API key

Cause 1: an unstable plugin version

Cause 2: a sub-workspace API key

Cause 3: the wrong endpoint setting

Q2: How do I use Qwen-Omni / Qwen-Audio / Qwen-OCR?

Q3: How do I use the image generation models?

Q4: How do I self-host Dify?

Deployment options

Docker Compose (recommended)

Q5: How do I reduce token usage?

Strategies

Best practices

1. Prompt design

Structured prompts

Example prompt

2. Workflow design principles

3. Knowledge base management

4. Security recommendations

Related resources

Recommended reading

Comparing developer tools

Support

External resources

Going further

1. Developing custom plugins

2. Multilingual applications

3. Data analysis applications