2026年9月更新开发者指南 REST API

Dify API 指南 2026：通过 REST 将 AI 集成到您的应用

Dify REST API 让您可以从自己的代码中调用 Dify 应用，例如将聊天机器人嵌入网站、自动化文档处理，或将 AI 功能集成到 SaaS 产品。本指南涵盖 API 密钥、聊天请求、流式响应和自部署基础 URL。

什么是 Dify API？

Dify API 是一个 REST API，让您可以从任何编程语言或平台以编程方式调用在 Dify 中创建的任何应用。一旦发布 Dify 应用（聊天机器人、智能体、工作流或文本生成应用），它就会获得一个独立的 API 端点，您可以使用 Secret Key 调用。

Dify Cloud 的基础 URL 是 https://api.dify.ai/v1。自托管时，替换为您自己的域名：https://your-server.com/v1。

典型使用场景

网站聊天机器人

在任何网站嵌入 AI 聊天，无需使用 Dify 小部件。

文档自动化

将 PDF 或文本发送到 Dify 工作流并获取结构化输出。

SaaS AI 功能

在现有产品中添加 AI 写作、摘要或问答功能。

后端管道

从 cron 任务、Webhook 或队列处理器触发 Dify 智能体。

移动应用

通过标准 HTTP 从 iOS 或 Android 应用调用 Dify。

无代码工具

通过 HTTP 请求节点将 Dify 与 n8n、Make 或 Zapier 连接。

注意：每种 Dify 应用类型（聊天机器人、智能体、工作流、文本生成）都有略微不同的端点。本指南重点介绍最常用的聊天消息 API。

创建 API 密钥

每个 Dify 应用都有自己的 API 密钥。您需要为每个想通过 API 访问的应用创建一个。操作方法如下：

在 Studio 中打开您的 Dify 应用

前往 cloud.dify.ai（或您的自托管 URL），打开您想通过 API 调用的应用。

点击右上角的"API 访问"

这将打开该应用的 API 参考面板。

点击"创建 API 密钥"

给它起个名字（如"生产"或"测试"），方便日后识别。

安全保存 Secret Key

将密钥保存为服务端环境变量，不要写入前端代码或公开代码库。

在 Authorization 请求头中使用它

所有 API 请求都需要此请求头：Authorization: Bearer 您的_API_KEY

安全警告：切勿在客户端 JavaScript 或公开代码库中暴露您的 API 密钥。始终将其存储为环境变量，并始终从后端服务器调用 Dify API。

API 端点概览

Dify API 提供发送消息、管理对话、上传文件等端点。所有端点均相对于基础 URL https://api.dify.ai/v1。

方法	端点	描述
POST	/chat-messages	发送聊天消息并接收回复。支持阻塞和流式传输。
POST	/completion-messages	向文本生成应用发送提示词，返回生成的文本。
POST	/files/upload	为应用请求上传文件；后续请求必须使用同一个 user。知识库摄取使用单独的 Knowledge API。
GET	/conversations	列出某用户的所有对话。使用 user 参数进行过滤。
GET	/messages	获取特定对话的消息历史。
DELETE	/conversations/:id	永久删除一个对话及其所有消息。
POST	/messages/:id/feedbacks	为特定消息提交评分（点赞/点踩）。
GET	/parameters	获取应用的输入参数、介绍文本和建议问题。

先确认应用类型：上表概括应用 API 的常用接口。Chatflow、Workflow、新版 Agent 和文本生成应用的可用端点及流式事件并不完全相同。先调用 /info 查看应用的 mode，再打开对应的官方 API 概览。

先验证密钥，再发送第一条消息

官方快速开始建议先调用适用于所有应用类型的 /info。成功响应会返回应用名称和 mode，这样可以在发送生成请求前确认密钥与应用是否匹配。

curl 'https://api.dify.ai/v1/info' \
  -H 'Authorization: Bearer YOUR_API_KEY'

以下聊天示例适用于支持 /chat-messages 的对话型应用。将 YOUR_API_KEY 替换为实际密钥。user 应是您系统中稳定且不包含敏感信息的终端用户标识符。

聊天应用的 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": "你好！你能帮我做什么？",
    "response_mode": "blocking",
    "conversation_id": "",
    "user": "user-123"
  }'

响应示例

{
  "event": "message",
  "task_id": "abc123",
  "id": "msg_456",
  "message_id": "msg_456",
  "conversation_id": "conv_789",
  "mode": "chat",
  "answer": "你好！我可以帮助您解答问题、撰写文本、进行分析等。您想探索什么？",
  "metadata": { "usage": { "prompt_tokens": 12, "completion_tokens": 22 } },
  "created_at": 1711234567
}

Python 示例（使用 requests 库）

import os
import requests

API_KEY = os.environ["DIFY_API_KEY"]
BASE_URL = "https://api.dify.ai/v1"

def chat(query, conversation_id="", user="user-123"):
    response = requests.post(
        f"{BASE_URL}/chat-messages",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "inputs": {},
            "query": query,
            "response_mode": "blocking",
            "conversation_id": conversation_id,
            "user": user,
        }
    )
    response.raise_for_status()
    return response.json()

# 第一条消息
result = chat("什么是 Dify？")
print(result["answer"])
conversation_id = result["conversation_id"]

# 在同一对话中继续
result2 = chat("能详细说明吗？", conversation_id=conversation_id)
print(result2["answer"])

提示：保存第一次响应中的 conversation_id 并在后续调用中传递它。这样可以保持对话历史，AI 会记住之前说过的内容。

流式响应（SSE）

流式传输允许在生成过程中逐步显示回复。Dify 使用服务器发送事件（SSE）进行流式传输。在请求体中设置 "response_mode": "streaming"。

除保活用的 ping 外，事件通常以 data: 行传递 JSON。Chatbot 和 Chatflow 使用 message 片段，旧版 Agent 和新版 Agent 使用 agent_message。终止事件也因应用类型而异，因此不要把所有流都只按 message 和 message_end 处理。

流式 curl 示例

curl -X POST 'https://api.dify.ai/v1/chat-messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --no-buffer \
  -d '{
    "inputs": {},
    "query": "写一首关于 AI 的短诗。",
    "response_mode": "streaming",
    "conversation_id": "",
    "user": "user-123"
  }'

Chatbot 的 Python 流式示例

import os
import json
import requests

API_KEY = os.environ["DIFY_API_KEY"]

def stream_chat(query, user="user-123"):
    with requests.post(
        "https://api.dify.ai/v1/chat-messages",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "inputs": {},
            "query": query,
            "response_mode": "streaming",
            "conversation_id": "",
            "user": user,
        },
        stream=True,
    ) as response:
        response.raise_for_status()
        for line in response.iter_lines():
            if line and line.startswith(b"data: "):
                data = json.loads(line[6:])
                if data.get("event") == "message":
                    print(data["answer"], end="", flush=True)
                elif data.get("event") == "error":
                    raise RuntimeError(data.get("message", "Dify stream error"))
                elif data.get("event") == "message_end":
                    print()
                    break

stream_chat("简单解释量子计算。")

常见问题

如何获取 Dify API 密钥？

在已发布的应用内打开 API 访问并创建应用密钥。应用密钥只适用于对应应用，应保存在服务端，并通过 Authorization: Bearer 您的密钥请求头发送。

Dify API 是免费的吗？

费用和限额取决于部署方式与套餐。Dify Cloud 套餐包含不同的 API 限额和消息积分；使用自有模型密钥时，模型提供商另行计费。自部署仍需承担服务器与模型成本。

可以流式传输 Dify API 响应吗？

可以。生成类接口通过 response_mode 选择 blocking 或 streaming。流式模式使用 SSE，但事件名称和终止事件取决于 Chatbot、Chatflow、Agent 或 Workflow 等应用类型。

哪些编程语言可以使用 Dify API？

任何能够发送 HTTPS 请求的语言都可以使用 Dify API，例如 Python、JavaScript、PHP、Ruby、Go、Java 和 C#。集成时应以当前官方端点文档为准。

本指南核对的官方资料

Dify 的应用类型、端点和事件契约会继续变化。部署前请用以下官方页面复核代码：

在生产环境中部署 Dify API

自部署 Dify 让您控制实例的 API 基础 URL 和服务配置。实际吞吐量仍取决于部署资源、并发设置和模型提供商限制。在 Hetzner 上仅需 €3.79/月起步。

在 Hetzner 上部署 → Dify 入门教程比较所有托管选项