Dify-14: 工作流API端点
本文档提供了 Dify 中工作流 API 端点的全面文档，使开发人员能够以编程方式执行、监控和管理工作流。这些端点是服务 API 层的一部分，允许外部应用程序与 Dify 的工作流功能进行集成。
工作流 API 概述
工作流 API 提供了端点，使开发人员能够与 Dify 的工作流编排系统进行交互。Dify 中的工作流表示一系列操作，这些操作被组织为节点的有向图，每个节点执行特定任务，如文本生成、数据处理或外部服务集成。
身份验证
所有工作流 API 端点都使用 API 密钥进行身份验证。所有请求都必须在 Authorization HTTP 标头中包含您的 API 密钥：
Authorization: Bearer {API_KEY}
强烈建议将 API 密钥存储在服务器端，不要在客户端共享或存储，以防止潜在的安全漏洞。
工作流执行端点
执行工作流
端点：POST /workflows/run
此端点允许执行已发布的工作流。
请求体：
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| inputs | object | 是 | 工作流的输入变量字典。键对应于工作流中定义的变量名，值是这些变量的相应值。 |
| response_mode | string | 是 | 响应模式：“streaming”（推荐）或 “blocking”。 |
| user | string | 是 | 用于定义终端用户身份的用户标识符。 |
对于文件输入，值应为具有以下结构的对象列表：
{"type": "document|image|audio|video|custom","transfer_method": "remote_url|local_file","url": "https://example.com/file.jpg", // 当 transfer_method 为 remote_url 时"upload_file_id": "file-id" // 当 transfer_method 为 local_file 时
}
响应：响应格式取决于response_mode 参数：
- 阻塞模式：返回具有以下结构的 JSON 对象：
{"workflow_run_id": "workflow-run-id","task_id": "task-id","data": {"id": "workflow-execution-id","workflow_id": "workflow-id","status": "succeeded|failed|stopped","outputs": {},"error": "error message (if any)","elapsed_time": 1.23,"total_tokens": 1000,"total_steps": 5,"created_at": 1705395332,"finished_at": 1705395335}
}
- 流式模式：返回包含多个事件的 SSE（服务器发送事件）流，包括：
- workflow_started：表示工作流执行已开始。
- node_started：表示工作流节点已开始执行。
- node_finished：表示工作流节点已完成执行。
- workflow_finished：表示工作流执行已完成。
- tts_message：TTS 音频流事件（如果适用）。
- tts_message_end：TTS 音频流结束事件（如果适用）。
工作流执行过程
以下图表说明了工作流执行过程以及流式模式下发送的事件：
工作流控制端点
停止工作流执行
端点：POST /workflows/{task_id}/stop
此端点允许停止正在运行的工作流执行。
请求体：
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| user | string | 是 | 用户标识符，必须与执行请求中使用的标识符匹配。 |
响应：
{"result": "success"
}
获取工作流运行详情
端点：GET /workflows/{workflow_run_id}
此端点检索特定工作流运行的详细信息。
响应：
{"id": "workflow-run-id","workflow_id": "workflow-id","status": "running|succeeded|failed|stopped","inputs": {},"outputs": {},"error": "error message (if any)","total_steps": 5,"total_tokens": 1000,"created_at": 1705395332,"finished_at": 1705395335,"elapsed_time": 1.23
}
与聊天应用程序的集成
工作流可以与 Dify 中的聊天应用程序集成。当工作流作为聊天交互的一部分执行时，聊天 API 端点将在其流式响应中包含与工作流相关的事件。
在高级聊天 API 中，以下与工作流相关的事件可以包含在流式响应中：
workflow_started：表示工作流已开始执行。node_started：表示工作流节点已开始执行。node_finished：表示工作流节点已完成执行。workflow_finished：表示工作流已完成执行。
这些事件的结构与工作流执行端点中描述的相同。
工作流中的文件处理
工作流支持文件输入，这些输入可以由工作流节点进行处理。文件可以通过以下两种方式提供：
- 远程 URL：提供文件的 URL，Dify 将下载并处理它。
- 本地文件：首先使用文件上传 API 上传文件，然后在工作流执行请求中提供文件 ID。
支持的文件类型
| 类别 | 支持的扩展名 |
|---|---|
| 文档 | TXT, MD, MARKDOWN, PDF, HTML, XLSX, XLS, DOCX, CSV, EML, MSG, PPTX, PPT, XML, EPUB |
| 图像 | JPG, JPEG, PNG, GIF, WEBP, SVG |
| 音频 | MP3, M4A, WAV, WEBM, AMR |
| 视频 | MP4, MOV, MPEG, MPGA |
| 自定义 | 其他文件类型 |
文件上传 API
端点：POST /files/upload
此端点允许上传用于工作流执行的文件。
请求：
这是一个multipart/form-data 请求，包含以下字段：
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
| file | file | 是 | 要上传的文件 |
| user | string | 是 | 用户标识符 |
响应：
{"id": "file-id","name": "example.png","size": 1024,"extension": "png","mime_type": "image/png","created_by": "user-id","created_at": 1577836800
}
错误处理
工作流 API 可以返回以下错误：
| 状态码 | 错误码 | 描述 |
|---|---|---|
| 400 | invalid_param | 请求中的参数无效 |
| 400 | app_unavailable | 应用配置不可用 |
| 400 | provider_not_initialize | 没有可用的模型凭证配置 |
| 400 | provider_quota_exceeded | 模型调用配额已超出 |
| 400 | model_currently_not_support | 当前模型不可用 |
| 400 | workflow_request_error | 工作流执行失败 |
| 500 | - | 内部服务器错误 |
完整的工作流 API 请求 / 响应示例
示例请求
curl -X POST 'https://api.dify.ai/v1/workflows/run' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{"inputs": {"text_input": "Analyze this text for sentiment","files": [{"type": "document","transfer_method": "local_file","upload_file_id": "72fa9618-8f89-4a37-9b33-7e1178a24a67"}]},"response_mode": "streaming","user": "user-123"
}'
示例流式响应
data: {"event": "workflow_started", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "workflow_id": "dfjasklfjdslag", "sequence_number": 1, "created_at": 1679586595}}data: {"event": "node_started", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "node_id": "dfjasklfjdslag", "node_type": "start", "title": "Start", "index": 0, "predecessor_node_id": "fdljewklfklgejlglsd", "inputs": {}, "created_at": 1679586595}}data: {"event": "node_finished", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "node_id": "dfjasklfjdslag", "node_type": "start", "title": "Start", "index": 0, "predecessor_node_id": "fdljewklfklgejlglsd", "inputs": {}, "outputs": {}, "status": "succeeded", "elapsed_time": 0.324, "execution_metadata": {"total_tokens": 63127864, "total_price": 2.378, "currency": "USD"}, "created_at": 1679586595}}data: {"event": "workflow_finished", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "workflow_id": "dfjasklfjdslag", "outputs": {}, "status": "succeeded", "elapsed_time": 0.324, "total_tokens": 63127864, "total_steps": "1", "created_at": 1679586595, "finished_at": 1679976595}}