Dify API 教程 2026:密钥、端点、curl 与 Python
从后端安全调用 Dify API:先用 /info 确认应用类型,再选择 Chatbot、Agent、Workflow 或文本生成端点。以下 curl 与 Python 示例同时说明密钥保护和 SSE 事件处理。
什么是 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 连接。
创建 API 密钥
每个 Dify 应用都有自己的 API 密钥。您需要为每个想通过 API 访问的应用创建一个。操作方法如下:
在 Studio 中打开您的 Dify 应用
前往 cloud.dify.ai(或您的自托管 URL),打开您想通过 API 调用的应用。
点击右上角的"API 访问"
这将打开该应用的 API 参考面板。
点击"创建 API 密钥"
给它起个名字(如"生产"或"测试"),方便日后识别。
安全保存 Secret Key
将密钥保存为服务端环境变量,不要写入前端代码或公开代码库。
在 Authorization 请求头中使用它
所有 API 请求都需要此请求头:Authorization: Bearer 您的_API_KEY
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 | 获取应用的输入参数、介绍文本和建议问题。 |
/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 选择部署方式
自部署让您控制 API 基础 URL、网络与服务配置。Hetzner 的德国或芬兰 CX23 自 2026 年 6 月 15 日起为每月 5.49 欧元起,不含增值税与 IPv4。最终成本还包括备份、存储、运维和模型提供商费用,价格与可用性可能变化。
联盟披露:如果您通过以下服务商链接购买,我们可能获得佣金,您无需支付额外费用。