Dify API接口调用教程｜附配置文件

在企业知识库问答、AI客服、自动化工作流、智能表单处理等场景中，Dify 是一个非常常用的 AI 应用开发平台。它既提供了可视化的应用编排能力，也提供了标准化的 API 接口，方便开发者将 AI 应用集成到网站、小程序、企业微信、钉钉、飞书、内部系统或第三方业务平台中。

本文将围绕 Dify API 接口调用 展开，详细介绍如何获取 API Key、如何调用 Chatflow、Workflow、文本生成应用接口，并提供常用的 curl、Python、JavaScript 调用示例，同时附上可直接参考的配置文件，帮助你快速完成 Dify API 接入。

一、Dify API 简介

Dify 的 API 能够将你在 Dify 平台中创建的 AI 应用开放给外部系统调用。简单来说，你可以先在 Dify 后台搭建好一个 AI 应用，例如：

• 智能客服机器人
• 企业知识库问答助手
• SQL 生成助手
• 文案生成工具
• 合同审核工作流
• OCR 信息抽取流程
• 多步骤自动化 AI 工作流

然后通过 API 将这些能力嵌入到自己的业务系统中。

Dify API 常见调用方式包括：

1. Chat Messages API
   用于调用聊天类应用，例如 Chatbot、Chatflow。

2. Completion Messages API
   用于调用文本生成类应用，例如标题生成、摘要生成、文案改写。

3. Workflow Run API
   用于调用工作流应用，适合多步骤任务处理。

4. File Upload API
   用于上传文件，例如图片、PDF、Word、Excel 等，然后在应用中使用。

5. Conversation API
   用于管理会话，例如查询历史会话、重命名会话、删除会话。

二、调用 Dify API 前的准备工作

在正式调用接口之前，需要完成以下准备工作。

1. 创建 Dify 应用

进入 Dify 控制台后，可以根据业务需求创建不同类型的应用：

• 聊天助手
• Agent
• Chatflow
• Workflow
• 文本生成应用

如果你是第一次接入 API，建议先创建一个简单的聊天助手或 Workflow，便于测试接口是否正常。

2. 发布应用

应用创建完成后，需要点击右上角的 发布 按钮。

如果应用没有发布，外部 API 可能无法调用到最新配置。

3. 获取 API Key

在应用详情页面中，找到：

访问 API / API Access

然后创建一个 API Key。

API Key 一般格式类似：

app-xxxxxxxxxxxxxxxxxxxxxxxx

调用接口时，需要将该 Key 放在请求头中：

Authorization: Bearer YOUR_API_KEY

请注意，API Key 属于敏感信息，不建议直接写死在前端代码中，更推荐放在后端服务或环境变量中。

三、Dify API 基础地址

如果你使用的是 Dify 官方云服务，API 地址通常为：

https://api.dify.ai/v1

如果你是私有化部署，则地址取决于你的部署域名，例如：

https://dify.example.com/v1

或者：

http://192.168.1.100/v1

在后续示例中，我们统一使用：

https://api.dify.ai/v1

作为 API Base URL。

四、通用请求头说明

调用 Dify API 时，常用请求头如下：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

其中：

五、响应模式说明：blocking 与 streaming

Dify API 通常支持两种响应模式：

1. blocking

blocking 表示阻塞式返回。也就是说，服务端会等 AI 完整生成结果后，再一次性返回给调用方。

适合场景：

• 后台批处理
• 短文本生成
• 不需要实时展示结果的接口
• 工作流自动化任务

示例：

{
  "response_mode": "blocking"
}

2. streaming

streaming 表示流式返回。AI 生成内容时，会边生成边返回，前端可以实时展示打字机效果。

适合场景：

• 聊天机器人
• 在线客服
• Web 对话窗口
• 需要提升用户体验的长文本生成

示例：

{
  "response_mode": "streaming"
}

如果你开发的是网页聊天机器人，推荐使用 streaming。如果你是后端服务调用并希望简单处理结果，可以先使用 blocking。

六、调用聊天应用 API

聊天应用接口常用于 Chatbot、Chatflow 等应用。

1. 接口地址

POST /chat-messages

完整地址：

https://api.dify.ai/v1/chat-messages

2. 请求参数说明

常见请求参数如下：

3. curl 调用示例

curl -X POST 'https://api.dify.ai/v1/chat-messages' \
  -H 'Authorization: Bearer app-xxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {},
    "query": "请介绍一下 Dify 的 API 调用方式",
    "response_mode": "blocking",
    "user": "user-001"
  }'

4. blocking 响应示例

{
  "event": "message",
  "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227",
  "id": "9da23599-e713-473b-982c-4328d4f5c78a",
  "message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
  "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
  "mode": "chat",
  "answer": "Dify API 可以通过 HTTP 请求调用...",
  "metadata": {
    "usage": {
      "prompt_tokens": 120,
      "completion_tokens": 300,
      "total_tokens": 420
    }
  },
  "created_at": 1700000000
}

其中最重要的是：

"answer": "Dify API 可以通过 HTTP 请求调用..."

如果你需要支持连续对话，需要保存返回值中的：

"conversation_id"

下一轮调用时带上该字段即可。

5. 连续对话示例

第一轮请求：

{
  "inputs": {},
  "query": "什么是 RAG？",
  "response_mode": "blocking",
  "user": "user-001"
}

接口会返回：

{
  "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
  "answer": "RAG 是检索增强生成..."
}

第二轮请求时带上 conversation_id：

curl -X POST 'https://api.dify.ai/v1/chat-messages' \
  -H 'Authorization: Bearer app-xxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {},
    "query": "它适合用在哪些企业场景？",
    "response_mode": "blocking",
    "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
    "user": "user-001"
  }'

这样 Dify 就会基于同一个会话上下文继续回答。

七、调用文本生成应用 API

如果你创建的是文本生成应用，例如：

• 文章标题生成器
• 小红书文案生成器
• 简历优化工具
• 邮件生成助手
• 摘要生成工具

则通常使用 Completion Messages API。

1. 接口地址

POST /completion-messages

完整地址：

https://api.dify.ai/v1/completion-messages

2. 请求示例

假设你的文本生成应用中定义了一个变量：

topic

用于接收主题。

可以这样调用：

curl -X POST 'https://api.dify.ai/v1/completion-messages' \
  -H 'Authorization: Bearer app-xxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {
      "topic": "人工智能在企业数字化转型中的应用"
    },
    "response_mode": "blocking",
    "user": "user-001"
  }'

3. 响应示例

{
  "event": "message",
  "task_id": "b3a7d34d-56fd-4c21-997f-f21db2a9781c",
  "id": "f1c2d3e4-1111-2222-3333-444455556666",
  "message_id": "f1c2d3e4-1111-2222-3333-444455556666",
  "mode": "completion",
  "answer": "人工智能正在成为企业数字化转型的重要驱动力...",
  "metadata": {
    "usage": {
      "prompt_tokens": 80,
      "completion_tokens": 600,
      "total_tokens": 680
    }
  },
  "created_at": 1700000000
}

八、调用 Workflow 工作流 API

Workflow 是 Dify 中非常强大的能力，适合处理复杂任务，例如：

• 输入一段文本，自动分类、摘要、生成报告
• 上传合同文件，自动提取关键信息
• 输入客户问题，判断意图，再路由到不同知识库
• 多模型协作完成内容生成
• 调用 HTTP 工具与业务系统联动

1. 接口地址

POST /workflows/run

完整地址：

https://api.dify.ai/v1/workflows/run

2. 请求参数说明

3. Workflow 调用示例

假设你的 Workflow 开始节点定义了两个变量：

请求示例：

curl -X POST 'https://api.dify.ai/v1/workflows/run' \
  -H 'Authorization: Bearer app-xxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {
      "title": "Dify API接口调用教程",
      "style": "技术教程"
    },
    "response_mode": "blocking",
    "user": "user-001"
  }'

4. Workflow 响应示例

{
  "workflow_run_id": "abc123",
  "task_id": "task-123456",
  "data": {
    "id": "abc123",
    "workflow_id": "workflow-001",
    "status": "succeeded",
    "outputs": {
      "result": "这是一篇关于 Dify API 调用的技术教程..."
    },
    "error": null,
    "elapsed_time": 3.25,
    "total_tokens": 1200,
    "created_at": 1700000000,
    "finished_at": 1700000003
  }
}

一般来说，最终结果会在：

data.outputs

中。

例如：

{
  "result": "这是一篇关于 Dify API 调用的技术教程..."
}

九、Python 调用 Dify API 示例

在实际项目中，后端调用 Dify API 是最常见的方式。下面以 Python 为例。

1. 安装依赖

pip install requests python-dotenv

2. 创建 .env 配置文件

DIFY_API_BASE=https://api.dify.ai/v1
DIFY_API_KEY=app-xxxxxxxxxxxxxxxxxxxxxxxx
DIFY_USER_ID=user-001

3. Python 调用聊天接口

新建文件：

dify_chat.py

代码如下：

import os
import requests
from dotenv import load_dotenv

load_dotenv()

DIFY_API_BASE = os.getenv("DIFY_API_BASE")
DIFY_API_KEY = os.getenv("DIFY_API_KEY")
DIFY_USER_ID = os.getenv("DIFY_USER_ID", "default-user")


def chat_with_dify(query, conversation_id=None):
    url = f"{DIFY_API_BASE}/chat-messages"

    headers = {
        "Authorization": f"Bearer {DIFY_API_KEY}",
        "Content-Type": "application/json"
    }

    payload = {
        "inputs": {},
        "query": query,
        "response_mode": "blocking",
        "user": DIFY_USER_ID
    }

    if conversation_id:
        payload["conversation_id"] = conversation_id

    response = requests.post(url, headers=headers, json=payload, timeout=60)
    response.raise_for_status()

    return response.json()


if __name__ == "__main__":
    result = chat_with_dify("请用通俗语言解释什么是 Dify API")
    print("回答：", result.get("answer"))
    print("会话ID：", result.get("conversation_id"))

运行：

python dify_chat.py

4. Python 调用 Workflow 接口

新建文件：

dify_workflow.py

代码如下：

import os
import requests
from dotenv import load_dotenv

load_dotenv()

DIFY_API_BASE = os.getenv("DIFY_API_BASE")
DIFY_API_KEY = os.getenv("DIFY_API_KEY")
DIFY_USER_ID = os.getenv("DIFY_USER_ID", "default-user")


def run_workflow(inputs):
    url = f"{DIFY_API_BASE}/workflows/run"

    headers = {
        "Authorization": f"Bearer {DIFY_API_KEY}",
        "Content-Type": "application/json"
    }

    payload = {
        "inputs": inputs,
        "response_mode": "blocking",
        "user": DIFY_USER_ID
    }

    response = requests.post(url, headers=headers, json=payload, timeout=120)
    response.raise_for_status()

    return response.json()


if __name__ == "__main__":
    result = run_workflow({
        "title": "Dify API接口调用教程",
        "style": "详细技术教程"
    })

    outputs = result.get("data", {}).get("outputs", {})
    print(outputs)

十、JavaScript / Node.js 调用示例

如果你的项目是 Node.js 后端，也可以通过 fetch 或 axios 调用。

1. 安装 dotenv

npm install dotenv

如果你的 Node.js 版本较低，可能还需要安装：

npm install node-fetch

2. 创建 .env

DIFY_API_BASE=https://api.dify.ai/v1
DIFY_API_KEY=app-xxxxxxxxxxxxxxxxxxxxxxxx
DIFY_USER_ID=user-001

3. Node.js 调用聊天接口

新建：

dify-chat.js

代码如下：

require("dotenv").config();

const DIFY_API_BASE = process.env.DIFY_API_BASE;
const DIFY_API_KEY = process.env.DIFY_API_KEY;
const DIFY_USER_ID = process.env.DIFY_USER_ID || "default-user";

async function chatWithDify(query, conversationId = null) {
  const url = `${DIFY_API_BASE}/chat-messages`;

  const payload = {
    inputs: {},
    query,
    response_mode: "blocking",
    user: DIFY_USER_ID
  };

  if (conversationId) {
    payload.conversation_id = conversationId;
  }

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${DIFY_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`Dify API Error: ${response.status} ${errorText}`);
  }

  return await response.json();
}

(async () => {
  const result = await chatWithDify("请介绍一下 Dify Workflow 的作用");
  console.log("回答：", result.answer);
  console.log("会话ID：", result.conversation_id);
})();

运行：

node dify-chat.js

十一、流式响应调用方式

如果你希望像 ChatGPT 一样实现“逐字输出”的效果，需要使用 streaming 模式。

1. curl 流式调用示例

curl -N -X POST 'https://api.dify.ai/v1/chat-messages' \
  -H 'Authorization: Bearer app-xxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {},
    "query": "请写一篇关于 Dify API 的介绍",
    "response_mode": "streaming",
    "user": "user-001"
  }'

注意这里使用了：

-N

它可以让 curl 不缓存输出内容，便于观察实时返回。

2. 流式返回格式

流式返回通常是 SSE 格式，类似：

data: {"event":"message","answer":"Dify","conversation_id":"xxx"}

data: {"event":"message","answer":" API","conversation_id":"xxx"}

data: {"event":"message","answer":" 可以","conversation_id":"xxx"}

data: {"event":"message_end","metadata":{"usage":{"total_tokens":300}}}

前端或后端需要逐行读取 data: 后面的 JSON，并将 answer 字段拼接起来。

3. 前端处理建议

如果你在前端实现流式输出，需要注意：

1. 不要直接在前端暴露 Dify API Key。
2. 推荐由后端转发请求。
3. 后端读取 Dify 的 SSE 流，再转发给前端。
4. 前端使用 EventSource 或 fetch + ReadableStream 展示内容。

十二、文件上传接口调用

在一些场景中，用户需要上传 PDF、图片、Word 文档等文件，然后让 Dify 应用读取文件内容。

1. 文件上传接口

POST /files/upload

完整地址：

https://api.dify.ai/v1/files/upload

2. curl 上传文件示例

curl -X POST 'https://api.dify.ai/v1/files/upload' \
  -H 'Authorization: Bearer app-xxxxxxxxxxxxxxxxxxxxxxxx' \
  -F 'file=@/path/to/demo.pdf' \
  -F 'user=user-001'

3. 文件上传响应示例

{
  "id": "file-abc123",
  "name": "demo.pdf",
  "size": 102400,
  "extension": "pdf",
  "mime_type": "application/pdf",
  "created_by": "user-001",
  "created_at": 1700000000
}

上传成功后，需要记录文件 ID，例如：

file-abc123

4. 在聊天接口中携带文件

curl -X POST 'https://api.dify.ai/v1/chat-messages' \
  -H 'Authorization: Bearer app-xxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {},
    "query": "请总结这个文件的核心内容",
    "response_mode": "blocking",
    "user": "user-001",
    "files": [
      {
        "type": "document",
        "transfer_method": "local_file",
        "upload_file_id": "file-abc123"
      }
    ]
  }'

常见文件类型可以根据应用配置选择，例如：

• document
• image
• audio
• video
• custom

具体支持类型与 Dify 应用配置有关。

十三、附：项目配置文件示例

下面提供一个适合后端服务使用的配置文件示例。

1. .env.example

# Dify API 基础地址
DIFY_API_BASE=https://api.dify.ai/v1

# Dify 应用 API Key
DIFY_API_KEY=app-xxxxxxxxxxxxxxxxxxxxxxxx

# 默认用户 ID
DIFY_USER_ID=default-user

# 请求超时时间，单位：秒
DIFY_TIMEOUT=60

# 是否启用流式响应
DIFY_STREAMING=false

2. config.yaml

如果你的项目更喜欢使用 YAML 配置，可以参考：

dify:
  api_base: "https://api.dify.ai/v1"
  api_key: "app-xxxxxxxxxxxxxxxxxxxxxxxx"
  user_id: "default-user"
  timeout: 60
  response_mode: "blocking"

apps:
  chat:
    endpoint: "/chat-messages"
    inputs: {}

  completion:
    endpoint: "/completion-messages"

  workflow:
    endpoint: "/workflows/run"

logging:
  level: "INFO"
  enable_request_log: true
  enable_response_log: false

3. Docker Compose 环境变量示例

如果你的业务服务通过 Docker 部署，可以这样配置：

services:
  dify-api-demo:
    image: your-app-image:latest
    container_name: dify-api-demo
    environment:
      DIFY_API_BASE: "https://api.dify.ai/v1"
      DIFY_API_KEY: "app-xxxxxxxxxxxxxxxxxxxxxxxx"
      DIFY_USER_ID: "default-user"
      DIFY_TIMEOUT: "60"
    ports:
      - "8080:8080"
    restart: always

十四、常见错误与排查方法

1. 401 Unauthorized

出现 401 一般是认证失败。

常见原因：

• API Key 写错
• 请求头没有加 Authorization
• Bearer 拼写错误
• API Key 已被删除或失效
• 调用了错误应用的 API Key

正确格式：

Authorization: Bearer app-xxxxxxxxxxxxxxxxxxxxxxxx

2. 404 Not Found

常见原因：

• API Base URL 写错
• 私有化部署路径不正确
• 接口地址拼写错误
• 使用了不存在的 endpoint

例如应为：

/chat-messages

而不是：

/chat/message

3. 400 Bad Request

常见原因：

• 缺少必填字段
• inputs 中变量名和 Dify 应用中定义的不一致
• response_mode 值不合法
• 文件参数格式不正确

建议检查应用开始节点或提示词变量定义，确保请求体中的字段完全匹配。

4. 超时问题

如果 Workflow 较复杂，模型生成时间较长，可能出现超时。

解决办法：

• 增大后端 HTTP 请求超时时间
• 使用 streaming 模式
• 简化 Workflow 节点
• 减少单次输入内容长度
• 优化模型选择和提示词

5. 返回内容为空

常见原因：

• Workflow 结束节点没有正确输出变量
• 文本生成应用提示词配置不完整
• 知识库未命中且应用设置为不回答
• 模型调用失败但未正确处理错误

可以在 Dify 控制台查看应用运行日志，定位具体节点的问题。

十五、安全接入建议

在生产环境中调用 Dify API，需要特别注意安全问题。

1. 不要在前端暴露 API Key

错误示例：

const apiKey = "app-xxxxxxxxxxxxxxxxxxxxxxxx";

如果把 API Key 写在前端代码中，用户可以通过浏览器开发者工具直接看到，从而盗用你的接口额度。

推荐方式：

前端 → 你的后端服务 → Dify API

由后端统一保存 API Key，并进行鉴权、限流和日志记录。

2. 对用户请求进行限流

建议按用户维度限制调用频率，例如：

• 每分钟最多请求 10 次
• 每天最多请求 100 次
• 单次输入最多 5000 字
• 上传文件大小限制为 10MB

这样可以避免恶意刷接口导致费用失控。

3. 记录调用日志

建议记录以下信息：

不过，涉及隐私或敏感内容时，应做好脱敏处理。

4. 做好异常兜底

AI 接口可能因为网络、模型、额度、参数等原因失败。业务系统中应提供兜底提示，例如：

当前服务繁忙，请稍后再试。

不要直接把原始异常信息暴露给终端用户。

十六、推荐的后端封装方式

在正式项目中，不建议每个业务模块都直接拼接 Dify API 请求。更好的方式是封装一个统一的 Dify Client。

例如：

DifyClient
├── chat()
├── completion()
├── run_workflow()
├── upload_file()
└── stream_chat()

这样做的好处是：

1. API Key 统一管理。
2. 错误处理统一。
3. 日志记录统一。
4. 超时时间统一。
5. 后续切换 Dify 地址或应用 Key 更方便。
6. 方便增加重试、限流、监控等能力。

十七、完整 Python Client 示例

下面给出一个简单但实用的封装版本。

import requests


class DifyClient:
    def __init__(self, api_base, api_key, user_id="default-user", timeout=60):
        self.api_base = api_base.rstrip("/")
        self.api_key = api_key
        self.user_id = user_id
        self.timeout = timeout

    @property
    def headers(self):
        return {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

    def chat(self, query, inputs=None, conversation_id=None):
        url = f"{self.api_base}/chat-messages"

        payload = {
            "inputs": inputs or {},
            "query": query,
            "response_mode": "blocking",
            "user": self.user_id
        }

        if conversation_id:
            payload["conversation_id"] = conversation_id

        return self._post(url, payload)

    def completion(self, inputs):
        url = f"{self.api_base}/completion-messages"

        payload = {
            "inputs": inputs,
            "response_mode": "blocking",
            "user": self.user_id
        }

        return self._post(url, payload)

    def run_workflow(self, inputs):
        url = f"{self.api_base}/workflows/run"

        payload = {
            "inputs": inputs,
            "response_mode": "blocking",
            "user": self.user_id
        }

        return self._post(url, payload)

    def _post(self, url, payload):
        try:
            response = requests.post(
                url,
                headers=self.headers,
                json=payload,
                timeout=self.timeout
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            raise RuntimeError(f"Dify API request failed: {str(e)}")


if __name__ == "__main__":
    client = DifyClient(
        api_base="https://api.dify.ai/v1",
        api_key="app-xxxxxxxxxxxxxxxxxxxxxxxx",
        user_id="user-001"
    )

    result = client.chat("请介绍一下 Dify API 的使用方式")
    print(result.get("answer"))

十八、实际业务接入流程建议

如果你要把 Dify API 接入到真实业务系统，可以按照下面的流程实施：

1. 明确业务场景
   例如智能客服、知识库问答、文档分析或内容生成。

2. 在 Dify 中创建应用
   根据场景选择 Chatbot、Chatflow、Workflow 或文本生成应用。

3. 配置模型和提示词
   调整系统提示词、变量、知识库、工具和工作流节点。

4. 发布应用并获取 API Key
   确保 API Key 与应用一一对应。

5. 本地使用 curl 测试
   先确认接口地址、请求头、请求体是否正确。

6. 后端封装 Dify Client
   不要在业务代码中重复写请求逻辑。

7. 接入前端或业务系统
   前端请求你的后端，由后端转发到 Dify。

8. 增加日志、限流和异常处理
   保障生产环境稳定性。

9. 上线后持续观察调用效果
   根据日志优化提示词、知识库和 Workflow 节点。

十九、总结

Dify API 的核心调用逻辑并不复杂，本质上就是通过 HTTP 请求将用户输入传给 Dify 应用，再获取 AI 返回结果。对于聊天类应用，通常使用 /chat-messages；对于文本生成应用，使用 /completion-messages；对于 Workflow 应用，则使用 /workflows/run。

实际开发中需要重点关注以下几点：

• API Key 必须放在后端或安全环境变量中。
• inputs 参数要与 Dify 应用中的变量保持一致。
• 连续对话需要保存并传递 conversation_id。
• 长文本或聊天场景推荐使用 streaming。
• 生产环境要做好限流、日志、异常处理和超时控制。
• Workflow 的输出结果通常在 data.outputs 中。

掌握以上内容后，你就可以将 Dify 应用稳定地接入到自己的系统中，实现智能问答、内容生成、文档分析、工作流自动化等多种 AI 能力。