Dify API接口调用教程｜生产环境实测

在大模型应用真正落地到生产环境时，很多团队都会遇到同一个问题：平台里调试效果不错，但如何稳定、可控、安全地接入业务系统？
Dify 作为一个比较成熟的 AI 应用开发平台，提供了可视化编排、知识库、工作流、Agent、变量管理、日志观测等能力，同时也提供了标准化 API，方便开发者把 Dify 中搭建好的应用接入到 Web 系统、App、小程序、企业内部系统或自动化流程中。

本文将围绕 Dify API 接口调用 展开，结合生产环境中的真实使用思路，系统介绍 Dify API 的调用方式、参数含义、流式响应、阻塞响应、会话管理、文件上传、错误处理、安全策略以及上线注意事项。

一、为什么要用 Dify API？

在 Dify 控制台中，我们可以很方便地创建以下类型的 AI 应用：

• 聊天助手 Chatbot
• 文本生成应用 Text Generator
• Agent 智能体
• Workflow 工作流
• 知识库问答应用
• 多步骤自动化任务

但如果只停留在控制台里测试，应用价值是有限的。生产环境中更常见的场景是：

1. 用户在业务系统中输入问题；
2. 后端服务调用 Dify API；
3. Dify 根据应用配置、Prompt、知识库、工作流逻辑生成结果；
4. 后端将结果返回给前端；
5. 前端展示给用户，或进入下一步业务流程。

也就是说，Dify API 是连接 AI 应用编排平台 和 真实业务系统 的桥梁。

相比直接调用 OpenAI、通义千问、Claude、DeepSeek 等模型接口，使用 Dify API 有几个明显优势：

• Prompt 可视化维护：无需每次改代码都调整提示词；
• 支持知识库检索：可以快速实现企业知识问答；
• 工作流编排方便：多个节点逻辑可视化搭建；
• 模型可切换：后端代码不需要频繁改动；
• 日志可追踪：便于调试和运营分析；
• 权限与密钥管理清晰：适合团队协作；
• 支持流式输出：体验接近 ChatGPT。

二、准备工作

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

1. 创建 Dify 应用

登录 Dify 控制台后，可以根据业务需求创建应用。常见选择如下：

如果是生产环境，我更建议优先考虑 Workflow 或 聊天助手 + 知识库。
Workflow 的优势是流程明确，输入输出更可控，适合对稳定性要求较高的业务场景。

2. 获取 API Key

进入应用详情页后，通常可以在「API 访问」或「Access API」相关页面找到接口调用说明和 API Key。

API Key 一般长这样：

app-xxxxxxxxxxxxxxxxxxxxxxxx

调用接口时需要在请求头中携带：

Authorization: Bearer app-xxxxxxxxxxxxxxxxxxxxxxxx

注意：
API Key 一定不要暴露在前端代码中。

错误示例：

// 不推荐：直接在前端写 Dify API Key
const apiKey = "app-xxxxxx";

正确做法是：

• 前端请求自己的后端服务；
• 后端服务读取环境变量中的 Dify API Key；
• 后端服务再调用 Dify API；
• 后端将结果返回前端。

3. 确认 API 地址

如果使用 Dify 云服务，API 地址一般类似：

https://api.dify.ai/v1

如果是私有化部署，则地址通常为：

https://你的域名/v1

例如：

https://dify.example.com/v1

生产环境建议使用 HTTPS，并配置好反向代理、证书和防火墙策略。

三、Dify 常用 API 类型

Dify 的 API 根据应用类型不同，会有不同接口。常见接口包括：

本文重点讲三类生产环境中最常用的接口：

1. 聊天接口 /chat-messages
2. 文本生成接口 /completion-messages
3. 工作流接口 /workflows/run

四、调用聊天接口 /chat-messages

聊天接口适用于 Chatbot、知识库问答、多轮对话等应用。

1. 请求地址

POST /v1/chat-messages

完整地址示例：

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

2. 请求头

Authorization: Bearer app-你的APIKey
Content-Type: application/json

3. 请求参数说明

常用请求体如下：

{
  "inputs": {},
  "query": "请介绍一下你们公司的售后政策",
  "response_mode": "blocking",
  "conversation_id": "",
  "user": "user-001"
}

字段说明：

其中比较关键的是 conversation_id 和 user。

• user 用来标识最终用户；
• conversation_id 用来维持同一轮对话上下文；
• 第一次请求可以不传 conversation_id；
• Dify 返回结果中会带上新的 conversation_id；
• 后续同一会话继续传这个 ID。

4. cURL 调用示例

curl -X POST 'https://api.dify.ai/v1/chat-messages' \
  -H 'Authorization: Bearer app-你的APIKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {},
    "query": "帮我总结一下Dify的主要功能",
    "response_mode": "blocking",
    "conversation_id": "",
    "user": "user-001"
  }'

5. 返回结果示例

阻塞模式下，一般会在完整生成后一次性返回：

{
  "event": "message",
  "task_id": "task-xxxx",
  "id": "msg-xxxx",
  "message_id": "msg-xxxx",
  "conversation_id": "conv-xxxx",
  "mode": "chat",
  "answer": "Dify 是一个用于构建大模型应用的平台，主要功能包括……",
  "metadata": {
    "usage": {
      "prompt_tokens": 100,
      "completion_tokens": 200,
      "total_tokens": 300
    }
  },
  "created_at": 1710000000
}

生产环境中，至少建议保存以下字段：

• conversation_id
• message_id
• answer
• usage
• created_at
• 当前业务用户 ID
• 当前业务请求 ID

这些数据对后续排查问题、统计成本和分析用户行为非常有用。

五、阻塞模式与流式模式

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

"response_mode": "blocking"

或：

"response_mode": "streaming"

1. blocking 阻塞模式

阻塞模式的特点是：

• 请求发出后等待模型完整生成；
• 最后一次性返回完整结果；
• 后端处理简单；
• 前端体验一般；
• 适合短文本生成、分类、摘要等任务。

例如：

{
  "response_mode": "blocking"
}

适用场景：

• 文本分类
• JSON 结构化提取
• 简短摘要
• 自动标签生成
• 后台批处理任务

2. streaming 流式模式

流式模式的特点是：

• 模型边生成边返回；
• 用户可以实时看到文字输出；
• 体验更好；
• 后端和前端都需要处理流；
• 适合聊天机器人、长文本输出。

例如：

{
  "response_mode": "streaming"
}

流式返回通常是 Server-Sent Events，也就是 SSE 格式。返回内容类似：

data: {"event":"message","answer":"你好"}

data: {"event":"message","answer":"，很高兴"}

data: {"event":"message","answer":"为你服务"}

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

前端需要不断读取 data: 后面的 JSON，并将 answer 追加到页面上。

六、Node.js 调用 Dify API 示例

下面以 Node.js 后端为例，演示如何调用 Dify 聊天接口。

1. 安装依赖

npm install express axios dotenv

2. 配置环境变量

创建 .env 文件：

DIFY_API_KEY=app-你的APIKey
DIFY_API_BASE_URL=https://api.dify.ai/v1

3. 后端接口示例

import express from "express";
import axios from "axios";
import dotenv from "dotenv";

dotenv.config();

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

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

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

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

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

    return res.status(500).json({
      message: "AI服务暂时不可用，请稍后重试"
    });
  }
});

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

这个示例适合阻塞式接口调用。如果是生产环境，还需要增加鉴权、限流、日志记录、异常重试等逻辑。

七、Python 调用 Dify API 示例

如果你的业务系统使用 Python，也可以通过 requests 调用。

1. 安装依赖

pip install requests python-dotenv

2. 示例代码

import os
import requests
from dotenv import load_dotenv

load_dotenv()

DIFY_API_KEY = os.getenv("DIFY_API_KEY")
DIFY_API_BASE_URL = os.getenv("DIFY_API_BASE_URL", "https://api.dify.ai/v1")

def chat_with_dify(query, user_id="user-001", conversation_id=""):
    url = f"{DIFY_API_BASE_URL}/chat-messages"

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

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

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

    data = response.json()

    return {
        "answer": data.get("answer"),
        "conversation_id": data.get("conversation_id"),
        "message_id": data.get("message_id"),
        "usage": data.get("metadata", {}).get("usage")
    }

if __name__ == "__main__":
    result = chat_with_dify("请用三句话介绍Dify")
    print(result)

八、调用文本生成接口 /completion-messages

如果你的应用是文本生成类型，比如：

• 生成营销文案；
• 生成日报；
• 对文章进行摘要；
• 从文本中提取结构化信息；
• 生成邮件回复；
• 根据表单信息生成合同片段；

就可以使用 /completion-messages 接口。

1. 请求示例

curl -X POST 'https://api.dify.ai/v1/completion-messages' \
  -H 'Authorization: Bearer app-你的APIKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {
      "topic": "Dify API接口调用教程",
      "style": "技术博客"
    },
    "response_mode": "blocking",
    "user": "user-001"
  }'

2. 参数说明

和聊天接口相比，文本生成接口通常不需要 query，而是主要依赖 inputs 中的变量。

例如你在 Dify 应用里定义了两个变量：

• topic
• style

那么调用 API 时就需要传：

{
  "inputs": {
    "topic": "Dify API接口调用教程",
    "style": "技术博客"
  }
}

这也是 Dify 在生产环境中非常实用的地方：
业务代码只负责传入变量，具体 Prompt 逻辑可以在 Dify 控制台中维护。

九、调用工作流接口 /workflows/run

Workflow 是 Dify 生产环境中非常推荐使用的能力。因为它可以将复杂任务拆成多个节点，例如：

1. 接收用户输入；
2. 判断问题类型；
3. 查询知识库；
4. 调用大模型生成回答；
5. 格式化输出；
6. 返回结构化结果。

1. 请求示例

curl -X POST 'https://api.dify.ai/v1/workflows/run' \
  -H 'Authorization: Bearer app-你的APIKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {
      "question": "请分析这段用户反馈的情绪倾向",
      "content": "客服回复太慢了，我等了三天还没解决。"
    },
    "response_mode": "blocking",
    "user": "user-001"
  }'

2. 返回结果

工作流的返回结构会根据节点配置有所不同，通常会包含：

{
  "workflow_run_id": "run-xxxx",
  "task_id": "task-xxxx",
  "data": {
    "id": "run-xxxx",
    "workflow_id": "workflow-xxxx",
    "status": "succeeded",
    "outputs": {
      "sentiment": "负面",
      "reason": "用户表达了等待时间过长和问题未解决的不满"
    },
    "elapsed_time": 2.35,
    "total_tokens": 500,
    "total_steps": 4,
    "created_at": 1710000000,
    "finished_at": 1710000002
  }
}

生产环境中使用 Workflow 时，建议尽量让最终输出保持结构化，例如：

{
  "category": "售后投诉",
  "sentiment": "negative",
  "summary": "用户反馈客服响应慢，问题三天未解决",
  "suggestion": "建议升级人工客服处理"
}

这样业务系统更容易解析，而不是依赖自然语言回答。

十、文件上传接口 /files/upload

在一些场景中，用户可能需要上传图片、文档、音频或其他文件，再交给 Dify 应用处理。

典型场景：

• 上传合同，让 AI 提取关键信息；
• 上传图片，让 AI 分析内容；
• 上传简历，让 AI 生成候选人评价；
• 上传文档，让工作流做摘要。

文件上传接口通常使用 multipart/form-data。

cURL 示例

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

上传成功后会返回文件 ID。后续可以在聊天、工作流或文本生成接口中引用该文件。

生产环境注意事项：

• 限制文件大小；
• 校验文件类型；
• 对用户上传文件做安全扫描；
• 避免敏感文件被越权访问；
• 文件处理失败时给出明确提示。

十一、生产环境实测经验

下面是一些在真实生产环境中非常重要，但很多教程容易忽略的点。

1. API Key 必须放在后端

这是最基本但也最容易犯错的问题。

不要把 Dify API Key 写在：

• Vue/React 前端代码；
• 小程序端代码；
• App 客户端代码；
• 浏览器本地存储；
• 公开 Git 仓库。

推荐方式：

DIFY_API_KEY=app-xxxx

后端通过环境变量读取，并对外提供自己的业务接口。

2. 给每个用户设置稳定的 user 标识

Dify API 中的 user 字段不是随便填的。生产环境建议使用业务系统中的用户 ID，例如：

"user": "uid_10086"

如果是未登录用户，也可以生成匿名 ID：

"user": "guest_abc123"

这样可以方便：

• 追踪请求来源；
• 分析用户行为；
• 做限流策略；
• 定位异常调用；
• 区分不同用户会话。

3. 会话 ID 要由后端统一管理

对于聊天类应用，conversation_id 很关键。建议不要完全依赖前端保存，而是后端建立会话表。

可以设计一张简单的表：

这样可以支持：

• 历史会话列表；
• 多轮上下文；
• 删除会话；
• 重新打开会话；
• 用户隔离。

4. 设置合理的超时时间

AI 接口和普通接口不同，响应时间受模型、上下文长度、知识库检索、工作流节点数量等因素影响。

生产环境建议：

• 短文本任务：30 秒左右；
• 普通聊天：60 秒左右；
• 长文本生成：120 秒左右；
• 复杂工作流：根据节点数量单独评估。

如果任务时间较长，建议使用流式响应或异步任务模式，不要让用户一直等待白屏。

5. 做好错误处理

Dify API 调用可能出现以下问题：

• API Key 错误；
• 请求参数错误；
• 模型服务异常；
• 网络超时；
• 知识库检索失败；
• 工作流节点执行失败；
• 用户输入过长；
• 并发过高；
• 第三方模型限速。

后端不要直接把 Dify 的原始错误全部暴露给用户。可以做一层包装：

{
  "message": "AI服务暂时不可用，请稍后重试"
}

同时在服务端记录详细日志：

用户ID、请求参数、Dify返回错误、耗时、traceId、时间

6. 增加限流与防刷

AI 调用是有成本的。如果没有限流，很容易被恶意刷接口，导致费用飙升。

建议至少做以下限制：

• 单用户每分钟请求次数限制；
• 单 IP 每分钟请求次数限制；
• 单用户每日 token 或调用次数限制；
• 未登录用户更严格限制；
• 异常请求自动封禁。

例如：

登录用户：每分钟 20 次
未登录用户：每分钟 3 次
同 IP：每分钟 60 次

7. 记录 token 用量和成本

Dify 返回结果中通常包含 usage 信息，例如：

{
  "prompt_tokens": 1000,
  "completion_tokens": 500,
  "total_tokens": 1500
}

建议将其保存到数据库中。这样可以统计：

• 每个用户消耗；
• 每个应用消耗；
• 每天总消耗；
• 哪些任务最费 token；
• 哪些 Prompt 需要优化。

如果企业内部有多个部门使用 AI 应用，也可以按部门做成本分摊。

8. Prompt 和输出要做版本管理

很多团队上线后会频繁修改 Dify 中的 Prompt 或工作流节点。如果没有版本管理，就可能出现：

• 今天效果好，明天突然变差；
• 后端解析字段突然不存在；
• 用户投诉但无法复现；
• 不知道是哪次改动导致问题。

建议建立发布规范：

1. Dify 内部先调试；
2. 测试环境验证；
3. 记录版本号和修改内容；
4. 再发布到生产应用；
5. 后端日志记录当前应用版本。

如果工作流输出是 JSON，尤其要注意字段名稳定。

十二、前端如何处理流式输出

如果你希望实现类似 ChatGPT 的打字机效果，就需要前端处理 SSE 流。

基本逻辑是：

1. 前端请求后端流式接口；
2. 后端调用 Dify streaming；
3. 后端将 Dify 的 SSE 数据转发给前端；
4. 前端逐段解析并追加显示。

注意，生产环境不建议前端直接请求 Dify，因为会暴露 API Key。应该由后端转发。

前端伪代码示例：

const response = await fetch("/api/chat-stream", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    query: "请介绍一下Dify API",
    conversationId: ""
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder("utf-8");

let answer = "";

while (true) {
  const { value, done } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  answer += chunk;

  console.log("当前输出：", answer);
}

实际项目中还需要解析 data:、处理换行、识别 message_end 事件，并在结束时保存 conversation_id 和 message_id。

十三、接口调用常见问题

1. 为什么返回 401？

通常是 API Key 错误或请求头格式不正确。检查：

Authorization: Bearer app-xxxx

注意 Bearer 后面有一个空格。

2. 为什么返回 400？

通常是参数错误。检查：

• inputs 是否缺失；
• 必填变量是否没有传；
• query 是否为空；
• response_mode 是否正确；
• 应用类型和接口是否匹配。

例如，聊天应用应该调用 /chat-messages，文本生成应用应该调用 /completion-messages。

3. 为什么多轮对话没有上下文？

大概率是没有正确传 conversation_id。

第一次请求可以为空，后续请求必须传上一次返回的 conversation_id。

4. 为什么接口很慢？

可能原因包括：

• 模型本身响应慢；
• Prompt 太长；
• 知识库召回内容过多；
• 工作流节点太多；
• 输出内容过长；
• 网络链路不稳定；
• 第三方模型限流。

优化方式：

• 缩短 Prompt；
• 限制知识库召回数量；
• 使用更快的模型；
• 开启流式输出；
• 拆分复杂任务；
• 对高频问题做缓存。

5. 为什么返回内容不是 JSON？

如果你要求模型输出 JSON，但 Prompt 不够严格，模型仍可能返回自然语言。

建议在 Prompt 中明确要求：

你必须只输出合法 JSON，不要输出 Markdown，不要输出解释说明。
字段包括：category、summary、confidence。

同时后端要做 JSON 解析失败的兜底处理。

十四、生产环境推荐架构

一个较稳妥的生产环境架构如下：

用户前端
   ↓
业务后端 API
   ↓
鉴权 / 限流 / 参数校验
   ↓
Dify API 调用层
   ↓
Dify 应用 / 工作流 / 知识库
   ↓
模型服务

业务后端需要承担以下职责：

• 用户身份认证；
• 参数校验；
• API Key 保护；
• 请求限流；
• 日志记录；
• 会话管理；
• 错误包装；
• 成本统计；
• 结果缓存；
• 敏感词过滤；
• 数据权限控制。

Dify 则负责：

• Prompt 编排；
• 工作流执行；
• 知识库检索；
• 模型调用；
• 应用日志；
• 节点调试。

这种分层方式既保留了 Dify 的灵活性，也保证了业务系统的安全性和可控性。

十五、上线前检查清单

正式上线前，建议逐项检查：

• [ ] API Key 是否只存放在后端环境变量中；
• [ ] 是否配置 HTTPS；
• [ ] 是否设置接口超时；
• [ ] 是否有用户鉴权；
• [ ] 是否有 IP 或用户级限流；
• [ ] 是否记录请求日志；
• [ ] 是否记录 token 用量；
• [ ] 是否保存 conversation_id；
• [ ] 是否处理 Dify 错误返回；
• [ ] 是否有测试环境；
• [ ] Prompt 是否经过多人测试；
• [ ] 工作流输出字段是否稳定；
• [ ] 是否有敏感信息过滤；
• [ ] 是否准备降级方案；
• [ ] 是否配置监控告警。

十六、总结

Dify API 的调用本身并不复杂，核心就是：

• 获取 API Key；
• 选择正确接口；
• 设置请求头；
• 传入 inputs、query、user 等参数；
• 根据业务选择 blocking 或 streaming；
• 解析返回结果。

但真正进入生产环境后，重点并不是“能不能调通”，而是：

• 是否安全；
• 是否稳定；
• 是否可追踪；
• 是否可控成本；
• 是否方便排查问题；
• 是否能支持多轮会话；
• 是否适合业务系统长期维护。

如果只是做 Demo，几行 cURL 就够了；如果要上线给真实用户使用，就必须把鉴权、限流、日志、会话、错误处理、成本统计和版本管理都考虑进去。

整体来看，Dify 非常适合作为企业 AI 应用的中间层。它可以让产品、运营、算法和研发在同一个平台上协作：研发负责系统集成和安全稳定，产品和运营可以在 Dify 中调整应用逻辑，算法或 AI 工程师可以优化 Prompt、知识库和模型配置。

对于希望快速落地 AI 能力的团队来说，Dify API 是一个值得深入掌握的能力。只要架构设计合理，它不仅能帮助我们快速搭建 AI 助手，也能支撑更复杂的企业级智能工作流。