Dify API 接入实战：从获取 Key 到聊天、工作流调用全流程源码示例

发布人：慈云数据-客服中心发布时间：20小时前阅读量：0

Dify API接口调用教程｜附源码

在大模型应用开发中，很多团队会选择使用 Dify 来快速搭建 AI 应用，例如智能客服、知识库问答、文本生成助手、工作流自动化工具等。Dify 的优势在于：它既提供了可视化编排能力，又提供了标准化 API 接口，开发者可以很方便地将已经搭建好的 AI 应用集成到网站、App、企业系统或自动化脚本中。

本文将围绕 Dify API 接口调用 展开，详细介绍如何获取 API Key、如何调用聊天应用接口、文本生成接口、工作流接口，并提供 Python、Node.js、JavaScript 前端调用示例源码，帮助你快速完成 Dify API 的接入。

一、什么是 Dify API？

Dify 是一个开源的大语言模型应用开发平台，支持将 OpenAI、Claude、通义千问、智谱、DeepSeek、本地大模型等能力封装成可交互的 AI 应用。

在 Dify 中创建应用后，可以通过 API 的方式对外提供服务。也就是说，你可以不通过 Dify 的网页聊天界面，而是直接在自己的业务系统中调用它。

例如：

在公司官网中接入 AI 客服；
在微信公众号中接入智能问答；
在企业内部系统中接入知识库助手；
在后台服务中批量调用 AI 生成文案；
在自动化流程中调用 Dify 工作流完成复杂任务。

Dify API 本质上是一个 HTTP 接口，开发者只需要按照官方规范发送请求，即可获得 AI 返回结果。

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

在正式调用接口之前，需要完成以下几个步骤。

1. 创建 Dify 应用

应用类型	适用场景
Chatbot 聊天助手	多轮对话、客服机器人、知识库问答
Text Generator 文本生成	文案生成、摘要生成、标题生成
Agent 智能体	复杂任务规划、工具调用
Workflow 工作流	多步骤自动化任务

如果只是做一个简单的聊天机器人，可以选择 聊天助手 Chatbot。

如果需要根据输入生成一段固定格式内容，例如文章摘要、产品描述、SEO 标题，可以选择 文本生成应用。

如果需要多节点流程，例如「输入需求 → 检索知识库 → 调用大模型 → 格式化输出」，可以选择 Workflow 工作流。

2. 发布应用

创建并配置好应用后，需要点击发布。只有发布后的应用，才能稳定地通过 API 调用。

通常发布流程如下：

在 Dify 后台进入对应应用；
配置提示词、模型、变量、知识库等内容；
测试应用效果；
点击发布；
进入 API 访问页面查看接口说明。

3. 获取 API Key

在应用详情页中，一般可以找到 API Access 或 访问 API 入口。

进入后可以创建一个 API Key。API Key 是调用接口时的身份凭证，需要在请求头中携带。

示例格式：

Authorization: Bearer app-xxxxxxxxxxxxxxxx

注意：不同应用的 API Key 可能不同，不能混用。

三、Dify API 基础请求格式

Dify API 通常采用 RESTful 风格，通过 HTTP POST 请求发送 JSON 数据。

假设你的 Dify 服务地址为：

https://api.dify.ai

如果是自建 Dify 服务，地址可能类似：

https://dify.example.com

调用时通常需要设置以下请求头：

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

其中：

Content-Type 表示请求体是 JSON 格式；
Authorization 用于传入 API Key；
YOUR_API_KEY 替换为你在 Dify 后台创建的真实 Key。

四、调用聊天应用接口

聊天应用接口适合用于多轮对话场景，例如智能客服、知识库问答、AI 助手等。

1. 接口地址

一般聊天应用接口如下：

POST /v1/chat-messages

完整地址示例：

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

如果是私有化部署，则替换为你的服务域名：

https://dify.example.com/v1/chat-messages

2. 请求参数说明

常用参数如下：

参数名	类型	是否必填	说明
`inputs`	object	是	应用变量输入，如果没有变量可传空对象
`query`	string	是	用户输入的问题
`response_mode`	string	是	返回模式，支持 `blocking` 和 `streaming`
`conversation_id`	string	否	会话 ID，用于多轮对话
`user`	string	是	用户唯一标识

其中，response_mode 有两种模式：

blocking：阻塞模式，一次性返回完整结果；
streaming：流式模式，边生成边返回，适合网页聊天界面。

3. cURL 调用示例

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

4. 返回结果示例

{
  "event": "message",
  "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227",
  "id": "ad4cb33f-xxxx-xxxx-xxxx",
  "message_id": "ad4cb33f-xxxx-xxxx-xxxx",
  "conversation_id": "41dd8d7d-xxxx-xxxx-xxxx",
  "mode": "chat",
  "answer": "Dify API 可以帮助开发者将 Dify 中创建的 AI 应用集成到自己的系统中...",
  "metadata": {
    "usage": {
      "prompt_tokens": 100,
      "completion_tokens": 200,
      "total_tokens": 300
    }
  },
  "created_at": 1710000000
}

其中最重要的是：

"answer": "..."

这就是 AI 返回的回答内容。

另外需要注意：

"conversation_id": "..."

如果你希望下一轮对话能够继承上下文，就需要保存这个 conversation_id，并在下一次请求中继续传入。

五、Python 调用 Dify 聊天接口源码

下面是一个完整的 Python 调用示例。

1. 安装依赖

pip install requests

2. Python 源码

import requests
import json

DIFY_API_KEY = "YOUR_API_KEY"
DIFY_API_URL = "https://api.dify.ai/v1/chat-messages"


def chat_with_dify(query, user="user-001", conversation_id=""):
    headers = {
        "Authorization": f"Bearer {DIFY_API_KEY}",
        "Content-Type": "application/json"
    }

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

    response = requests.post(
        DIFY_API_URL,
        headers=headers,
        data=json.dumps(payload),
        timeout=60
    )

    if response.status_code != 200:
        raise Exception(f"请求失败，状态码：{response.status_code}，响应：{response.text}")

    result = response.json()

    return {
        "answer": result.get("answer"),
        "conversation_id": result.get("conversation_id")
    }


if __name__ == "__main__":
    conversation_id = ""

    while True:
        question = input("用户：")

        if question.lower() in ["exit", "quit", "q"]:
            print("程序已退出")
            break

        result = chat_with_dify(
            query=question,
            conversation_id=conversation_id
        )

        conversation_id = result["conversation_id"]

        print("AI：", result["answer"])

3. 代码说明

这段代码实现了一个命令行聊天程序。用户在终端输入问题，程序调用 Dify API 获取回答，并打印在终端中。

关键点如下：

DIFY_API_KEY：替换为自己的 Dify API Key；
DIFY_API_URL：如果是私有化部署，需要替换为自己的服务地址；
conversation_id：用于保存上下文，实现多轮对话；
response_mode 设置为 blocking，表示等待完整回答后一次性返回。

六、Node.js 调用 Dify API 源码

如果你的后端服务使用 Node.js，也可以通过 axios 调用 Dify API。

1. 安装依赖

npm install axios

2. Node.js 源码

const axios = require("axios");

const DIFY_API_KEY = "YOUR_API_KEY";
const DIFY_API_URL = "https://api.dify.ai/v1/chat-messages";

async function chatWithDify(query, conversationId = "", user = "user-001") {
  try {
    const response = await axios.post(
      DIFY_API_URL,
      {
        inputs: {},
        query,
        response_mode: "blocking",
        conversation_id: conversationId,
        user
      },
      {
        headers: {
          "Authorization": `Bearer ${DIFY_API_KEY}`,
          "Content-Type": "application/json"
        },
        timeout: 60000
      }
    );

    return {
      answer: response.data.answer,
      conversationId: response.data.conversation_id
    };
  } catch (error) {
    if (error.response) {
      console.error("请求失败：", error.response.status, error.response.data);
    } else {
      console.error("请求异常：", error.message);
    }

    throw error;
  }
}

async function main() {
  let conversationId = "";

  const result1 = await chatWithDify("请介绍一下Dify是什么", conversationId);
  conversationId = result1.conversationId;
  console.log("AI：", result1.answer);

  const result2 = await chatWithDify("它适合哪些场景？", conversationId);
  conversationId = result2.conversationId;
  console.log("AI：", result2.answer);
}

main();

七、前端 JavaScript 调用示例

在实际项目中，并不建议直接在浏览器前端暴露 Dify API Key。因为 API Key 一旦出现在前端代码中，就可能被用户通过浏览器开发者工具获取，存在严重安全风险。

不过，为了演示调用方式，下面提供一个简单的前端示例。正式项目中建议通过后端中转。

1. HTML 示例源码




  
  Dify API 调用示例
  


  
    Dify API 调用示例

2. 前端调用安全建议

正式项目中建议采用如下架构：

浏览器前端 → 自己的后端服务 → Dify API

也就是说，前端只请求你自己的后端接口，由后端服务保存 Dify API Key 并调用 Dify。这样可以避免 API Key 暴露。

八、后端中转接口示例

下面提供一个 Node.js Express 后端中转示例。

1. 安装依赖

npm install express axios cors dotenv

2. `.env` 配置文件

DIFY_API_KEY=YOUR_API_KEY
DIFY_API_URL=https://api.dify.ai/v1/chat-messages
PORT=3000

3. Express 服务端源码

require("dotenv").config();

const express = require("express");
const axios = require("axios");
const cors = require("cors");

const app = express();

app.use(cors());
app.use(express.json());

app.post("/api/chat", async (req, res) => {
  const { query, conversationId, user } = req.body;

  if (!query) {
    return res.status(400).json({
      message: "query不能为空"
    });
  }

  try {
    const response = await axios.post(
      process.env.DIFY_API_URL,
      {
        inputs: {},
        query,
        response_mode: "blocking",
        conversation_id: conversationId || "",
        user: user || "anonymous-user"
      },
      {
        headers: {
          "Authorization": `Bearer ${process.env.DIFY_API_KEY}`,
          "Content-Type": "application/json"
        },
        timeout: 60000
      }
    );

    res.json({
      answer: response.data.answer,
      conversationId: response.data.conversation_id,
      messageId: response.data.message_id
    });
  } catch (error) {
    console.error("Dify API调用失败：", error.response?.data || error.message);

    res.status(500).json({
      message: "Dify API调用失败",
      detail: error.response?.data || error.message
    });
  }
});

app.listen(process.env.PORT || 3000, () => {
  console.log(`Server running at http://localhost:${process.env.PORT || 3000}`);
});

4. 前端请求后端接口

async function sendMessageToBackend(question) {
  const response = await fetch("http://localhost:3000/api/chat", {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      query: question,
      conversationId: "",
      user: "web-user-001"
    })
  });

  const data = await response.json();

  console.log(data.answer);
}

通过这种方式，Dify API Key 只保存在后端 .env 文件中，安全性更高。

九、调用文本生成应用接口

如果你创建的是文本生成类应用，调用接口通常是：

POST /v1/completion-messages

该接口适合一次性生成文本，不强调多轮对话。

1. cURL 示例

curl -X POST 'https://api.dify.ai/v1/completion-messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {
      "topic": "人工智能在教育行业的应用"
    },
    "response_mode": "blocking",
    "user": "user-001"
  }'

这里的 inputs 需要与你在 Dify 应用中配置的变量一致。

例如你在提示词中定义了变量：

请围绕 {{topic}} 写一篇文章大纲

那么调用接口时就需要传入：

{
  "inputs": {
    "topic": "人工智能在教育行业的应用"
  }
}

2. Python 示例

import requests

API_KEY = "YOUR_API_KEY"
API_URL = "https://api.dify.ai/v1/completion-messages"

payload = {
    "inputs": {
        "topic": "Dify API接口调用教程"
    },
    "response_mode": "blocking",
    "user": "user-001"
}

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

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

if response.status_code == 200:
    data = response.json()
    print(data.get("answer"))
else:
    print("请求失败：", response.status_code, response.text)

十、调用 Dify Workflow 工作流接口

Dify 的 Workflow 非常适合处理复杂任务。相比普通聊天应用，工作流可以包含多个节点，例如：

开始节点；
参数提取节点；
知识库检索节点；
LLM 节点；
条件判断节点；
HTTP 请求节点；
代码执行节点；
结束节点。

如果你希望让 AI 应用具备更强的业务流程处理能力，可以使用 Workflow。

1. Workflow 接口地址

POST /v1/workflows/run

完整地址示例：

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

2. 请求示例

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

3. Python 调用 Workflow 示例

import requests

API_KEY = "YOUR_API_KEY"
API_URL = "https://api.dify.ai/v1/workflows/run"

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

payload = {
    "inputs": {
        "title": "Dify API接口调用教程",
        "language": "中文"
    },
    "response_mode": "blocking",
    "user": "user-001"
}

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

if response.status_code == 200:
    result = response.json()
    print(result)
else:
    print("请求失败：", response.status_code, response.text)

Workflow 的返回结果通常包含执行状态、输出变量、任务 ID 等信息。你可以根据工作流结束节点设置的输出字段读取最终结果。

十一、流式响应调用方式

在聊天产品中，用户往往希望看到 AI 一边生成一边输出，而不是等待完整回答后才显示。这时可以使用 streaming 模式。

1. 请求参数

将：

"response_mode": "blocking"

改为：

"response_mode": "streaming"

即可启用流式响应。

2. Python 流式调用示例

import requests
import json

API_KEY = "YOUR_API_KEY"
API_URL = "https://api.dify.ai/v1/chat-messages"

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

payload = {
    "inputs": {},
    "query": "请用通俗语言解释什么是Dify API",
    "response_mode": "streaming",
    "conversation_id": "",
    "user": "user-001"
}

response = requests.post(
    API_URL,
    headers=headers,
    json=payload,
    stream=True,
    timeout=120
)

for line in response.iter_lines():
    if line:
        decoded_line = line.decode("utf-8")

        if decoded_line.startswith("data: "):
            data = decoded_line.replace("data: ", "")

            if data == "[DONE]":
                break

            try:
                event = json.loads(data)
                answer = event.get("answer")

                if answer:
                    print(answer, end="", flush=True)
            except json.JSONDecodeError:
                pass

流式接口一般会以 Server-Sent Events，也就是 SSE 的方式返回数据。每一段内容通常以 data: 开头，开发者需要逐行读取并解析。

十二、常见错误及解决方法

1. 401 Unauthorized

错误原因通常是 API Key 不正确或没有传入。

检查以下内容：

Authorization 是否写成了 Bearer YOUR_API_KEY；
API Key 是否复制完整；
当前 API Key 是否属于对应应用；
是否误用了其他应用的 Key。

2. 404 Not Found

可能原因包括：

API 地址写错；
自建 Dify 服务域名错误；
接口路径错误；
应用类型和接口不匹配。

例如聊天应用应调用：

/v1/chat-messages

文本生成应用应调用：

/v1/completion-messages

Workflow 应调用：

/v1/workflows/run

3. 400 Bad Request

通常是请求参数不完整或格式错误。

重点检查：

query 是否为空；
inputs 是否是对象；
response_mode 是否填写正确；
文本生成应用中的变量是否与 Dify 配置一致；
user 是否传入。

4. 请求超时

如果模型响应较慢，可能出现超时。解决方式包括：

增大后端请求超时时间；
使用流式响应；
优化提示词；
减少知识库检索数量；
选择响应速度更快的模型。

十三、Dify API 接入最佳实践

1. 不要在前端暴露 API Key

API Key 应该放在后端服务或环境变量中，不要直接写在浏览器代码里。

2. 保存 conversation_id

如果你做的是聊天应用，一定要保存 conversation_id。

例如：

用户第一次提问时，传空字符串；
Dify 返回 conversation_id；
后续同一用户继续提问时，带上该 conversation_id；
这样 AI 才能记住上下文。

3. 为每个用户设置唯一 user 标识

user 字段建议传入业务系统中的用户 ID，例如：

"user": "uid-10086"

这样便于后续追踪、统计和排查问题。

4. 处理异常和日志

生产环境中一定要记录接口调用日志，包括：

请求时间；
用户 ID；
conversation_id；
message_id；
接口耗时；
错误状态码；
错误响应内容。

但需要注意，不要在日志中记录敏感信息，例如 API Key、用户隐私数据等。

5. 使用环境变量管理配置

不要把 API Key 写死在代码中。推荐使用 .env 文件或云服务环境变量。

例如：

DIFY_API_KEY=app-xxxxxxxxxxxxxxxx
DIFY_API_BASE_URL=https://api.dify.ai

在代码中读取：

process.env.DIFY_API_KEY

这样更安全，也方便不同环境切换。

十四、完整项目结构示例

如果你要做一个简单的 Web 聊天应用，可以参考下面的项目结构：

dify-chat-demo/
├── server/
│   ├── app.js
│   ├── package.json
│   └── .env
└── web/
    ├── index.html
    ├── main.js
    └── style.css

其中：

server/app.js：后端中转服务，负责调用 Dify API；
server/.env：保存 API Key；
web/index.html：前端页面；
web/main.js：调用后端接口；
web/style.css：页面样式。

这种结构简单清晰，适合快速做 Demo，也可以扩展到正式项目中。

十五、总结

本文详细介绍了 Dify API 的调用方法，包括：

如何创建应用并获取 API Key；
如何调用聊天应用接口；
如何调用文本生成应用接口；
如何调用 Workflow 工作流接口；
如何使用 Python、Node.js、前端 JavaScript 调用 Dify；
如何处理流式响应；
常见错误及解决方案；
生产环境接入最佳实践。

总体来说，Dify API 的接入门槛并不高。只要掌握三个核心点即可：

找到正确的接口地址；
在请求头中携带正确的 API Key；
按照应用类型传入正确参数。

如果只是简单对话，优先使用 /v1/chat-messages；如果是一次性文本生成，使用 /v1/completion-messages；如果是复杂业务流程，使用 /v1/workflows/run。

通过 Dify 的可视化编排能力和 API 调用能力，开发者可以非常高效地把大模型能力集成到真实业务系统中，快速构建属于自己的 AI 应用。

文章标签： DifyAPI 接口调用源码示例工作流

上一篇：Dify 接口怎么接入项目？从 API Key 到 Python/Node 源码实战指南

下一篇：Dify API 接入实战：从接口调用到配置文件一次讲清

更多栏目

新闻动态

文档中心

下载中心

目录结构

全文

产品与服务

新闻帮助

生态合作

了解我们

Dify API 接入实战：从获取 Key 到聊天、工作流调用全流程源码示例

Dify API接口调用教程｜附源码

一、什么是 Dify API？

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

1. 创建 Dify 应用

2. 发布应用

3. 获取 API Key

三、Dify API 基础请求格式

四、调用聊天应用接口

1. 接口地址

2. 请求参数说明

3. cURL 调用示例

4. 返回结果示例

五、Python 调用 Dify 聊天接口源码

1. 安装依赖

2. Python 源码

3. 代码说明

六、Node.js 调用 Dify API 源码

1. 安装依赖

2. Node.js 源码

七、前端 JavaScript 调用示例

1. HTML 示例源码

Dify API 调用示例

2. 前端调用安全建议

八、后端中转接口示例

1. 安装依赖

2. .env 配置文件

3. Express 服务端源码

4. 前端请求后端接口

九、调用文本生成应用接口

1. cURL 示例

2. Python 示例

十、调用 Dify Workflow 工作流接口

1. Workflow 接口地址

2. 请求示例

3. Python 调用 Workflow 示例

十一、流式响应调用方式

1. 请求参数

2. Python 流式调用示例

十二、常见错误及解决方法

1. 401 Unauthorized

2. 404 Not Found

3. 400 Bad Request

4. 请求超时

十三、Dify API 接入最佳实践

1. 不要在前端暴露 API Key

2. 保存 conversation_id

3. 为每个用户设置唯一 user 标识

4. 处理异常和日志

5. 使用环境变量管理配置

十四、完整项目结构示例

十五、总结

2. `.env` 配置文件