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

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

Dify REST API 让您可以从自己的代码中调用任何 Dify 应用 — 将聊天机器人嵌入网站、自动化文档处理，或将 AI 功能集成到任意 SaaS 产品。本指南涵盖从 API 密钥到流式响应和自托管设置的所有内容。

什么是 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 访问的应用创建一个。操作方法如下：

1

在 Studio 中打开您的 Dify 应用

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

2

点击右上角的"API 访问"

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

3

点击"创建 API 密钥"

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

4

立即复制 Secret Key

密钥只显示一次。将其保存为环境变量 — 绝不要直接写在源代码中。

5

在 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 上传文件（PDF、图片等）用于 RAG 或视觉应用。
GET /conversations 列出某用户的所有对话。使用 user 参数进行过滤。
GET /messages 获取特定对话的消息历史。
DELETE /conversations/:id 永久删除一个对话及其所有消息。
POST /messages/:id/feedbacks 为特定消息提交评分（点赞/点踩）。
GET /parameters 获取应用的输入参数、介绍文本和建议问题。

您的第一次 API 调用

让我们进行一次真实的 API 调用。将 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 requests

API_KEY = "your_api_key_here"
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）

流式传输允许在生成过程中实时显示 token — 就像 ChatGPT 的打字效果。Dify 使用服务器发送事件（SSE）进行流式传输。在请求体中设置 "response_mode": "streaming"。

每个事件以 data: 前缀的行形式到达。事件类型包括 message（一个 token 块）、message_end（带元数据的结束消息）和 error。

流式 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"
  }'

Python 流式示例

import requests
import json

def stream_chat(query, user="user-123"):
    with requests.post(
        "https://api.dify.ai/v1/chat-messages",
        headers={
            "Authorization": "Bearer YOUR_API_KEY",
            "Content-Type": "application/json",
        },
        json={
            "inputs": {},
            "query": query,
            "response_mode": "streaming",
            "conversation_id": "",
            "user": user,
        },
        stream=True,
    ) as response:
        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") == "message_end":
                    print()
                    break

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

常见问题

如何获取 Dify API 密钥？

打开您的 Dify 应用，点击右上角的"API 访问"，创建一个新的 API 密钥。复制 Secret Key — 它只显示一次。在 Authorization 请求头中使用它，格式为"Bearer 您的密钥"。

Dify API 是免费的吗？

Dify API 本身是免费的 — 您只需为消耗的 LLM token 付费（OpenAI、Anthropic 等）。自托管 Dify 没有 API 费用。Dify Cloud 按消息积分收费。

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

可以。在请求体中设置"response_mode":"streaming"以获取服务器发送事件（SSE）。这样您就可以在 token 生成时实时显示，就像 ChatGPT 一样。

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

任何支持 HTTP 请求的语言都可以：Python、JavaScript/Node.js、PHP、Ruby、Go、Java、C# 等。Dify 为 Python 和 Node.js 提供官方 SDK，并为每个端点提供 curl 示例。

在生产环境中部署 Dify API

自托管 Dify 让您拥有完整的 API 控制权、无速率限制，且不会向 Dify 发送任何数据。在 Hetzner 上仅需 €3.79/月起步。

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