Dify API接口调用教程｜2026最新版

随着 AI 应用从“尝鲜阶段”进入“工程化落地阶段”，越来越多团队开始使用 Dify 来搭建智能客服、知识库问答、AI Agent、内容生成工具、企业内部助手等应用。Dify 的优势不仅在于可视化编排能力强，更重要的是它提供了完善的 API 接口调用能力，可以让开发者把在 Dify 中创建好的 AI 应用集成到网站、App、小程序、企业系统、自动化流程或第三方平台中。

本文将以 2026 年常见的使用方式为基础，系统讲解 Dify API 接口调用方法、鉴权方式、常见接口类型、请求参数、流式响应、非流式响应、文件上传、会话管理、错误排查以及最佳实践，帮助你快速完成从 Dify 应用创建到 API 调用上线的全过程。

一、Dify API 是什么？

Dify API 是 Dify 为开发者提供的一组接口服务。通过 API，你可以在外部系统中调用 Dify 创建的 AI 应用，例如：

• 调用聊天机器人应用，实现智能对话；
• 调用文本生成应用，实现文章、标题、摘要生成；
• 调用工作流应用，实现复杂业务自动化；
• 调用知识库问答应用，实现企业文档问答；
• 调用 Agent 应用，实现带工具调用能力的智能任务处理；
• 上传文件，让 AI 基于文件内容进行分析；
• 管理会话、消息、反馈、用户输入等数据。

简单来说，Dify API 的作用就是：
把你在 Dify 后台搭建好的 AI 能力，以接口形式提供给其他系统调用。

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

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

1. 部署或注册 Dify

你可以选择两种方式使用 Dify：

方式一：使用 Dify 云服务

适合不想维护服务器、希望快速上线的用户。注册后即可创建应用并获取 API Key。

方式二：私有化部署 Dify

适合企业内部使用，尤其是对数据安全、模型接入、权限控制有较高要求的场景。私有化部署后，你的 API 地址通常是自己的域名，例如：

https://dify.example.com

API 基础地址一般类似：

https://dify.example.com/v1

如果使用官方云服务，则接口地址以官方平台提供的地址为准。

2. 创建一个 Dify 应用

登录 Dify 控制台后，通常可以创建以下几类应用：

创建应用后，你可以在 Dify 后台完成提示词配置、模型选择、知识库绑定、变量设置、工作流编排等操作。

3. 获取 API Key

进入具体应用的 API 访问页面，一般可以看到：

• API Endpoint；
• API Key；
• 请求示例；
• 接口文档；
• 调用方式说明。

API Key 是调用 Dify 接口的重要凭证，通常在请求头中通过 Authorization 传递：

Authorization: Bearer YOUR_API_KEY

注意：
API Key 一定不要暴露在前端页面中。
如果你要在网页、小程序、App 中调用 Dify API，建议通过自己的后端服务中转请求，避免密钥泄露。

三、Dify API 调用的基本格式

Dify API 通常采用 RESTful 风格，请求和响应主要使用 JSON 格式。

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

POST /v1/chat-messages
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

请求体示例：

{
  "inputs": {},
  "query": "你好，请介绍一下你自己",
  "response_mode": "blocking",
  "conversation_id": "",
  "user": "user-001"
}

其中：

四、Dify 常见 API 接口类型

不同类型的 Dify 应用对应的接口略有差异。以下是常见接口。

五、聊天应用 API：/chat-messages

如果你创建的是聊天助手类应用，通常会使用聊天消息接口。

1. 接口地址

POST /v1/chat-messages

完整地址示例：

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

2. 请求头

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

3. 非流式请求示例

curl -X POST 'https://dify.example.com/v1/chat-messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {},
    "query": "请用通俗语言解释什么是大模型",
    "response_mode": "blocking",
    "conversation_id": "",
    "user": "user-001"
  }'

4. 非流式响应示例

{
  "event": "message",
  "message_id": "msg_xxx",
  "conversation_id": "conv_xxx",
  "mode": "chat",
  "answer": "大模型可以理解为一种经过大量数据训练的人工智能模型……",
  "metadata": {
    "usage": {
      "prompt_tokens": 120,
      "completion_tokens": 300,
      "total_tokens": 420
    }
  },
  "created_at": 1760000000
}

这里最关键的字段是：

5. 多轮对话怎么做？

第一次请求时，conversation_id 可以为空：

{
  "conversation_id": ""
}

Dify 返回结果中会包含一个新的 conversation_id。

后续用户继续提问时，需要把这个 conversation_id 带上：

{
  "inputs": {},
  "query": "那它和传统机器学习有什么区别？",
  "response_mode": "blocking",
  "conversation_id": "conv_xxx",
  "user": "user-001"
}

这样 Dify 就能基于同一个会话上下文进行连续对话。

六、文本生成应用 API：/completion-messages

如果你的应用是文本生成类型，例如生成标题、写邮件、写文章摘要等，一般使用：

POST /v1/completion-messages

请求示例

curl -X POST 'https://dify.example.com/v1/completion-messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {
      "topic": "企业如何落地AI知识库",
      "style": "专业、易懂"
    },
    "response_mode": "blocking",
    "user": "user-001"
  }'

在文本生成应用中，inputs 非常重要。
如果你在 Dify 应用中定义了变量，例如：

• topic
• style
• language
• length

那么调用 API 时就需要在 inputs 中传入对应字段。

响应示例

{
  "event": "message",
  "message_id": "msg_xxx",
  "mode": "completion",
  "answer": "企业落地 AI 知识库，关键不在于简单上传文档……",
  "metadata": {
    "usage": {
      "total_tokens": 800
    }
  },
  "created_at": 1760000000
}

七、工作流 API：/workflows/run

Dify 工作流非常适合处理复杂任务，例如：

• 先识别用户意图；
• 再查询知识库；
• 再调用大模型生成结果；
• 再进行格式化输出；
• 最后返回给业务系统。

工作流通常通过以下接口执行：

POST /v1/workflows/run

请求示例

curl -X POST 'https://dify.example.com/v1/workflows/run' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {
      "customer_question": "我的订单为什么还没发货？",
      "order_id": "OD20260101001"
    },
    "response_mode": "blocking",
    "user": "user-001"
  }'

响应示例

{
  "workflow_run_id": "run_xxx",
  "task_id": "task_xxx",
  "data": {
    "id": "run_xxx",
    "workflow_id": "workflow_xxx",
    "status": "succeeded",
    "outputs": {
      "result": "您的订单目前处于仓库拣货阶段，预计今天下午发出。"
    },
    "elapsed_time": 3.21,
    "total_tokens": 980,
    "created_at": 1760000000,
    "finished_at": 1760000003
  }
}

对于工作流应用，重点关注：

{
  "data": {
    "outputs": {}
  }
}

最终业务结果通常在 outputs 中。

八、流式响应与非流式响应

Dify API 常见的响应模式有两种：

"response_mode": "blocking"

和：

"response_mode": "streaming"

1. 非流式响应：blocking

非流式响应会等待 AI 完整生成后，一次性返回结果。

优点：

• 实现简单；
• 适合后端任务；
• 适合短文本生成；
• 适合不需要打字机效果的场景。

缺点：

• 用户需要等待完整结果返回；
• 长文本生成体验较差；
• 请求时间较长时可能受网关超时影响。

2. 流式响应：streaming

流式响应会边生成边返回，常用于聊天机器人页面的“打字机效果”。

请求示例：

curl -X POST 'https://dify.example.com/v1/chat-messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {},
    "query": "请写一篇关于AI客服的介绍",
    "response_mode": "streaming",
    "conversation_id": "",
    "user": "user-001"
  }'

流式响应通常以 Server-Sent Events，也就是 SSE 的形式返回。返回内容可能类似：

data: {"event":"message","answer":"AI"}
data: {"event":"message","answer":"客服"}
data: {"event":"message","answer":"可以"}
data: {"event":"message_end","metadata":{"usage":{"total_tokens":500}}}

前端或后端需要持续读取数据流，并把每次返回的 answer 拼接起来。

九、JavaScript 调用 Dify API 示例

以下示例适用于 Node.js 后端环境，不建议直接放在浏览器前端，因为会暴露 API Key。

const fetch = require("node-fetch");

async function callDify() {
  const response = await fetch("https://dify.example.com/v1/chat-messages", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      inputs: {},
      query: "请介绍一下Dify API的作用",
      response_mode: "blocking",
      conversation_id: "",
      user: "user-001"
    })
  });

  const data = await response.json();
  console.log(data.answer);
}

callDify();

如果你使用的是 Node.js 18 及以上版本，通常已经内置 fetch，可以不安装 node-fetch。

十、Python 调用 Dify API 示例

Python 后端调用 Dify API 也非常简单。

import requests

url = "https://dify.example.com/v1/chat-messages"

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

payload = {
    "inputs": {},
    "query": "请说明Dify如何接入企业知识库",
    "response_mode": "blocking",
    "conversation_id": "",
    "user": "user-001"
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

print(data.get("answer"))

十一、Python 流式调用示例

如果要实现流式输出，可以这样写：

import requests
import json

url = "https://dify.example.com/v1/chat-messages"

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

payload = {
    "inputs": {},
    "query": "请生成一段关于智能客服的介绍",
    "response_mode": "streaming",
    "conversation_id": "",
    "user": "user-001"
}

with requests.post(url, headers=headers, json=payload, stream=True) as response:
    for line in response.iter_lines():
        if line:
            decoded_line = line.decode("utf-8")
            if decoded_line.startswith("data: "):
                json_str = decoded_line.replace("data: ", "")
                try:
                    data = json.loads(json_str)
                    if data.get("event") == "message":
                        print(data.get("answer", ""), end="", flush=True)
                    elif data.get("event") == "message_end":
                        print("\n生成结束")
                except json.JSONDecodeError:
                    pass

十二、文件上传接口

在一些场景中，你可能希望用户上传图片、文档或其他文件，然后让 Dify 应用基于文件内容进行处理。

常见文件上传接口类似：

POST /v1/files/upload

curl 示例

curl -X POST 'https://dify.example.com/v1/files/upload' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@/path/to/document.pdf' \
  -F 'user=user-001'

响应中通常会返回文件 ID：

{
  "id": "file_xxx",
  "name": "document.pdf",
  "size": 102400,
  "extension": "pdf",
  "mime_type": "application/pdf",
  "created_by": "user-001",
  "created_at": 1760000000
}

随后你可以在调用聊天或工作流接口时，把文件信息传入请求体。

示例：

{
  "inputs": {},
  "query": "请总结这个文件的核心内容",
  "response_mode": "blocking",
  "conversation_id": "",
  "user": "user-001",
  "files": [
    {
      "type": "document",
      "transfer_method": "local_file",
      "upload_file_id": "file_xxx"
    }
  ]
}

十三、会话管理与用户标识

在 Dify API 调用中，user 字段非常重要。它通常用于标识终端用户，例如：

"user": "user-001"

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

"user": "customer_10086"

或者：

"user": "wechat_openid_xxx"

这样做有几个好处：

1. 方便区分不同用户的对话；
2. 便于排查日志；
3. 便于统计调用情况；
4. 有助于实现用户级限流；
5. 可用于后续数据分析。

对于聊天应用，conversation_id 用于维持同一会话上下文。建议你的业务系统保存每个用户当前会话对应的 conversation_id，当用户开启新话题时再创建新的会话。

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

1. 401 Unauthorized

常见原因：

• API Key 错误；
• 请求头没有带 Authorization；
• Bearer 拼写错误；
• Key 已被删除或失效；
• 调用了错误环境的接口地址。

正确格式：

Authorization: Bearer YOUR_API_KEY

2. 404 Not Found

可能原因：

• API 地址写错；
• 私有部署路径不正确；
• 使用了错误的接口；
• 应用未发布或接口不可用。

建议检查：

https://你的域名/v1/chat-messages

或对应的工作流、文本生成接口地址。

3. 400 Bad Request

常见原因：

• JSON 格式错误；
• 缺少必要参数；
• inputs 字段与应用变量不匹配；
• 文件参数格式错误；
• response_mode 值不正确。

建议先使用 Dify 后台提供的 curl 示例测试，再迁移到代码中。

4. 响应很慢

可能原因：

• 模型本身生成速度慢；
• 提示词过长；
• 知识库检索内容过多；
• 工作流节点太多；
• 网络延迟；
• 使用了非流式响应。

优化建议：

• 使用 streaming 模式；
• 精简提示词；
• 控制知识库召回数量；
• 减少不必要的工作流节点；
• 设置合理的超时时间；
• 选择响应速度更快的模型。

十五、生产环境最佳实践

1. 不要在前端暴露 API Key

错误做法：

fetch("https://dify.example.com/v1/chat-messages", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
})

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

正确做法是：

前端页面 -> 你的后端服务 -> Dify API

由你的后端服务统一管理 API Key、权限、限流和日志。

2. 为不同应用使用不同 API Key

如果你有多个 Dify 应用，例如客服助手、文案生成、订单查询助手，建议分别使用不同的 API Key。这样某个 Key 泄露时，不会影响全部应用。

3. 做好超时与重试机制

AI 接口可能因为模型服务、网络、并发等原因出现延迟或失败。生产环境建议设置：

• 请求超时时间；
• 失败重试；
• 幂等控制；
• 错误日志；
• 用户友好的错误提示。

例如：

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

4. 保存关键日志

建议记录以下信息：

• 用户 ID；
• 请求时间；
• 应用类型；
• 输入摘要；
• 返回状态；
• conversation_id；
• message_id；
• token 消耗；
• 错误信息。

但要注意：
如果涉及隐私、合同、医疗、财务等敏感信息，需要遵守企业安全规范，避免明文保存敏感内容。

5. 控制调用成本

AI API 调用通常会产生模型费用或资源消耗。建议从以下方面控制成本：

• 限制单次输入长度；
• 限制单用户调用频率；
• 设置每日调用额度；
• 优化提示词；
• 减少无效上下文；
• 使用更合适的模型；
• 定期分析 token 消耗。

十六、Dify API 接入典型架构

一个推荐的企业级接入架构如下：

用户
 ↓
前端页面 / App / 小程序
 ↓
业务后端服务
 ↓
权限校验 / 参数校验 / 限流 / 日志记录
 ↓
Dify API
 ↓
大模型 / 知识库 / 工作流 / 工具调用
 ↓
返回结果给业务后端
 ↓
返回给用户

这种架构的优点是：

• API Key 不暴露；
• 可统一做权限控制；
• 可接入企业账号体系；
• 可记录业务日志；
• 可对敏感内容做过滤；
• 可对高频用户做限流；
• 可根据业务情况切换不同 Dify 应用。

十七、完整后端中转示例：Node.js Express

下面是一个简单的后端中转示例。

const express = require("express");

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

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

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

    const response = await fetch("https://dify.example.com/v1/chat-messages", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.DIFY_API_KEY}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        inputs: {},
        query,
        response_mode: "blocking",
        conversation_id: conversation_id || "",
        user: user || "anonymous"
      })
    });

    const data = await response.json();

    res.json({
      answer: data.answer,
      conversation_id: data.conversation_id,
      message_id: data.message_id
    });
  } catch (error) {
    console.error(error);
    res.status(500).json({ error: "AI服务调用失败" });
  }
});

app.listen(3000, () => {
  console.log("Server running at http://localhost:3000");
});

.env 文件中保存：

DIFY_API_KEY=your_api_key_here

这样前端只需要请求你的后端接口：

fetch("/api/ai/chat", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    query: "你好",
    conversation_id: "",
    user: "user-001"
  })
});

十八、接入知识库问答的注意事项

如果你的 Dify 应用绑定了知识库，API 调用方式与普通聊天接口类似，但实际效果取决于知识库配置。

建议注意以下几点：

1. 文档切分要合理，避免片段过长或过短；
2. 知识库标题、正文、元信息要清晰；
3. 召回数量不要过多，否则会增加 token 成本；
4. 对专业领域内容要定期更新；
5. 对无法回答的问题设置兜底提示；
6. 对用户问题进行必要的改写或归一化；
7. 对涉及合规风险的回答增加人工审核流程。

知识库问答不是简单上传文档就能达到最佳效果，核心在于：
文档质量、切分策略、检索配置、提示词约束和模型能力的综合优化。

十九、上线前检查清单

在 Dify API 正式上线前，建议完成以下检查：

• [ ] API Key 是否只保存在后端；
• [ ] 是否设置了请求超时；
• [ ] 是否做了用户身份校验；
• [ ] 是否设置了调用频率限制；
• [ ] 是否保存必要日志；
• [ ] 是否处理了 400、401、404、500 等错误；
• [ ] 是否测试了流式与非流式响应；
• [ ] 是否验证了多轮对话；
• [ ] 是否测试了知识库召回效果；
• [ ] 是否控制了 token 成本；
• [ ] 是否准备了服务异常时的兜底话术；
• [ ] 是否对敏感信息做了脱敏或过滤。

二十、总结

Dify API 的核心价值在于，它可以把可视化搭建好的 AI 应用快速集成到真实业务系统中。对于开发者来说，掌握 Dify API 调用并不复杂，关键是理解以下几点：

1. API Key 用于鉴权，必须妥善保管；
2. 聊天应用使用 /chat-messages；
3. 文本生成应用使用 /completion-messages；
4. 工作流应用使用 /workflows/run；
5. response_mode 决定返回方式，blocking 简单，streaming 体验更好；
6. conversation_id 用于多轮对话；
7. inputs 要与 Dify 应用变量保持一致；
8. 生产环境建议通过后端中转调用；
9. 知识库效果取决于文档质量和检索配置；
10. 上线前必须做好安全、限流、日志和成本控制。

如果你只是想快速测试，可以直接使用 curl 或 Python 调用；如果要正式接入业务系统，建议采用“前端 → 后端 → Dify API”的架构，并结合权限校验、异常处理、日志记录和成本控制进行工程化落地。

通过本文的教程，你已经可以完成 Dify API 的基础调用、流式输出、多轮会话、工作流执行、文件上传和生产环境接入。接下来，你可以根据自己的业务场景，把 Dify 与 CRM、ERP、客服系统、知识库系统、企业微信、飞书、钉钉、小程序或内部管理后台结合起来，构建真正可用、可维护、可扩展的 AI 应用。