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

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 连接。

注意:每种 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 为应用请求上传文件;后续请求必须使用同一个 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 选择部署方式

自部署让您控制 API 基础 URL、网络与服务配置。Hetzner 的德国或芬兰 CX23 自 2026 年 6 月 15 日起为每月 5.49 欧元起,不含增值税与 IPv4。最终成本还包括备份、存储、运维和模型提供商费用,价格与可用性可能变化。

联盟披露:如果您通过以下服务商链接购买,我们可能获得佣金,您无需支付额外费用。

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