Dify API接口调用教程｜零基础可学

随着大模型应用的快速发展，越来越多的人开始使用 Dify 搭建 AI 应用，例如智能客服、知识库问答、AI 写作助手、工作流自动化助手等。Dify 的优势在于：即使你不会从零开发大模型应用，也可以通过可视化界面快速创建一个 AI 应用，并且通过 API 接口 将它接入网站、小程序、企业系统、自动化脚本或第三方平台。

本文将以零基础视角，详细讲解 Dify API 接口如何调用，包括 Dify 是什么、如何创建应用、如何获取 API Key、如何查看接口文档、如何使用 curl、Python、JavaScript 调用 Dify API，以及常见问题和实战建议。即使你没有太多后端开发经验，也可以跟着本文一步步完成调用。

一、Dify 是什么？

Dify 是一个开源的大模型应用开发平台，主要用于快速构建、部署和管理 AI 应用。它支持多种大语言模型，例如 OpenAI、Claude、通义千问、智谱、DeepSeek、本地模型等，也支持知识库、工作流、工具调用、对话管理、Prompt 编排等能力。

简单来说，Dify 可以帮助你完成以下事情：

• 创建一个 AI 聊天机器人；
• 搭建企业知识库问答系统；
• 设计多步骤 AI 工作流；
• 封装 AI 应用并通过 API 调用；
• 将 AI 能力接入网页、App、企业微信、飞书、钉钉等系统；
• 管理用户会话、上下文、变量和模型参数。

对于零基础用户来说，Dify 最大的好处是：你不需要直接编写复杂的 Prompt 管理逻辑，也不需要自己处理大模型上下文、知识库检索、工作流编排等复杂问题。你只需要在 Dify 后台配置好应用，然后通过 API 把它调用起来即可。

二、为什么要调用 Dify API？

在 Dify 平台中，你可以直接通过网页测试 AI 应用。但如果你想把这个 AI 应用真正用到业务系统里，就需要使用 API。

例如：

• 你想在自己的网站上加一个 AI 客服；
• 你想让微信小程序调用 Dify 的智能问答能力；
• 你想在公司内部系统中接入知识库问答；
• 你想写一个 Python 脚本自动调用 AI 生成内容；
• 你想让工作流根据用户输入自动分析数据；
• 你想将 Dify 应用接入企业微信、飞书机器人或钉钉机器人。

这些场景本质上都需要通过接口发送请求，把用户输入传给 Dify，然后接收 Dify 返回的 AI 回复。

三、调用 Dify API 前需要准备什么？

在正式调用接口之前，你需要准备以下内容。

1. 一个可用的 Dify 环境

你可以选择以下两种方式：

方式一：使用 Dify 云服务

直接访问 Dify 官方网站，注册账号后即可使用。适合新手、测试和快速上线。

方式二：自己部署 Dify

如果你对数据安全、私有化部署有要求，可以使用 Docker 自行部署 Dify。自部署方式适合企业内部系统、私有知识库、敏感业务场景。

对于零基础用户，建议先从 Dify 云服务开始学习，等熟悉后再考虑私有化部署。

2. 创建一个 Dify 应用

登录 Dify 后，你需要先创建一个应用。Dify 常见应用类型包括：

• 聊天助手：适合多轮对话，例如客服、问答机器人；
• 文本生成应用：适合单次文本生成，例如文章生成、标题生成；
• Agent 应用：适合具备工具调用能力的智能体；
• 工作流应用：适合复杂流程编排，例如表单分析、数据处理、多步骤任务。

如果你是初学者，建议先创建一个 聊天助手，因为聊天类接口最容易理解，也最常见。

创建应用的大致步骤如下：

1. 登录 Dify 控制台；
2. 点击“创建应用”；
3. 选择“聊天助手”；
4. 填写应用名称，例如“智能客服测试”；
5. 配置模型，例如 GPT、DeepSeek、通义千问等；
6. 编写系统提示词；
7. 点击发布或保存。

系统提示词可以简单写成：

你是一个专业、友好、耐心的智能客服助手，请用简洁清晰的中文回答用户问题。

3. 获取 API Key

Dify 的 API 调用需要身份认证，通常使用 API Key。

获取方式一般如下：

1. 进入你创建好的应用；
2. 找到“访问 API”或“API Access”；
3. 点击创建或复制 API Key；
4. 保存好这个 Key。

API Key 通常类似下面这样：

app-xxxxxxxxxxxxxxxxxxxxxxxx

请注意，API Key 非常重要，相当于你的接口调用凭证。不要把它暴露在前端网页代码中，也不要上传到公开代码仓库，例如 GitHub。

四、Dify API 的基本调用逻辑

调用 Dify API 的过程可以理解为：

1. 用户输入一句话；
2. 你的程序把这句话发送给 Dify API；
3. Dify 将输入交给你配置好的应用处理；
4. 大模型生成回复；
5. Dify 把结果返回给你的程序；
6. 你的程序展示给用户。

一个典型的接口请求包含以下部分：

• 请求地址 URL；
• 请求方法，一般是 POST；
• 请求头 Headers；
• 请求体 Body；
• 返回结果 Response。

例如，调用聊天接口时，一般需要传入：

• inputs：应用中定义的输入变量；
• query：用户的问题；
• response_mode：返回模式；
• conversation_id：会话 ID，可用于多轮对话；
• user：用户标识。

五、Dify API 请求地址说明

如果你使用的是 Dify 云服务，请求地址通常类似：

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

如果你是私有化部署，地址通常类似：

http://你的服务器地址/v1/chat-messages

例如：

http://localhost/v1/chat-messages

或者：

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

不同应用类型对应的接口可能不同：

本文主要以聊天助手接口 /v1/chat-messages 为例讲解。

六、使用 curl 调用 Dify API

如果你是零基础，建议先用 curl 测试接口。curl 是一种命令行请求工具，适合快速验证 API 是否可用。

1. 阻塞模式调用

阻塞模式是指：请求发出后，等待 Dify 完整生成结果，再一次性返回。

示例代码如下：

curl -X POST 'https://api.dify.ai/v1/chat-messages' \
--header 'Authorization: Bearer app-你的API密钥' \
--header 'Content-Type: application/json' \
--data-raw '{
  "inputs": {},
  "query": "你好，请介绍一下 Dify 是什么？",
  "response_mode": "blocking",
  "conversation_id": "",
  "user": "user-001"
}'

参数解释：

• Authorization：认证信息，格式为 Bearer + 空格 + API Key；
• Content-Type：请求数据格式，这里是 JSON；
• inputs：输入变量，如果没有变量可以传空对象；
• query：用户输入的问题；
• response_mode：响应模式，blocking 表示阻塞返回；
• conversation_id：会话 ID，首次请求可以为空；
• user：用户唯一标识，可自定义。

如果调用成功，你会收到类似返回：

{
  "event": "message",
  "task_id": "xxx",
  "id": "xxx",
  "message_id": "xxx",
  "conversation_id": "xxx",
  "mode": "chat",
  "answer": "Dify 是一个开源的大模型应用开发平台……",
  "metadata": {},
  "created_at": 1710000000
}

其中最重要的是：

"answer": "Dify 是一个开源的大模型应用开发平台……"

这就是 AI 返回的答案。

2. 流式模式调用

流式模式是指：AI 一边生成，一边返回内容。类似 ChatGPT 打字机效果，适合聊天窗口。

示例：

curl -X POST 'https://api.dify.ai/v1/chat-messages' \
--header 'Authorization: Bearer app-你的API密钥' \
--header 'Content-Type: application/json' \
--data-raw '{
  "inputs": {},
  "query": "请用三句话解释人工智能。",
  "response_mode": "streaming",
  "conversation_id": "",
  "user": "user-001"
}'

流式返回通常是 Server-Sent Events，返回内容会分多段出现。对于前端聊天界面，流式模式体验更好；对于后台脚本或简单集成，阻塞模式更容易处理。

七、使用 Python 调用 Dify API

如果你想在 Python 程序中调用 Dify，可以使用 requests 库。

1. 安装 requests

pip install requests

2. Python 阻塞模式示例

import requests

API_KEY = "app-你的API密钥"
API_URL = "https://api.dify.ai/v1/chat-messages"

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

data = {
    "inputs": {},
    "query": "请介绍一下 Dify API 的作用。",
    "response_mode": "blocking",
    "conversation_id": "",
    "user": "python-user-001"
}

response = requests.post(API_URL, headers=headers, json=data)

if response.status_code == 200:
    result = response.json()
    print("AI 回复：")
    print(result.get("answer"))
    print("会话 ID：", result.get("conversation_id"))
else:
    print("请求失败：", response.status_code)
    print(response.text)

运行后，如果配置正确，你就可以在终端看到 AI 回复。

3. 多轮对话如何实现？

Dify 的聊天助手支持多轮对话。关键在于保存第一次返回的 conversation_id，后续请求继续传入该 ID。

示例：

import requests

API_KEY = "app-你的API密钥"
API_URL = "https://api.dify.ai/v1/chat-messages"

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

conversation_id = ""

while True:
    user_input = input("你：")

    if user_input.lower() in ["exit", "quit"]:
        break

    data = {
        "inputs": {},
        "query": user_input,
        "response_mode": "blocking",
        "conversation_id": conversation_id,
        "user": "python-user-001"
    }

    response = requests.post(API_URL, headers=headers, json=data)

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

这段代码实现了一个简单的命令行聊天机器人。用户可以连续提问，Dify 会根据会话上下文进行回答。

八、使用 JavaScript 调用 Dify API

在实际项目中，很多人希望在网页或 Node.js 服务中调用 Dify API。

需要特别注意：不建议直接在浏览器前端暴露 Dify API Key。正确做法是由你的后端服务调用 Dify，然后前端调用你自己的后端接口。

下面先给出 Node.js 示例。

1. Node.js 调用示例

如果你使用 Node.js 18 及以上版本，可以直接使用内置 fetch。

const API_KEY = "app-你的API密钥";
const API_URL = "https://api.dify.ai/v1/chat-messages";

async function callDify() {
  const response = await fetch(API_URL, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      inputs: {},
      query: "请用简单语言解释什么是 Dify。",
      response_mode: "blocking",
      conversation_id: "",
      user: "node-user-001"
    })
  });

  if (!response.ok) {
    const errorText = await response.text();
    console.error("请求失败：", response.status, errorText);
    return;
  }

  const result = await response.json();
  console.log("AI 回复：", result.answer);
}

callDify();

2. Express 封装后端接口

如果你要给网页使用，建议封装一个后端接口。

安装 Express：

npm install express

示例代码：

const express = require("express");

const app = express();
app.use(express.json());

const API_KEY = process.env.DIFY_API_KEY;
const API_URL = "https://api.dify.ai/v1/chat-messages";

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

    const response = await fetch(API_URL, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${API_KEY}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        inputs: {},
        query,
        response_mode: "blocking",
        conversation_id: conversation_id || "",
        user: "web-user-001"
      })
    });

    const result = await response.json();
    res.json(result);
  } catch (error) {
    res.status(500).json({
      message: "服务器错误",
      error: error.message
    });
  }
});

app.listen(3000, () => {
  console.log("服务已启动：http://localhost:3000");
});

这样，前端只需要请求你自己的 /api/chat，而不需要直接接触 Dify API Key。

九、工作流 API 调用简介

除了聊天助手，Dify 的工作流应用也非常常用。工作流可以把多个步骤串起来，例如：

1. 接收用户输入；
2. 判断用户意图；
3. 查询知识库；
4. 调用大模型生成结果；
5. 输出结构化内容。

工作流接口通常是：

/v1/workflows/run

curl 示例：

curl -X POST 'https://api.dify.ai/v1/workflows/run' \
--header 'Authorization: Bearer app-你的API密钥' \
--header 'Content-Type: application/json' \
--data-raw '{
  "inputs": {
    "topic": "Dify API 教程",
    "style": "通俗易懂"
  },
  "response_mode": "blocking",
  "user": "workflow-user-001"
}'

这里的 inputs 不是空对象，而是你在工作流中定义的变量。例如你定义了 topic 和 style，调用接口时就要传入对应字段。

十、常见参数详细解释

1. inputs

inputs 用于传递应用变量。

如果你的 Dify 应用中没有定义变量，可以写：

"inputs": {}

如果你的应用定义了变量，例如：

• name
• company
• product

那么请求时可以这样写：

"inputs": {
  "name": "张三",
  "company": "某某科技有限公司",
  "product": "智能客服系统"
}

2. query

query 是用户输入内容，主要用于聊天类应用。

例如：

"query": "你能帮我写一份产品介绍吗？"

对于工作流应用，有时不一定使用 query，而是主要依赖 inputs。

3. response_mode

常见取值有两个：

新手建议先使用 blocking，等接口跑通后再学习 streaming。

4. conversation_id

conversation_id 用于标识一段对话。

首次请求可以传空字符串：

"conversation_id": ""

Dify 返回结果中会包含新的 conversation_id。后续请求传入这个 ID，就可以继续同一轮上下文。

5. user

user 是用户标识，用于区分不同调用者。可以是用户 ID、手机号哈希、系统内部账号 ID 等。

例如：

"user": "user-10001"

建议不同真实用户使用不同的 user 值，这样方便后续统计、追踪和管理。

十一、如何处理文件上传？

某些 Dify 应用支持上传文件，例如文档分析、图片理解、合同解析等。通常需要先调用文件上传接口，再把文件 ID 传给应用。

文件上传接口一般是：

/v1/files/upload

curl 示例：

curl -X POST 'https://api.dify.ai/v1/files/upload' \
--header 'Authorization: Bearer app-你的API密钥' \
--form 'file=@/path/to/test.pdf' \
--form 'user=user-001'

上传成功后，会返回文件相关信息，例如文件 ID。之后你可以在应用调用时引用该文件。

由于不同 Dify 版本和应用配置对文件参数支持略有差异，实际开发中应以 Dify 应用页面中的 API 文档为准。

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

1. 401 Unauthorized

原因通常是 API Key 错误或请求头格式不正确。

请检查：

Authorization: Bearer app-你的API密钥

注意 Bearer 后面有一个空格。

2. 404 Not Found

可能原因：

• API 地址写错；
• 使用了错误的 Dify 域名；
• 私有化部署路径不正确；
• 应用接口类型不匹配。

例如聊天助手应调用：

/v1/chat-messages

工作流应调用：

/v1/workflows/run

3. 400 Bad Request

通常是请求参数有问题，例如：

• JSON 格式错误；
• 缺少必填字段；
• inputs 变量和应用配置不一致；
• response_mode 写错；
• 文件参数格式不正确。

建议先复制 Dify 页面中提供的官方示例，再逐步修改。

4. 没有返回 answer

可能原因：

• 调用的是工作流接口，返回结构和聊天接口不同；
• 使用了流式模式，不能直接按 JSON 一次性解析；
• 应用执行失败；
• 模型服务异常。

如果使用 streaming，需要按 SSE 流式数据解析，而不是直接 response.json()。

5. 响应很慢

可能原因：

• 模型本身生成速度慢；
• Prompt 太长；
• 知识库检索内容过多；
• 工作流步骤太多；
• 网络延迟较高。

优化方式：

• 简化系统提示词；
• 减少无关知识库内容；
• 控制输出长度；
• 使用更快的模型；
• 对常见问题做缓存。

十三、安全调用建议

调用 Dify API 时，一定要注意安全。

1. 不要把 API Key 写在前端

错误示例：

const API_KEY = "app-xxxx";

如果这段代码出现在浏览器中，任何人都可以通过开发者工具看到你的 Key。

正确做法：

• 前端请求你的后端；
• 后端保存 API Key；
• 后端调用 Dify；
• 后端把结果返回给前端。

2. 使用环境变量保存密钥

例如在 Node.js 中：

DIFY_API_KEY=app-你的API密钥

代码中读取：

const API_KEY = process.env.DIFY_API_KEY;

这样可以避免密钥被写死在代码里。

3. 做好用户权限控制

如果你的 Dify 应用接入企业系统，建议在你自己的业务系统中控制用户权限，不要让所有人随意调用接口。

例如：

• 登录后才能调用；
• 限制调用频率；
• 限制单用户每日调用次数；
• 记录调用日志；
• 对敏感问题做过滤。

十四、Dify API 实战场景示例

场景一：网站 AI 客服

你可以在 Dify 中创建一个聊天助手，并上传企业产品文档作为知识库。然后网站前端提供聊天窗口，用户输入问题后，后端调用 Dify API 获取回答。

适合：

• 产品咨询；
• 售后问题；
• 价格说明；
• 使用教程；
• 常见故障排查。

场景二：企业知识库问答

企业内部往往有大量制度文档、操作手册和项目资料。你可以通过 Dify 构建知识库问答应用，然后接入企业微信或飞书。

员工可以直接提问：

如何申请报销？

AI 根据企业制度文档回答，大幅减少人工咨询成本。

场景三：自动生成营销文案

你可以创建一个文本生成应用，让用户输入产品名称、卖点、目标人群，然后通过 API 自动生成小红书文案、朋友圈文案、短视频脚本等。

场景四：表单智能分析

使用 Dify 工作流可以处理更复杂任务。例如用户提交一段客户反馈，工作流自动判断情绪、提取关键词、生成处理建议，并返回结构化结果。

十五、零基础学习路线建议

如果你刚开始学习 Dify API，可以按照下面路线：

1. 先在 Dify 页面创建一个聊天助手；
2. 在页面内测试应用是否能正常回答；
3. 获取 API Key；
4. 用 curl 调用 /v1/chat-messages；
5. 用 Python 写一个命令行聊天程序；
6. 学会保存 conversation_id 实现多轮对话；
7. 再学习 Node.js 后端封装；
8. 最后学习流式输出、文件上传和工作流接口。

不要一开始就追求复杂系统。API 学习最重要的是先跑通最小闭环：输入一句话，拿到 AI 回复。只要这个流程成功，后面的功能都是逐步扩展。

十六、总结

Dify API 的核心价值在于：它可以把你在 Dify 平台中搭建好的 AI 应用，方便地接入真实业务系统。对于零基础用户来说，只需要理解几个关键点：

• Dify 应用需要先创建并发布；
• 调用 API 前要获取 API Key；
• 请求头中必须携带 Authorization: Bearer API_KEY；
• 聊天助手常用接口是 /v1/chat-messages；
• 工作流常用接口是 /v1/workflows/run；
• blocking 适合新手和后台任务；
• streaming 适合聊天界面实时输出；
• 多轮对话要保存并传递 conversation_id；
• API Key 不要暴露在前端。

如果你是第一次学习，建议从 curl 和 Python 示例开始，把接口调用跑通，再逐步接入网站、小程序或企业系统。掌握 Dify API 后，你就可以把大模型能力真正应用到实际业务中，例如智能客服、知识库问答、自动写作、数据分析和流程自动化。

Dify 的可视化配置能力加上 API 调用能力，能够让非专业 AI 工程师也快速构建可用的大模型应用。只要你理解了本文介绍的调用流程和参数含义，就已经具备了把 Dify 应用接入真实项目的基础能力。