Dify-11: API参考

本文档提供了关于 Dify 服务 API 的全面信息，使开发人员能够以编程方式集成和与 Dify 应用进行交互。这些 API 允许您构建自定义前端，或利用 Dify 的功能集成各种人工智能应用类型。

API 概述

Dify 根据应用类型提供了不同的 API 端点集：

• 聊天应用：基于会话的对话，带有历史上下文。
• 文本生成应用：无会话历史的无状态文本生成。
• 工作流应用：执行预定义的多步骤工作流。
• 智能体聊天应用：具有使用工具能力的增强型聊天应用。

身份验证

所有 Dify API 都使用 API 密钥进行身份验证。必须使用承载令牌格式将 API 密钥包含在 Authorization HTTP 标头中：

Authorization: Bearer {API_KEY}

出于安全原因，强烈建议将 API 密钥存储在服务器端，而不要在客户端代码中暴露。

响应模式

Dify API 支持两种响应模式：

• 阻塞模式Blocking：完成后返回完整响应（对于长时间运行的进程可能会超时）。
• 流模式Streaming：在生成响应时以块的形式返回响应，使用服务器发送事件（SSE）。

通用请求和响应元素

文件结构

发送文件时，结构通常如下：

{
  "type": "image|document|audio|video|custom",
  "transfer_method": "remote_url|local_file",
  "url": "https://example.com/path/to/file",  // 当 transfer_method 为 remote_url 时
  "upload_file_id": "file-id"  // 当 transfer_method 为 local_file 时
}

流响应结构

在流模式下，响应遵循 SSE 格式：

data: {"event": "message", "task_id": "task-id", "answer": "partial text", ...}\n\n
data: {"event": "message_end", ...}\n\n

每个块以 data: 开头，并由两个换行符分隔。内容是 JSON 格式，根据事件类型具有不同的结构。

---

聊天应用 API

发送聊天消息

端点：POST /chat-messages
创建新的聊天消息或继续现有对话。

请求体：

参数	类型	描述
query	string	用户输入 / 问题内容
inputs	object	应用定义的变量（键值对）
response_mode	string	“streaming” 或 “blocking”
user	string	用户标识符
conversation_id	string	可选 - 继续先前对话的 ID
files	array	可选 - 要处理的文件列表
auto_generate_name	boolean	可选 - 自动生成对话标题

响应：
在阻塞模式下，返回 ChatCompletionResponse 对象。在流模式下，返回 ChunkChatCompletionResponse 流。

流式传输事件：

事件	描述
message	来自大语言模型的文本块
agent_message	智能体模式下的文本块
agent_thought	智能体的推理过程
message_file	工具创建的新文件
tts_message	语音合成输出
message_end	消息结束
error	错误信息

上传文件

端点：POST /files/upload
上传文件以在消息中使用，支持多模态理解。

请求体：包含文件（要上传的文件）和 user（用户标识符）的表单数据。

响应：文件元数据，包括 ID、名称、大小等。

停止生成

端点：POST /chat-messages/:task_id/stop
停止正在进行的消息生成（仅在流模式下）。

路径参数：
task_id：来自流块的任务 ID

请求体：
user：用户标识符

响应：

{
  "result": "success"
}

消息反馈

端点：POST /messages/:message_id/feedbacks
对消息提供反馈（点赞 / 点踩）。

路径参数：
message_id：消息 ID

请求体：

参数	描述
rating	“like”、“dislike” 或 null
user	用户标识符
content	可选的反馈内容

响应：

{
  "result": "success"
}

获取下一个建议问题

端点：GET /messages/{message_id}/suggested
获取当前消息的下一个建议问题。

路径参数：
message_id：消息 ID

查询参数：
user：用户标识符

响应：

{
  "result": "success",
  "data": ["问题 1", "问题 2", "问题 3"]
}

获取对话历史记录

端点：GET /messages
以滚动加载格式返回历史聊天记录。

查询参数：

参数	描述
conversation_id	对话 ID
user	用户标识符
first_id	可选 - 当前页面第一个聊天记录的 ID
limit	可选 - 返回的记录数量（默认 20）

响应：包含消息内容、元数据和反馈的消息列表。

获取对话列表

端点：GET /conversations
检索当前用户的对话列表。

查询参数：

参数	描述
user	用户标识符
last_id	可选 - 当前页面最后一个记录的 ID
limit	可选 - 返回的记录数量（默认 20）
sort_by	可选 - 排序字段

响应：包含对话元数据的对话列表。

删除对话

端点：DELETE /conversations/:conversation_id
删除对话。

路径参数：
conversation_id：对话 ID

请求体：
user：用户标识符

响应：

{
  "result": "success"
}

---

文本生成应用 API

文本生成应用是无会话历史的无状态文本生成应用。

创建文本生成消息

端点：POST /completion-messages
向文本生成应用发送请求。

请求体：

参数	类型	描述
inputs	object	必填 - 必须包含 “query” 键及输入文本
response_mode	string	“streaming” 或 “blocking”
user	string	用户标识符
files	array	可选 - 要处理的文件列表

响应：
类似于聊天 API，但没有对话上下文。

停止文本生成

端点：POST /completion-messages/:task_id/stop
停止正在进行的文本生成（仅在流模式下）。

参数与聊天 API 的停止端点类似。

---

工作流应用 API

工作流应用执行预定义的多步骤工作流。

执行工作流

端点：POST /workflows/run
执行工作流，需要有已发布的工作流。

请求体：

参数	类型	描述
inputs	object	应用定义的变量（键值对）
response_mode	string	“streaming” 或 “blocking”
user	string	用户标识符

响应事件：

事件	描述
workflow_started	工作流开始执行
node_started	节点开始执行
node_finished	节点执行完成
workflow_finished	工作流执行完成
tts_message	语音合成输出
error	错误信息

停止工作流任务

端点：POST /workflows/:task_id/stop
停止正在进行的工作流执行。

路径参数：
task_id：来自流块的任务 ID

支持工作流的高级聊天 API

高级聊天 API 扩展了标准聊天 API，具有工作流功能。它支持所有聊天 API 端点，并在流响应中包含与工作流相关的事件。

高级聊天事件

高级聊天 API 结合了聊天 API 和工作流 API 的功能，具有与聊天 API 相同的端点，但在流响应中包含额外的事件类型。

错误处理

所有 API 端点返回标准的 HTTP 状态码和结构化的错误响应。

状态码	错误码	描述
400	invalid_param	无效的参数输入
400	app_unavailable	应用配置不可用
400	provider_not_initialize	没有可用的模型凭证配置
400	provider_quota_exceeded	模型调用配额已超出
400	model_currently_not_support	当前模型不可用
400	completion_request_error	文本生成失败
404	-	资源未找到
500	-	内部服务器错误

---

API 集成流程

此图展示了客户端应用与 Dify API 之间的集成流程，包括不同的 API 端点、响应模式，以及文件上传和停止生成等可选功能。