{ "openapi": "3.0.1", "info": { "title": "Workflow 应用 API", "description": "Workflow 应用提供无会话支持，适用于翻译、文章写作、摘要 AI 等场景。", "version": "1.0.0" }, "servers": [ { "url": "https://{api_base_url}", "description": "Workflow 应用 API 的基础 URL。自部署时，替换为你的 API 基础 URL。", "variables": { "api_base_url": { "default": "api.dify.ai/v1", "description": "API 基础 URL 的主机与路径，不含 `https://` 前缀。" } } } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/workflows/run": { "post": { "summary": "执行工作流", "description": "执行工作流。没有已发布的工作流时无法执行。", "operationId": "executeWorkflowCn", "tags": [ "工作流" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowExecutionRequest" }, "examples": { "streaming_example": { "summary": "请求示例 - 流式模式", "value": { "inputs": { "query": "Summarize this text: The quick brown fox jumps over the lazy dog." }, "response_mode": "streaming", "user": "user_workflow_123" } }, "blocking_example": { "summary": "请求示例 - 阻塞模式", "value": { "inputs": { "query": "Translate this to French: Hello world" }, "response_mode": "blocking", "user": "user_workflow_456" } }, "with_file_array_variable": { "summary": "Request Example - File array input", "value": { "inputs": { "my_documents": [ { "type": "document", "transfer_method": "local_file", "upload_file_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab" }, { "type": "image", "transfer_method": "remote_url", "url": "https://example.com/image.jpg" } ] }, "response_mode": "blocking", "user": "user_workflow_789" } } } } } }, "responses": { "200": { "description": "请求成功。内容类型和结构取决于请求中的 `response_mode` 参数。\n\n- 如果 `response_mode` 为 `blocking`，返回 `application/json` 和 `WorkflowBlockingResponse` 对象。\n- 如果 `response_mode` 为 `streaming`，返回 `text/event-stream` 和 `ChunkWorkflowEvent` 对象流。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowBlockingResponse" }, "examples": { "blockingResponse": { "summary": "响应示例 - 阻塞模式", "value": { "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": { "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", "status": "succeeded", "outputs": { "result": "Bonjour le monde" }, "error": null, "elapsed_time": 1.23, "total_tokens": 150, "total_steps": 3, "created_at": 1705407629, "finished_at": 1705407630 } } } } }, "text/event-stream": { "schema": { "type": "string", "description": "服务器发送事件 (SSE) 流。\n\n**解析**：每行以 `data: ` 开头，后接一个 JSON 对象，以 `\\n\\n` 终止。解析 JSON 前先去除 `data: ` 前缀，再读取 `event` 字段确定事件类型。忽略 `ping` 事件，该事件每 10 秒发送一次以保持连接活跃。\n\n**流生命周期**：收到 `workflow_finished`、`workflow_paused` 或 `error` 事件时流关闭。错误以流内 `error` 事件的形式返回，HTTP 状态码始终为 `200`；请检查事件载荷获取详情，不要依赖状态码判断。\n\n**推理事件**：\n- `reasoning_chunk`：来自 `reasoning_format` 为 `separated` 的 LLM 节点的推理内容增量。拼接连续的 `reasoning_chunk` 事件即可还原完整推理内容；`is_final: true` 的事件标志该节点思考结束（且 `reasoning` 可能为空）。载荷位于 `data` 下，与对话应用不同，不含 `message_id` 或 `conversation_id`。并行的 `text_chunk` 流不含 `` 标签。\n\n**人工介入事件**：\n- `human_input_required`：工作流到达人工介入节点时与 `workflow_paused` 一同触发。使用载荷中的 `form_token` 通过 [人工介入 API](/api-reference/人工介入/获取人工介入表单) 处理表单。\n- `human_input_form_filled`：接收者提交了表单，工作流恢复执行。\n- `human_input_form_timeout`：表单超时未响应。如定义了超时回退分支，工作流将沿该分支执行。" }, "examples": { "streamingResponse": { "summary": "响应示例 - 流式模式", "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Let me translate that.\", \"node_id\": \"node_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}" }, "humanInputPause": { "summary": "响应示例 - 人工介入暂停", "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}} data: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5}}" } } } } }, "400": { "description": "- `not_workflow_app` : App mode does not match the API route.\n- `provider_not_initialize` : 未找到有效的模型供应商凭据。\n- `provider_quota_exceeded` : 模型供应商配额已用尽。\n- `model_currently_not_support` : 当前模型不可用。\n- `completion_request_error` : 工作流 execution request failed.\n- `invalid_param` : Invalid parameter value.", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } }, "429": { "description": "- `too_many_requests` : 该应用的并发请求过多。\n- `rate_limit_error` : 上游模型供应商的速率限制已超出。", "content": { "application/json": { "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "status": 429, "code": "too_many_requests", "message": "Too many requests. Please try again later." } }, "rate_limit_error": { "summary": "rate_limit_error", "value": { "status": 429, "code": "rate_limit_error", "message": "Rate Limit Error" } } } } } }, "500": { "description": "`internal_server_error` : 内部服务器错误。", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "Internal Server Error." } } } } } } } } }, "/workflows/{workflow_id}/run": { "post": { "summary": "按 ID 执行工作流", "description": "通过 ID 执行指定的工作流版本。适用于运行工作流的特定已发布版本。", "operationId": "runWorkflowByIdZh", "tags": [ "工作流" ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "description": "要执行的特定版本的工作流 ID。此值在 [执行工作流](/api-reference/工作流/执行工作流) 响应和 [获取工作流运行详情](/api-reference/工作流/获取工作流执行情况) 的 `workflow_id` 字段中返回。", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowExecutionRequest" }, "examples": { "example": { "summary": "请求示例", "value": { "inputs": { "query": "Summarize this article" }, "response_mode": "blocking", "user": "user_workflow_123" } } } } } }, "responses": { "200": { "description": "请求成功。内容类型和结构取决于请求中的 `response_mode` 参数。\n\n- 如果 `response_mode` 为 `blocking`，返回 `application/json` 和 `WorkflowBlockingResponse` 对象。\n- 如果 `response_mode` 为 `streaming`，返回 `text/event-stream` 和 `ChunkWorkflowEvent` 对象流。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowBlockingResponse" }, "examples": { "blockingResponse": { "summary": "响应示例 - 阻塞模式", "value": { "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": { "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", "status": "succeeded", "outputs": { "result": "Article summary here" }, "error": null, "elapsed_time": 2.45, "total_tokens": 280, "total_steps": 4, "created_at": 1705407629, "finished_at": 1705407631 } } } } }, "text/event-stream": { "schema": { "type": "string", "description": "服务器发送事件 (SSE) 流。\n\n**解析**：每行以 `data: ` 开头，后接一个 JSON 对象，以 `\\n\\n` 终止。解析 JSON 前先去除 `data: ` 前缀，再读取 `event` 字段确定事件类型。忽略 `ping` 事件，该事件每 10 秒发送一次以保持连接活跃。\n\n**流生命周期**：收到 `workflow_finished`、`workflow_paused` 或 `error` 事件时流关闭。错误以流内 `error` 事件的形式返回，HTTP 状态码始终为 `200`；请检查事件载荷获取详情，不要依赖状态码判断。\n\n**推理事件**：\n- `reasoning_chunk`：来自 `reasoning_format` 为 `separated` 的 LLM 节点的推理内容增量。拼接连续的 `reasoning_chunk` 事件即可还原完整推理内容；`is_final: true` 的事件标志该节点思考结束（且 `reasoning` 可能为空）。载荷位于 `data` 下，与对话应用不同，不含 `message_id` 或 `conversation_id`。并行的 `text_chunk` 流不含 `` 标签。\n\n**人工介入事件**：\n- `human_input_required`：工作流到达人工介入节点时与 `workflow_paused` 一同触发。使用载荷中的 `form_token` 通过 [人工介入 API](/api-reference/人工介入/获取人工介入表单) 处理表单。\n- `human_input_form_filled`：接收者提交了表单，工作流恢复执行。\n- `human_input_form_timeout`：表单超时未响应。如定义了超时回退分支，工作流将沿该分支执行。" }, "examples": { "streamingResponse": { "summary": "响应示例 - 流式模式", "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Let me translate that.\", \"node_id\": \"node_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}" }, "humanInputPause": { "summary": "响应示例 - 人工介入暂停", "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}} data: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5}}" } } } } }, "400": { "description": "- `not_workflow_app` : App mode does not match the API route.\n- `bad_request` : 工作流 is a draft or has an invalid ID format.\n- `provider_not_initialize` : 未找到有效的模型供应商凭据。\n- `provider_quota_exceeded` : 模型供应商配额已用尽。\n- `model_currently_not_support` : 当前模型不可用。\n- `completion_request_error` : 工作流 execution request failed.\n- `invalid_param` : Required parameter missing or invalid.", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } }, "bad_request": { "summary": "bad_request", "value": { "status": 400, "code": "bad_request", "message": "Workflow is a draft and cannot be executed." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } }, "404": { "description": "`not_found` : 工作流 not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Workflow not found." } } } } } }, "429": { "description": "- `too_many_requests` : 该应用的并发请求过多。\n- `rate_limit_error` : 上游模型供应商的速率限制已超出。", "content": { "application/json": { "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "status": 429, "code": "too_many_requests", "message": "Too many requests. Please try again later." } }, "rate_limit_error": { "summary": "rate_limit_error", "value": { "status": 429, "code": "rate_limit_error", "message": "Rate Limit Error" } } } } } }, "500": { "description": "`internal_server_error` : 内部服务器错误。", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "Internal Server Error." } } } } } } } } }, "/workflows/run/{workflow_run_id}": { "get": { "summary": "获取工作流执行情况", "description": "根据工作流执行 ID 获取工作流任务的当前执行结果。", "operationId": "getWorkflowRunDetailCn", "tags": [ "工作流" ], "parameters": [ { "name": "workflow_run_id", "in": "path", "required": true, "description": "工作流运行 ID，可从工作流执行响应或流式事件中获取。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功获取工作流运行详情。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRunDetailResponse" }, "examples": { "workflowRunDetail": { "summary": "响应示例", "value": { "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", "status": "succeeded", "inputs": "{\"query\": \"Translate this to French\"}", "outputs": { "result": "Traduisez ceci en francais" }, "error": null, "total_steps": 3, "total_tokens": 150, "created_at": 1705407629, "finished_at": 1705407630, "elapsed_time": 1.23 } } } } } }, "400": { "description": "`not_workflow_app` : 应用模式与 API 路由不匹配。", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } } } } } }, "404": { "description": "`not_found` : 未找到工作流运行记录。", "content": { "application/json": { "examples": { "workflow_run_not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Workflow run not found." } } } } } } } } }, "/workflows/logs": { "get": { "summary": "获取工作流日志", "description": "列出过往的工作流运行，支持可选筛选。每条记录是运行级摘要（状态、Token 用量、步数和耗时），而非逐节点的执行日志。\n\n如需跟踪某次运行的节点级事件，请改用流式方式：\n\n- **自行发起的运行**：以流式模式调用 [执行工作流](/api-reference/工作流/执行工作流)，运行执行时会发送 `node_started` 和 `node_finished` 事件。\n- **已在进行中的运行**：调用 [流式获取工作流事件](/api-reference/工作流/流式获取工作流事件) 并附带 `include_state_snapshot=true`，先重放各已执行节点的状态，再流式发送其余事件。\n\n已结束运行的节点级日志无法通过服务 API 获取。", "operationId": "getWorkflowLogsCn", "tags": [ "工作流" ], "parameters": [ { "name": "keyword", "in": "query", "description": "在日志中搜索的关键词。", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "按执行状态筛选。", "schema": { "type": "string", "enum": [ "succeeded", "failed", "stopped" ] } }, { "name": "page", "in": "query", "description": "分页页码。", "schema": { "type": "integer", "default": 1, "minimum": 1, "maximum": 99999 } }, { "name": "limit", "in": "query", "description": "每页条目数。", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "created_at__before", "in": "query", "description": "筛选在此 ISO 8601 时间戳之前创建的日志。", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at__after", "in": "query", "description": "筛选在此 ISO 8601 时间戳之后创建的日志。", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_by_end_user_session_id", "in": "query", "description": "按终端用户会话 ID 筛选。", "schema": { "type": "string" } }, { "name": "created_by_account", "in": "query", "description": "按创建者的账户邮箱筛选（例如 `name@example.com`）。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功获取工作流日志。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowLogsResponse" }, "examples": { "workflowLogs": { "summary": "响应示例", "value": { "page": 1, "limit": 20, "total": 1, "has_more": false, "data": [ { "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", "workflow_run": { "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "version": "2025-01-16 12:00:00.000000", "status": "succeeded", "error": null, "elapsed_time": 1.23, "total_tokens": 150, "total_steps": 3, "created_at": 1705407629, "finished_at": 1705407630, "exceptions_count": 0, "triggered_from": "app-run" }, "created_from": "service-api", "created_by_role": "end_user", "created_by_account": null, "created_by_end_user": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "type": "service_api", "is_anonymous": false, "session_id": "user_workflow_123" }, "created_at": 1705407629 } ] } } } } } } } } }, "/workflows/tasks/{task_id}/stop": { "post": { "summary": "停止工作流任务", "description": "停止正在运行的工作流任务。仅在 `streaming` 模式下支持。", "operationId": "stopWorkflowTaskGenerationCn", "tags": [ "工作流" ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "任务 ID，可以从 [执行工作流](/api-reference/工作流/执行工作流) API 的流式分块返回中获取。", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "string", "description": "用户标识符，仅用于标识请求的终端用户，无需与 [执行工作流](/api-reference/工作流/执行工作流) 请求传入的 `user` 一致；停止对该任务始终生效。" } } }, "examples": { "example": { "summary": "请求示例", "value": { "user": "user_workflow_123" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResult" }, "400": { "description": "- `not_workflow_app` : 应用模式与 API 路由不匹配。\n- `invalid_param` : 必要参数缺失或无效。", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } } } } }, "/files/upload": { "post": { "operationId": "uploadWorkflowFileCn", "tags": [ "文件操作" ], "summary": "上传文件", "description": "上传文件用于发送消息时使用，支持图片、文档、音频和视频的多模态理解。上传的文件仅供当前终端用户使用。", "requestBody": { "description": "文件上传请求。需要 multipart/form-data 格式。", "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "要上传的文件。支持的类型包括图片、文档、音频和视频。" }, "user": { "type": "string", "description": "用户标识符，由开发者定义的规则生成，必须在应用内唯一。Service API 与 WebApp 的用户 ID 相互独立，即使取值相同也不指向同一用户。省略时，上传会归属到共享的 `DEFAULT-USER` 终端用户；后续请求只有携带与上传时相同的 `user` 值才能使用该文件。" } } } } } }, "responses": { "201": { "description": "文件上传成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponse" }, "examples": { "uploadSuccess": { "summary": "响应示例", "value": { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "name": "product-photo.png", "size": 204800, "extension": "png", "mime_type": "image/png", "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "created_at": 1705407629, "preview_url": null, "source_url": "https://upload.dify.ai/files/a1b2c3d4-5678-90ab-cdef-1234567890ab/file-preview?timestamp=1705407629&nonce=8b3e26a5&sign=rN5DXW3xkVGwGE5MSvptu_BhQVXpMbXWmVJ0ib0LMzI=", "original_url": null, "user_id": null, "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", "conversation_id": null, "file_key": null } } } } } }, "400": { "description": "- `no_file_uploaded` : 请求中未提供文件。\n- `too_many_files` : 每次请求仅允许上传一个文件。\n- `filename_not_exists_error` : 上传的文件没有文件名。\n- `invalid_param` : 文件名包含非法字符（`/` 或 `\\`）。", "content": { "application/json": { "examples": { "no_file_uploaded": { "summary": "no_file_uploaded", "value": { "status": 400, "code": "no_file_uploaded", "message": "Please upload your file." } }, "too_many_files": { "summary": "too_many_files", "value": { "status": 400, "code": "too_many_files", "message": "Only one file is allowed." } }, "filename_not_exists_error": { "summary": "filename_not_exists_error", "value": { "status": 400, "code": "filename_not_exists_error", "message": "The specified filename does not exist." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Filename contains invalid characters" } } } } } }, "413": { "description": "`file_too_large` : 文件大小超出限制。", "content": { "application/json": { "examples": { "file_too_large": { "summary": "file_too_large", "value": { "status": 413, "code": "file_too_large", "message": "File size exceeded." } } } } } }, "415": { "description": "`unsupported_file_type` : 不允许的文件类型。", "content": { "application/json": { "examples": { "unsupported_file_type": { "summary": "unsupported_file_type", "value": { "status": 415, "code": "unsupported_file_type", "message": "File type not allowed." } } } } } } } } }, "/end-users/{end_user_id}": { "get": { "operationId": "getEndUserWorkflowCn", "tags": [ "终端用户" ], "summary": "获取终端用户信息", "description": "根据 ID 获取终端用户信息。当其他 API 返回终端用户 ID（例如[上传文件](/api-reference/文件操作/上传文件)返回的 `created_by`）时很有用。", "parameters": [ { "name": "end_user_id", "in": "path", "required": true, "description": "终端用户 ID。", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功获取终端用户。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndUserDetail" }, "examples": { "endUserDetail": { "summary": "响应示例", "value": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "type": "service_api", "external_user_id": "abc-123", "name": null, "is_anonymous": false, "session_id": "abc-123", "created_at": "2024-01-16T12:00:29Z", "updated_at": "2024-01-16T12:00:29Z" } } } } } }, "404": { "description": "`end_user_not_found` : 未找到终端用户。", "content": { "application/json": { "examples": { "end_user_not_found": { "summary": "end_user_not_found", "value": { "status": 404, "code": "end_user_not_found", "message": "End user not found." } } } } } } } } }, "/audio-to-text": { "post": { "operationId": "workflowAudioToTextZh", "tags": [ "语音与文字转换" ], "summary": "语音转文字", "description": "将音频文件转换为文字。按上传文件的 MIME 类型校验，必须为 `audio/mp3`、`audio/m4a`、`audio/wav`、`audio/amr`、`audio/mpga` 之一；其他类型（包括常见的 `audio/mpeg`）会返回 `unsupported_audio_type` 错误。文件大小限制为 `30 MB`。", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AudioToTextRequest" } } } }, "responses": { "200": { "description": "语音转文字成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioToTextResponse" }, "examples": { "audioToTextSuccess": { "summary": "响应示例", "value": { "text": "Hello, I would like to know more about the iPhone 13 Pro Max." } } } } } }, "400": { "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `no_audio_uploaded` : 未上传音频文件。\n- `provider_not_support_speech_to_text` : 模型供应商不支持语音转文字。\n- `provider_not_initialize` : 未找到有效的模型供应商凭据。\n- `provider_quota_exceeded` : 模型供应商配额已用尽。\n- `model_currently_not_support` : 当前模型不支持此操作。\n- `completion_request_error` : 语音识别请求失败。", "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "status": 400, "code": "app_unavailable", "message": "App unavailable, please check your app configurations." } }, "no_audio_uploaded": { "summary": "no_audio_uploaded", "value": { "status": 400, "code": "no_audio_uploaded", "message": "Please upload your audio." } }, "provider_not_support_speech_to_text": { "summary": "provider_not_support_speech_to_text", "value": { "status": 400, "code": "provider_not_support_speech_to_text", "message": "Provider not support speech to text." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } } } } } }, "413": { "description": "`audio_too_large` : 音频文件大小超出限制。", "content": { "application/json": { "examples": { "audio_too_large": { "summary": "audio_too_large", "value": { "status": 413, "code": "audio_too_large", "message": "Audio size exceeded." } } } } } }, "415": { "description": "`unsupported_audio_type` : 不允许的音频类型。", "content": { "application/json": { "examples": { "unsupported_audio_type": { "summary": "unsupported_audio_type", "value": { "status": 415, "code": "unsupported_audio_type", "message": "Audio type not allowed." } } } } } }, "500": { "description": "`internal_server_error` : 内部服务器错误。", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "Internal server error." } } } } } } } } }, "/text-to-audio": { "post": { "operationId": "workflowTextToAudioZh", "tags": [ "语音与文字转换" ], "summary": "文字转语音", "description": "将文字转换为语音。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextToAudioRequest" }, "examples": { "textToAudioExample": { "summary": "请求示例", "value": { "text": "Hello, welcome to our service.", "user": "abc-123", "voice": "alloy", "streaming": false } } } } } }, "responses": { "200": { "description": "返回生成的音频文件。`Content-Type` 头设置为音频 MIME 类型（例如 `audio/wav`、`audio/mp3`）。如果 `streaming` 为 `true`，音频将以分块传输编码方式流式返回。", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `provider_not_initialize` : 未找到有效的模型供应商凭据。\n- `provider_quota_exceeded` : 模型供应商配额已用尽。\n- `model_currently_not_support` : 当前模型不支持此操作。\n- `completion_request_error` : 文字转语音请求失败。", "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "status": 400, "code": "app_unavailable", "message": "App unavailable, please check your app configurations." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } } } } } }, "500": { "description": "`internal_server_error` : 内部服务器错误。", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "Internal server error." } } } } } } } } }, "/info": { "get": { "operationId": "getWorkflowAppInfoCn", "tags": [ "应用配置" ], "summary": "获取应用基本信息", "description": "获取应用的基本信息，包括名称、描述、标签和模式。", "responses": { "200": { "description": "应用的基本信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponse" }, "examples": { "appInfo": { "summary": "响应示例", "value": { "name": "My Workflow App", "description": "一个有用的客服聊天机器人。", "tags": [ "customer-service", "chatbot" ], "mode": "workflow", "author_name": "Dify Team" } } } } } } } } }, "/parameters": { "get": { "operationId": "getWorkflowAppParametersCn", "tags": [ "应用配置" ], "summary": "获取应用参数", "description": "获取应用的输入表单配置，包括功能开关、输入参数名称、类型和默认值。", "responses": { "200": { "description": "应用参数信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowAppParametersResponse" }, "examples": { "appParameters": { "summary": "响应示例", "value": { "opening_statement": "Hello! How can I help you today?", "suggested_questions": [ "What can you do?", "Tell me about your features." ], "suggested_questions_after_answer": { "enabled": true }, "speech_to_text": { "enabled": false }, "text_to_speech": { "enabled": false, "voice": "alloy", "language": "en-US", "autoPlay": "disabled" }, "retriever_resource": { "enabled": true }, "annotation_reply": { "enabled": false }, "more_like_this": { "enabled": false }, "sensitive_word_avoidance": { "enabled": false }, "user_input_form": [ { "text-input": { "label": "City", "variable": "city", "required": true, "default": "" } } ], "file_upload": { "image": { "enabled": true, "number_limits": 3, "detail": "high", "transfer_methods": [ "remote_url", "local_file" ] } }, "system_parameters": { "file_size_limit": 15, "image_file_size_limit": 10, "audio_file_size_limit": 50, "video_file_size_limit": 100, "workflow_file_upload_limit": 10 } } } } } } }, "400": { "description": "`app_unavailable` : 应用不可用或配置错误。", "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "status": 400, "code": "app_unavailable", "message": "App unavailable, please check your app configurations." } } } } } } } } }, "/meta": { "get": { "operationId": "getWorkflowAppMetaZh", "tags": [ "应用配置" ], "summary": "获取应用元数据", "description": "获取应用的元数据，包括工具图标和其他配置详情。", "responses": { "200": { "description": "成功获取应用元数据。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppMetaResponse" }, "examples": { "appMeta": { "summary": "响应示例", "value": { "tool_icons": { "dalle3": "https://example.com/icons/dalle3.png", "calculator": { "background": "#4A90D9", "content": "🧮" } } } } } } } } } } }, "/site": { "get": { "operationId": "getWorkflowWebAppSettingsCn", "tags": [ "应用配置" ], "summary": "获取应用 WebApp 设置", "description": "获取应用的 WebApp 设置，包括站点配置、主题和自定义选项。", "responses": { "200": { "description": "应用的 WebApp 设置。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAppSettingsResponse" }, "examples": { "webAppSettings": { "summary": "响应示例", "value": { "title": "My Chat App", "chat_color_theme": "#4A90D9", "chat_color_theme_inverted": false, "icon_type": "emoji", "icon": "🤖", "icon_background": "#FFFFFF", "icon_url": null, "description": "一个有用的客服聊天机器人。", "copyright": "2025 Dify", "privacy_policy": "https://example.com/privacy", "custom_disclaimer": "", "default_language": "en-US", "show_workflow_steps": false, "use_icon_as_answer_icon": true } } } } } }, "403": { "description": "`forbidden` : 未找到此应用的站点或工作空间已归档。", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden", "value": { "status": 403, "code": "forbidden", "message": "Forbidden." } } } } } } } } }, "/form/human_input/{form_token}": { "get": { "tags": [ "人工介入" ], "summary": "获取人工介入表单", "description": "获取暂停中的人工介入表单内容。需要 WebApp 提交方式。\n\n调用人工介入接口的端到端流程，参见 [API 集成流程](/zh/api-reference/guides/human-input-flow)。", "operationId": "getWorkflowHumanInputForm", "parameters": [ { "name": "form_token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "暂停表单的访问令牌，由流式模式下执行工作流或发送对话消息接口返回的 `human_input_required` 事件提供。" } ], "responses": { "200": { "description": "表单内容获取成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "form_content": { "type": "string", "description": "已替换工作流变量的预渲染表单正文。" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "表单输入控件类型。可用值：`paragraph`（多行文本输入）、`select`（从列表中单选）、`file`（单个文件上传）和 `file-list`（多个文件上传）。" }, "output_variable_name": { "type": "string", "description": "引用该输入提交值在工作流中使用的变量名。对应提交 `inputs` 对象中的键。" }, "default": { "type": "object", "nullable": true, "description": "`paragraph` 输入的原始默认值配置。客户端不应直接解析此字段，请使用 `resolved_default_values` 来展示默认值。其他输入类型或未配置默认值时为 `null`。", "properties": { "type": { "type": "string", "description": "默认值来源。`constant` 表示将 `value` 作为字面字符串；`variable` 表示 `selector` 指向工作流变量。" }, "selector": { "type": "array", "items": { "type": "string" }, "description": "当 `type` 为 `variable` 时的变量引用路径（例如 `[\"node_id\", \"var_name\"]`）。至少包含两个元素。" }, "value": { "type": "string", "description": "当 `type` 为 `constant` 时的字面默认值。始终为字符串。" } } }, "option_source": { "type": "object", "description": "`select` 输入的选项来源。仅当 `type` 为 `select` 时出现。", "properties": { "type": { "type": "string", "enum": [ "variable", "constant" ], "description": "选项来源。`constant` 表示 `value` 直接列出选项；`variable` 表示 `selector` 指向提供选项的 `array[string]` 工作流变量。" }, "selector": { "type": "array", "items": { "type": "string" }, "description": "当 `type` 为 `variable` 时的变量引用路径。" }, "value": { "type": "array", "items": { "type": "string" }, "description": "当 `type` 为 `constant` 时的字面选项列表。" } } }, "allowed_file_types": { "type": "array", "items": { "type": "string", "enum": [ "image", "document", "audio", "video", "custom" ] }, "description": "接收人可上传的文件类别。`file` 和 `file-list` 输入会包含此字段。可用值：`image`、`document`、`audio`、`video`、`custom`。" }, "allowed_file_extensions": { "type": "array", "items": { "type": "string" }, "description": "当 `allowed_file_types` 包含 `custom` 时允许的文件扩展名。每个扩展名都需要包含前导 `.`，例如 `.md`。`file` 和 `file-list` 输入会包含此字段。" }, "allowed_file_upload_methods": { "type": "array", "items": { "type": "string", "enum": [ "local_file", "remote_url" ] }, "description": "接收人可使用的上传方式。可用值：`local_file`、`remote_url`。`file` 和 `file-list` 输入会包含此字段。" }, "number_limits": { "type": "integer", "description": "接收人可上传的最大文件数。仅 `file-list` 输入会包含此字段。" } } }, "description": "表单输入字段定义。" }, "resolved_default_values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "用于在表单中展示的预渲染默认值，按输入的 `output_variable_name` 分组。仅当 `paragraph` 输入的默认值可由工作流变量解析时填充；无可解析默认值的输入为空。客户端请直接展示这些值，无需在前端再次解析 `default`。所有值均为字符串。" }, "user_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 20, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "操作按钮的标识。当接收人选择该按钮时，作为 `action` 传入 [提交人工介入表单](/api-reference/人工介入/提交人工介入表单)。" }, "title": { "type": "string", "maxLength": 100, "description": "显示给接收人的按钮文本。" }, "button_style": { "type": "string", "description": "按钮的视觉样式。可用值：`primary`、`default`、`accent`、`ghost`。" } } }, "description": "可用的提交操作。" }, "expiration_time": { "type": "integer", "format": "int64", "description": "Unix 时间戳（秒），超过该时间后表单将不可提交。", "nullable": true } } }, "examples": { "success": { "summary": "响应示例", "value": { "form_content": "Please review the draft, set a priority, and confirm or request changes.", "inputs": [ { "type": "paragraph", "output_variable_name": "feedback", "default": { "type": "constant", "selector": [], "value": "" } }, { "type": "select", "output_variable_name": "priority", "option_source": { "type": "constant", "selector": [], "value": [ "low", "medium", "high" ] } }, { "type": "file", "output_variable_name": "attachment", "allowed_file_types": [ "image", "document" ], "allowed_file_extensions": [], "allowed_file_upload_methods": [ "local_file", "remote_url" ] }, { "type": "file-list", "output_variable_name": "attachments", "allowed_file_types": [ "image", "document" ], "allowed_file_extensions": [], "allowed_file_upload_methods": [ "local_file", "remote_url" ], "number_limits": 5 } ], "resolved_default_values": { "feedback": "" }, "user_actions": [ { "id": "approve", "title": "Approve", "button_style": "primary" }, { "id": "reject", "title": "Request changes", "button_style": "default" } ], "expiration_time": 1745510400 } } } } } }, "404": { "description": "`not_found`：未找到表单。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "未找到表单" } } } } } }, "412": { "description": "- `human_input_form_submitted`：表单已被提交。表单为一次性使用；无论由哪位用户提交，首个响应即生效。\n- `human_input_form_expired`：在提交到达之前表单已过期。", "content": { "application/json": { "examples": { "human_input_form_submitted": { "summary": "human_input_form_submitted", "value": { "status": 412, "code": "human_input_form_submitted", "message": "该表单已被其他用户提交，form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, "human_input_form_expired": { "summary": "human_input_form_expired", "value": { "status": 412, "code": "human_input_form_expired", "message": "该表单已过期，form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } } } }, "post": { "tags": [ "人工介入" ], "summary": "提交人工介入表单", "description": "向暂停中的人工介入表单提交接收人的响应。接受后工作流将继续；可通过订阅工作流事件接口跟踪后续事件。需要 WebApp 提交方式。", "operationId": "submitWorkflowHumanInputForm", "parameters": [ { "name": "form_token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "暂停表单的访问令牌，由流式模式下执行工作流或发送对话消息接口返回的 `human_input_required` 事件提供。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "inputs", "action", "user" ], "properties": { "inputs": { "type": "object", "additionalProperties": true, "description": "按各输入的 `output_variable_name` 作为键提交的值。段落和下拉选项输入为字符串；`file` 输入为单个文件映射；`file-list` 输入为文件映射数组。文件映射为 `{transfer_method: local_file, upload_file_id, type}` 或 `{transfer_method: remote_url, url, type}`，其中 `type` 为该字段 `allowed_file_types` 中的一种（`image`、`document`、`audio`、`video`、`custom`）。对于 `local_file`，`upload_file_id` 为 [上传文件](/api-reference/文件操作/上传文件) 返回的 `id`。请在执行、上传和提交各次调用中使用一致的 `user`。" }, "action": { "type": "string", "description": "接收人选择的操作按钮 ID。必须与表单的 `user_actions` 列表（由 [获取人工介入表单](/api-reference/人工介入/获取人工介入表单) 接口返回）中的某个 `id` 值匹配。" }, "user": { "type": "string", "description": "用户标识符，由开发者定义的规则生成，必须在应用内唯一。Service API 与 WebApp 的用户 ID 相互独立，即使取值相同也不指向同一用户。" } } }, "examples": { "approve": { "summary": "请求示例", "value": { "inputs": { "feedback": "可以发布", "priority": "high", "attachment": { "transfer_method": "local_file", "upload_file_id": "3c8fa1b2-7d4e-4f9a-b0c1-d2e3f4a5b6c7", "type": "image" }, "attachments": [ { "transfer_method": "local_file", "upload_file_id": "1a77f0df-c0e6-461c-987c-e72526f341ee", "type": "document" }, { "transfer_method": "remote_url", "url": "https://example.com/report.pdf", "type": "document" } ] }, "action": "approve", "user": "abc-123" } } } } } }, "responses": { "200": { "description": "表单提交成功。响应体为空对象。", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "success": { "summary": "响应示例", "value": {} } } } } }, "400": { "description": "- `bad_request`：表单接收人类型无效。\n- `invalid_form_data`：提交内容未通过表单定义的校验。", "content": { "application/json": { "examples": { "bad_request": { "summary": "bad_request", "value": { "status": 400, "code": "bad_request", "message": "表单接收人类型无效" } }, "invalid_form_data": { "summary": "invalid_form_data", "value": { "status": 400, "code": "invalid_form_data", "message": "缺少必填输入：feedback" } } } } } }, "404": { "description": "`not_found`：未找到表单。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "未找到表单" } } } } } }, "412": { "description": "- `human_input_form_submitted`：表单已被提交。表单为一次性使用；无论由哪位用户提交，首个响应即生效。\n- `human_input_form_expired`：在提交到达之前表单已过期。", "content": { "application/json": { "examples": { "human_input_form_submitted": { "summary": "human_input_form_submitted", "value": { "status": 412, "code": "human_input_form_submitted", "message": "该表单已被其他用户提交，form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, "human_input_form_expired": { "summary": "human_input_form_expired", "value": { "status": 412, "code": "human_input_form_expired", "message": "该表单已过期，form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } } } } }, "/workflow/{workflow_run_id}/events": { "get": { "tags": [ "工作流" ], "summary": "流式获取工作流事件", "description": "在工作流运行暂停或原始 SSE 连接断开后恢复 Server-Sent Events 流。对于已结束的运行，流仅发送单个 `workflow_finished` 事件后关闭。\n\n如需查看进行中运行的节点级状态与进度，可在调用时附带 `include_state_snapshot=true`：流会先重放各已执行节点的状态，再流式发送新事件。", "operationId": "streamWorkflowEvents", "parameters": [ { "name": "workflow_run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "要恢复事件流的工作流运行 ID（取自原始运行响应中的 `workflow_run_id`）。" }, { "name": "user", "in": "query", "required": true, "schema": { "type": "string" }, "description": "最初触发该运行的终端用户标识。必须与工作流运行的创建者一致。" }, { "name": "include_state_snapshot", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "为 `true` 时，从持久化状态快照重放，在流式发送新事件前附带已执行节点的状态摘要。" }, { "name": "continue_on_pause", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "设为 `true` 时，流会在多次 `workflow_paused` 事件之间保持打开（适用于工作流包含多个连续人工介入节点的场景）。默认在首次暂停时关闭流。" } ], "responses": { "200": { "description": "Server-Sent Events 流。每个事件以 `data: {JSON}\\n\\n` 形式送达。事件载荷结构与原始流式响应一致。", "content": { "text/event-stream": { "schema": { "type": "string", "description": "已恢复工作流运行的事件 SSE 流，格式与 [执行工作流](/api-reference/工作流/执行工作流) 相同。当恢复部分运行设置 `reasoning_format: separated` 的 LLM 节点时，本流还会携带 `reasoning_chunk` 事件。" }, "examples": { "resumedRun": { "summary": "响应示例 - 恢复运行", "value": "data: {\"event\": \"human_input_form_filled\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"rendered_content\": \"Please review the draft.\", \"action_id\": \"approve\", \"action_text\": \"Approve\"}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_2\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 2, \"created_at\": 1705407705}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Approved, now translating.\", \"node_id\": \"node_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour\"}, \"elapsed_time\": 2.1, \"total_tokens\": 42, \"total_steps\": 2, \"created_at\": 1705407629, \"finished_at\": 1705407706}}" } } } } }, "400": { "description": "`not_workflow_app` : Please check if your app mode matches the right API route.", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } } } } } }, "404": { "description": "`not_found` : Workflow run not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Workflow run not found" } } } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "恢复事件流", "source": "curl -N --request GET \\\n --url 'https://{api_base_url}/workflow/{workflow_run_id}/events?user={user}' \\\n --header 'Authorization: Bearer {api_key}'" }, { "lang": "bash", "label": "附带状态快照", "source": "curl -N --request GET \\\n --url 'https://{api_base_url}/workflow/{workflow_run_id}/events?user={user}&include_state_snapshot=true' \\\n --header 'Authorization: Bearer {api_key}'" } ] } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "API Key 认证。对于所有 API 请求，请在 `Authorization` HTTP 头中包含您的 API Key，并加上 `Bearer ` 前缀。示例：`Authorization: Bearer {API_KEY}`。**强烈建议将 API Key 存储在服务端，不要在客户端共享或存储，以避免 API Key 泄漏导致严重后果。**缺少或无效的 API Key 会返回 HTTP `401`，错误码为 `unauthorized`。" } }, "responses": { "SuccessResult": { "description": "操作成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "enum": [ "success" ], "description": "操作结果。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "result": "success" } } } } } } }, "schemas": { "WorkflowExecutionRequest": { "type": "object", "required": [ "inputs", "user" ], "properties": { "inputs": { "type": "object", "description": "工作流输入变量的键值对。文件类型变量的值应为文件对象数组，包含 `type`、`transfer_method` 以及 `url` 或 `upload_file_id`。请参阅 [获取应用参数](/api-reference/应用配置/获取应用参数) 响应中的 `user_input_form` 字段，以了解应用所需的变量名称和类型。", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObject" } } ] } }, "response_mode": { "type": "string", "enum": [ "streaming", "blocking" ], "description": "响应模式。使用 `blocking` 获取同步响应（Cloudflare 超时时间为 `100 s`），使用 `streaming` 获取服务器发送事件。未指定时默认为阻塞模式。" }, "user": { "type": "string", "description": "用户标识符，由开发者自定义规则，在应用内必须唯一。此标识符用于限定数据访问范围——工作流运行和文件仅在使用相同的 `user` 值查询时可见。" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObject" }, "nullable": true, "description": "文件列表。适用于需要将文件与文本组合输入的场景，仅在模型支持 Vision 能力时可用。要附加本地文件，请先通过 [上传文件](/api-reference/文件操作/上传文件) 上传，然后将返回的 `id` 作为 `upload_file_id`，并设置 `transfer_method: local_file`。" } } }, "InputFileObject": { "type": "object", "required": [ "type", "transfer_method" ], "properties": { "type": { "type": "string", "enum": [ "document", "image", "audio", "video", "custom" ], "description": "文件类型。" }, "transfer_method": { "type": "string", "enum": [ "remote_url", "local_file" ], "description": "传输方式：文件 URL 使用 `remote_url`，上传文件使用 `local_file`。" }, "url": { "type": "string", "format": "url", "description": "文件 URL（当 `transfer_method` 为 `remote_url` 时）。" }, "upload_file_id": { "type": "string", "description": "通过 [上传文件](/api-reference/文件操作/上传文件) API 获取的已上传文件 ID（当 `transfer_method` 为 `local_file` 时使用）。" } } }, "WorkflowBlockingResponse": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "description": "进行中的执行任务 ID。配合 [停止工作流任务](/api-reference/工作流/停止工作流任务) 使用以取消运行中的工作流。仅在执行期间有效。" }, "workflow_run_id": { "type": "string", "format": "uuid", "description": "此工作流运行记录的持久化标识符。配合 [获取工作流运行详情](/api-reference/工作流/获取工作流执行情况) 使用以在执行后获取结果。" }, "data": { "$ref": "#/components/schemas/WorkflowFinishedData" } } }, "ChunkWorkflowEvent": { "type": "object", "required": [ "event" ], "properties": { "event": { "type": "string", "enum": [ "workflow_started", "node_started", "node_finished", "node_retry", "iteration_started", "iteration_next", "iteration_completed", "loop_started", "loop_next", "loop_completed", "reasoning_chunk", "text_chunk", "workflow_finished", "tts_message", "tts_message_end", "workflow_paused", "agent_log", "human_input_required", "human_input_form_filled", "human_input_form_timeout", "error", "ping" ], "description": "流式事件的类型。" } }, "discriminator": { "propertyName": "event", "mapping": { "workflow_started": "#/components/schemas/StreamEventWorkflowStarted", "node_started": "#/components/schemas/StreamEventNodeStarted", "node_finished": "#/components/schemas/StreamEventNodeFinished", "node_retry": "#/components/schemas/StreamEventNodeRetry", "iteration_started": "#/components/schemas/StreamEventIterationStarted", "iteration_next": "#/components/schemas/StreamEventIterationNext", "iteration_completed": "#/components/schemas/StreamEventIterationCompleted", "loop_started": "#/components/schemas/StreamEventLoopStarted", "loop_next": "#/components/schemas/StreamEventLoopNext", "loop_completed": "#/components/schemas/StreamEventLoopCompleted", "reasoning_chunk": "#/components/schemas/StreamEventReasoningChunk", "text_chunk": "#/components/schemas/StreamEventTextChunk", "workflow_finished": "#/components/schemas/StreamEventWorkflowFinished", "tts_message": "#/components/schemas/StreamEventTtsMessage", "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd", "error": "#/components/schemas/StreamEventError", "ping": "#/components/schemas/StreamEventPing", "workflow_paused": "#/components/schemas/StreamEventWorkflowPaused", "agent_log": "#/components/schemas/StreamEventAgentLog", "human_input_required": "#/components/schemas/StreamEventHumanInputRequired", "human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled", "human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout" } } }, "StreamEventBase": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "description": "进行中的执行任务 ID。配合 [停止工作流任务](/api-reference/工作流/停止工作流任务) 使用以取消运行中的工作流。仅在执行期间有效。" }, "workflow_run_id": { "type": "string", "format": "uuid", "description": "此工作流运行记录的持久化标识符。配合 [获取工作流运行详情](/api-reference/工作流/获取工作流执行情况) 使用以在执行后获取结果。" } } }, "StreamEventWorkflowStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "工作流运行 ID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "工作流 ID." }, "inputs": { "type": "object", "additionalProperties": true, "description": "本次工作流运行的输入变量。" }, "created_at": { "type": "integer", "format": "int64", "description": "工作流运行开始时的 Unix 时间戳。" }, "reason": { "type": "string", "description": "工作流启动原因。`initial` 表示新执行，`resumption` 表示从暂停状态恢复。" } } } } } ] }, "StreamEventNodeStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "节点执行 ID。" }, "node_id": { "type": "string", "description": "工作流图中的节点 ID。" }, "node_type": { "type": "string", "description": "节点类型（例如 `llm`、`code`、`template-transform`）。" }, "title": { "type": "string", "description": "节点的显示名称。" }, "index": { "type": "integer", "description": "执行序列索引。" }, "predecessor_node_id": { "type": "string", "nullable": true, "description": "前驱节点的 ID（如有）。" }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "该节点的输入变量。" }, "inputs_truncated": { "type": "boolean", "description": "`inputs` 数据是否被截断。" }, "created_at": { "type": "integer", "format": "int64", "description": "节点执行开始时的 Unix 时间戳。" }, "extras": { "type": "object", "additionalProperties": true, "description": "节点执行的附加元数据。" }, "iteration_id": { "type": "string", "nullable": true, "description": "如果该节点在迭代内运行，则为父迭代 ID。" }, "loop_id": { "type": "string", "nullable": true, "description": "如果该节点在循环内运行，则为父循环 ID。" } } } } } ] }, "StreamEventNodeFinished": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "节点执行 ID。" }, "node_id": { "type": "string", "description": "工作流图中的节点 ID。" }, "node_type": { "type": "string", "description": "Node type." }, "title": { "type": "string", "description": "节点的显示名称。" }, "index": { "type": "integer", "description": "执行序列索引。" }, "predecessor_node_id": { "type": "string", "nullable": true, "description": "前驱节点的 ID（如有）。" }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "该节点的输入变量。" }, "inputs_truncated": { "type": "boolean", "description": "`inputs` 数据是否被截断。" }, "process_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "节点执行期间生成的处理数据。" }, "process_data_truncated": { "type": "boolean", "description": "`process_data` 是否被截断。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "节点的输出数据。" }, "outputs_truncated": { "type": "boolean", "description": "`outputs` 数据是否被截断。" }, "status": { "type": "string", "description": "节点执行状态。`running` 表示进行中，`succeeded` 表示已完成，`failed` 表示出错，`stopped` 表示手动停止，`exception` 表示意外失败。" }, "error": { "type": "string", "nullable": true, "description": "节点失败时的错误消息。" }, "elapsed_time": { "type": "number", "format": "float", "description": "耗时（秒）。" }, "execution_metadata": { "type": "object", "nullable": true, "description": "执行元数据，包含令牌用量。", "properties": { "total_tokens": { "type": "integer", "nullable": true, "description": "该节点消耗的总令牌数。" }, "total_price": { "type": "number", "format": "float", "nullable": true, "description": "该节点执行的总费用。" }, "currency": { "type": "string", "nullable": true, "description": "费用货币（例如 `USD`）。" } } }, "created_at": { "type": "integer", "format": "int64", "description": "节点执行开始时的 Unix 时间戳。" }, "finished_at": { "type": "integer", "format": "int64", "description": "节点执行结束时的 Unix 时间戳。" }, "files": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true }, "description": "该节点生成的文件。" }, "iteration_id": { "type": "string", "nullable": true, "description": "如果该节点在迭代内运行，则为父迭代 ID。" }, "loop_id": { "type": "string", "nullable": true, "description": "如果该节点在循环内运行，则为父循环 ID。" } } } } } ] }, "StreamEventNodeRetry": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "节点执行 ID。" }, "node_id": { "type": "string", "description": "工作流图中的节点 ID。" }, "node_type": { "type": "string", "description": "Node type." }, "title": { "type": "string", "description": "节点的显示名称。" }, "index": { "type": "integer", "description": "执行序列索引。" }, "predecessor_node_id": { "type": "string", "nullable": true, "description": "前驱节点的 ID（如有）。" }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true }, "inputs_truncated": { "type": "boolean", "description": "`inputs` 数据是否被截断。" }, "process_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "节点执行期间生成的处理数据。" }, "process_data_truncated": { "type": "boolean", "description": "`process_data` 是否被截断。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true }, "outputs_truncated": { "type": "boolean", "description": "`outputs` 数据是否被截断。" }, "status": { "type": "string", "description": "重试点的节点执行状态。" }, "error": { "type": "string", "nullable": true, "description": "触发重试的错误消息。" }, "elapsed_time": { "type": "number", "format": "float", "description": "耗时（秒）。" }, "created_at": { "type": "integer", "format": "int64" }, "finished_at": { "type": "integer", "format": "int64" }, "retry_index": { "type": "integer", "description": "从零开始的重试次数索引。" }, "iteration_id": { "type": "string", "nullable": true }, "loop_id": { "type": "string", "nullable": true }, "execution_metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "节点执行的元数据。" }, "files": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "节点在执行期间生成的文件。" } } } } } ] }, "StreamEventIterationStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "节点执行 ID。" }, "node_id": { "type": "string", "description": "迭代节点 ID。" }, "node_type": { "type": "string", "description": "节点类型（始终为 `iteration`）。" }, "title": { "type": "string", "description": "迭代节点的显示名称。" }, "created_at": { "type": "integer", "format": "int64" }, "inputs": { "type": "object", "additionalProperties": true, "description": "迭代的输入变量。" }, "inputs_truncated": { "type": "boolean", "description": "`inputs` 数据是否被截断。" }, "metadata": { "type": "object", "additionalProperties": true, "description": "迭代元数据。" }, "extras": { "type": "object", "additionalProperties": true } } } } } ] }, "StreamEventIterationNext": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "index": { "type": "integer", "description": "当前迭代索引（从零开始）。" }, "created_at": { "type": "integer", "format": "int64" }, "extras": { "type": "object", "additionalProperties": true } } } } } ] }, "StreamEventIterationCompleted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true }, "outputs_truncated": { "type": "boolean", "description": "`outputs` 数据是否被截断。" }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "迭代的输入变量。" }, "inputs_truncated": { "type": "boolean", "description": "`inputs` 数据是否被截断。" }, "created_at": { "type": "integer", "format": "int64", "description": "迭代开始时的 Unix 时间戳。" }, "extras": { "type": "object", "additionalProperties": true, "nullable": true, "description": "迭代的附加元数据。" }, "status": { "type": "string", "description": "迭代完成状态。" }, "error": { "type": "string", "nullable": true }, "elapsed_time": { "type": "number", "format": "float" }, "total_tokens": { "type": "integer" }, "execution_metadata": { "type": "object", "additionalProperties": true, "description": "执行元数据，包含令牌用量。" }, "finished_at": { "type": "integer", "format": "int64" }, "steps": { "type": "integer", "description": "已完成的迭代步数。" } } } } } ] }, "StreamEventLoopStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "created_at": { "type": "integer", "format": "int64" }, "inputs": { "type": "object", "additionalProperties": true }, "inputs_truncated": { "type": "boolean", "description": "`inputs` 数据是否被截断。" }, "metadata": { "type": "object", "additionalProperties": true }, "extras": { "type": "object", "additionalProperties": true } } } } } ] }, "StreamEventLoopNext": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "index": { "type": "integer", "description": "当前循环迭代索引（从零开始）。" }, "created_at": { "type": "integer", "format": "int64" }, "pre_loop_output": { "description": "上一次循环迭代的输出。", "nullable": true }, "extras": { "type": "object", "additionalProperties": true } } } } } ] }, "StreamEventLoopCompleted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true }, "outputs_truncated": { "type": "boolean", "description": "`outputs` 数据是否被截断。" }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "循环的输入变量。" }, "inputs_truncated": { "type": "boolean", "description": "`inputs` 数据是否被截断。" }, "created_at": { "type": "integer", "format": "int64" }, "extras": { "type": "object", "additionalProperties": true, "nullable": true, "description": "循环的附加元数据。" }, "status": { "type": "string", "description": "循环完成状态。" }, "error": { "type": "string", "nullable": true }, "elapsed_time": { "type": "number", "format": "float" }, "total_tokens": { "type": "integer" }, "execution_metadata": { "type": "object", "additionalProperties": true, "description": "执行元数据，包含令牌用量。" }, "finished_at": { "type": "integer", "format": "int64" }, "steps": { "type": "integer", "description": "已完成的循环迭代次数。" } } } } } ] }, "StreamEventReasoningChunk": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "由 `reasoning_format` 为 `separated` 的 LLM 节点发送的推理内容增量。拼接连续的 `reasoning_chunk` 事件即可还原完整推理内容。本流与 `text_chunk` 并行；`text` 流不含 `` 标签。" }, "node_id": { "type": "string", "nullable": true, "description": "产生该推理内容的 LLM 节点 ID。当多个 LLM 节点运行时，可据此归属推理内容。" }, "is_final": { "type": "boolean", "description": "`true` 标志 LLM 节点推理阶段结束（即「思考完成」信号）；该事件的 `reasoning` 可能为空。" } } } } } ] }, "StreamEventTextChunk": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "text": { "type": "string", "description": "文本内容块。" }, "from_variable_selector": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "工作流中文本变量的源路径。" } } } } } ] }, "StreamEventWorkflowFinished": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowFinishedData" } } } ] }, "StreamEventTtsMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64 编码的 MP3 音频块。按顺序解码并拼接所有块即可生成完整的音频文件。" }, "created_at": { "type": "integer", "format": "int64", "description": "该音频块生成时的 Unix 时间戳。" } } } ] }, "StreamEventTtsMessageEnd": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "audio": { "type": "string", "description": "空字符串。标识音频流结束。" }, "created_at": { "type": "integer", "format": "int64", "description": "音频流结束时的 Unix 时间戳。" } } } ] }, "StreamEventError": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "status": { "type": "integer", "description": "错误的 HTTP 状态码。" }, "code": { "type": "string", "description": "错误码。" }, "message": { "type": "string", "description": "错误信息。" } } } ] }, "StreamEventPing": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "type": "object", "description": "保活 ping 事件。无附加属性。" } ] }, "WorkflowFinishedData": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "工作流运行 ID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "工作流 ID." }, "status": { "type": "string", "description": "工作流执行状态。`running` 表示执行中，`succeeded` 表示成功完成，`failed` 表示执行出错，`stopped` 表示手动停止，`partial-succeeded` 表示部分节点成功但其他失败，`paused` 表示等待人工介入。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "工作流的输出数据。" }, "error": { "type": "string", "nullable": true, "description": "工作流失败时的错误消息。" }, "elapsed_time": { "type": "number", "format": "float", "description": "总耗时（秒）。" }, "total_tokens": { "type": "integer", "description": "所有节点消耗的总令牌数。" }, "total_steps": { "type": "integer", "description": "已执行的工作流总步数。" }, "created_at": { "type": "integer", "format": "int64", "description": "工作流运行创建时的 Unix 时间戳。" }, "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "工作流运行结束时的 Unix 时间戳。" }, "created_by": { "type": "object", "additionalProperties": true, "description": "创建者信息。仅存在于流式 `workflow_finished` 事件中。" }, "exceptions_count": { "type": "integer", "nullable": true, "description": "执行过程中遇到的异常数量。仅在流式 `workflow_finished` 事件中出现。" }, "files": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "nullable": true, "description": "工作流执行期间生成的文件。仅存在于流式 `workflow_finished` 事件中。" } } }, "WorkflowRunDetailResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "工作流运行 ID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "工作流 ID." }, "status": { "type": "string", "description": "工作流执行状态。`running` 表示执行中，`succeeded` 表示成功完成，`failed` 表示执行出错，`stopped` 表示手动停止，`partial-succeeded` 表示部分节点成功但其他失败，`paused` 表示等待人工介入。" }, "inputs": { "type": "string", "nullable": true, "description": "工作流运行的输入变量，以原始 JSON 字符串返回（例如 `{\"query\": \"...\"}`），客户端需自行解析；可能为 `null`。" }, "outputs": { "type": "object", "additionalProperties": true, "description": "工作流的输出数据。尚无输出时为空对象。" }, "error": { "type": "string", "nullable": true, "description": "工作流失败时的错误消息。" }, "total_steps": { "type": "integer", "description": "已执行的工作流总步数。" }, "total_tokens": { "type": "integer", "description": "消耗的总令牌数。" }, "created_at": { "type": "integer", "format": "int64", "description": "工作流运行创建时的 Unix 时间戳。" }, "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "工作流运行结束时的 Unix 时间戳。" }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "总耗时（秒）。" } } }, "FileUploadResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "唯一文件 ID。" }, "name": { "type": "string", "description": "文件名。" }, "size": { "type": "integer", "description": "文件大小（字节）。" }, "extension": { "type": "string", "nullable": true, "description": "文件扩展名。" }, "mime_type": { "type": "string", "nullable": true, "description": "文件的 MIME 类型。" }, "created_by": { "type": "string", "format": "uuid", "nullable": true, "description": "上传文件的用户 ID。" }, "created_at": { "type": "integer", "format": "int64", "description": "上传时间戳（Unix 纪元秒）。" }, "preview_url": { "type": "string", "nullable": true, "description": "文件的预览 URL。" }, "source_url": { "type": "string", "description": "文件的签名下载 URL。" }, "original_url": { "type": "string", "nullable": true, "description": "文件的原始 URL。" }, "user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "未使用，始终为 `null`。" }, "tenant_id": { "type": "string", "format": "uuid", "nullable": true, "description": "关联的租户 ID。" }, "conversation_id": { "type": "string", "format": "uuid", "nullable": true, "description": "关联的会话 ID。" }, "file_key": { "type": "string", "nullable": true, "description": "未使用，始终为 `null`。" } } }, "EndUserDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "终端用户 ID。" }, "tenant_id": { "type": "string", "format": "uuid", "description": "租户 ID。" }, "app_id": { "type": "string", "format": "uuid", "nullable": true, "description": "应用 ID。" }, "type": { "type": "string", "description": "终端用户类型。Service API 用户固定为 `service_api`。" }, "external_user_id": { "type": "string", "nullable": true, "description": "API 请求中提供的 `user` 标识符（例如 [发送对话消息](/api-reference/对话消息/发送对话消息) 中的 `user` 字段）。" }, "name": { "type": "string", "nullable": true, "description": "终端用户名称。" }, "is_anonymous": { "type": "boolean", "description": "用户是否为匿名用户。当原始 API 请求中未提供 `user` 标识符时，值为 `true`。" }, "session_id": { "type": "string", "description": "会话标识符。默认为 `external_user_id` 的值。" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间戳。" }, "updated_at": { "type": "string", "format": "date-time", "description": "最后更新时间戳。" } } }, "WorkflowLogsResponse": { "type": "object", "properties": { "page": { "type": "integer", "description": "当前页码。" }, "limit": { "type": "integer", "description": "每页条目数。" }, "total": { "type": "integer", "description": "日志条目总数。" }, "has_more": { "type": "boolean", "description": "是否有更多可用页面。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowLogItem" }, "description": "工作流日志条目列表。" } } }, "WorkflowLogItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "日志条目 ID。" }, "workflow_run": { "$ref": "#/components/schemas/WorkflowRunSummary" }, "created_from": { "type": "string", "description": "工作流运行的来源（例如 `service-api`）。" }, "created_by_role": { "type": "string", "description": "创建者的角色（例如 `end_user`、`account`）。" }, "created_by_account": { "type": "object", "nullable": true, "description": "由管理员用户创建时的账户详情。", "properties": { "id": { "type": "string", "format": "uuid", "description": "账户 ID。" }, "name": { "type": "string", "description": "账户显示名称。" }, "email": { "type": "string", "description": "账户邮箱地址。" } } }, "created_by_end_user": { "$ref": "#/components/schemas/EndUserSummary" }, "created_at": { "type": "integer", "format": "int64", "description": "日志条目创建时的 Unix 时间戳。" }, "details": { "type": "object", "additionalProperties": true, "nullable": true, "description": "日志条目的附加详情。" } } }, "WorkflowRunSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "工作流运行 ID。" }, "version": { "type": "string", "description": "工作流版本标识符。" }, "status": { "type": "string", "description": "工作流执行状态。`running` 表示执行中，`succeeded` 表示成功完成，`failed` 表示执行出错，`stopped` 表示手动停止，`partial-succeeded` 表示部分节点成功但其他失败，`paused` 表示等待人工介入。" }, "error": { "type": "string", "nullable": true, "description": "工作流失败时的错误消息。" }, "elapsed_time": { "type": "number", "format": "float", "description": "总耗时（秒）。" }, "total_tokens": { "type": "integer", "description": "消耗的总令牌数。" }, "total_steps": { "type": "integer", "description": "已执行的工作流总步数。" }, "created_at": { "type": "integer", "format": "int64", "description": "工作流运行创建时的 Unix 时间戳。" }, "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "工作流运行结束时的 Unix 时间戳。" }, "exceptions_count": { "type": "integer", "description": "执行期间发生的异常数量。" }, "triggered_from": { "type": "string", "description": "触发工作流运行的来源。`app-run` 表示从应用或 API 发起的运行，`webhook` 表示由 Webhook 触发器发起的运行，`schedule` 表示由定时触发器发起的运行，`plugin` 表示由插件触发器发起的运行。" } } }, "EndUserSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "终端用户 ID。" }, "type": { "type": "string", "description": "终端用户类型。" }, "is_anonymous": { "type": "boolean", "description": "终端用户是否为匿名。" }, "session_id": { "type": "string", "description": "会话标识符。" } } }, "AudioToTextRequest": { "type": "object", "description": "语音转文字的请求体。", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "音频文件。按 MIME 类型校验，必须为 `audio/mp3`、`audio/m4a`、`audio/wav`、`audio/amr`、`audio/mpga` 之一。大小限制：`30 MB`。" }, "user": { "type": "string", "description": "用户标识符。" } } }, "AudioToTextResponse": { "type": "object", "properties": { "text": { "type": "string", "description": "语音识别输出的文字。" } } }, "TextToAudioRequest": { "type": "object", "description": "文字转语音的请求体。提供 `message_id` 或 `text` 其中之一。", "properties": { "message_id": { "type": "string", "format": "uuid", "description": "消息 ID。当同时提供 `text` 时，优先使用消息 ID。" }, "text": { "type": "string", "description": "要转换的语音内容。" }, "user": { "type": "string", "description": "用户标识符。" }, "voice": { "type": "string", "description": "文字转语音使用的声音。可用声音取决于为此应用配置的 TTS 提供商。使用[获取应用参数](/api-reference/应用配置/获取应用参数) → `text_to_speech.voice` 中的 `voice` 值作为默认值。" }, "streaming": { "type": "boolean", "description": "是否启用流式响应。" } } }, "AppInfoResponse": { "type": "object", "properties": { "name": { "type": "string", "description": "应用名称。" }, "description": { "type": "string", "description": "应用描述。" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "应用标签。" }, "mode": { "type": "string", "description": "应用模式。`completion` 为文本生成应用，`chat` 为基础对话应用，`agent-chat` 为 Agent 应用，`advanced-chat` 为 Chatflow 应用，`workflow` 为 Workflow 应用。" }, "author_name": { "type": "string", "description": "应用作者名称。" } } }, "WorkflowAppParametersResponse": { "type": "object", "properties": { "opening_statement": { "type": "string", "nullable": true, "description": "开场白文本。" }, "suggested_questions": { "type": "array", "items": { "type": "string" }, "description": "建议问题列表。" }, "suggested_questions_after_answer": { "type": "object", "description": "回答后建议问题的配置。", "properties": { "enabled": { "type": "boolean", "description": "是否启用此功能。" } } }, "speech_to_text": { "type": "object", "description": "语音转文字功能配置。", "properties": { "enabled": { "type": "boolean", "description": "是否启用此功能。" } } }, "text_to_speech": { "type": "object", "description": "文字转语音功能配置。", "properties": { "enabled": { "type": "boolean", "description": "是否启用此功能。" }, "voice": { "type": "string", "description": "TTS 声音标识符。" }, "language": { "type": "string", "description": "TTS 语言。" }, "autoPlay": { "type": "string", "description": "自动播放设置。`enabled` 为自动播放音频，`disabled` 为需要手动播放。" } } }, "retriever_resource": { "type": "object", "description": "知识检索引用资源配置。", "properties": { "enabled": { "type": "boolean", "description": "是否启用此功能。" } } }, "annotation_reply": { "type": "object", "description": "标注回复功能配置。", "properties": { "enabled": { "type": "boolean", "description": "是否启用此功能。" } } }, "more_like_this": { "type": "object", "description": "更多类似推荐功能配置。", "properties": { "enabled": { "type": "boolean", "description": "是否启用此功能。" } } }, "sensitive_word_avoidance": { "type": "object", "description": "内容审核功能配置。", "properties": { "enabled": { "type": "boolean", "description": "是否启用此功能。" } } }, "user_input_form": { "type": "array", "items": { "type": "object", "oneOf": [ { "title": "Text Input", "type": "object", "properties": { "text-input": { "type": "object", "properties": { "label": { "type": "string", "description": "输入字段的显示标签。" }, "variable": { "type": "string", "description": "工作流中使用的变量名称。" }, "required": { "type": "boolean", "description": "该字段是否必填。" }, "default": { "type": "string", "description": "输入字段的默认值。" } } } } }, { "title": "Paragraph", "type": "object", "properties": { "paragraph": { "type": "object", "properties": { "label": { "type": "string", "description": "段落字段的显示标签。" }, "variable": { "type": "string", "description": "工作流中使用的变量名称。" }, "required": { "type": "boolean", "description": "该字段是否必填。" }, "default": { "type": "string", "description": "段落字段的默认值。" } } } } }, { "title": "Select", "type": "object", "properties": { "select": { "type": "object", "properties": { "label": { "type": "string", "description": "下拉选择字段的显示标签。" }, "variable": { "type": "string", "description": "工作流中使用的变量名称。" }, "required": { "type": "boolean", "description": "该字段是否必填。" }, "default": { "type": "string", "description": "默认选中的值。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "此表单控件的可选值列表。" } } } } } ] }, "description": "用户输入表单配置。" }, "file_upload": { "type": "object", "description": "文件上传配置。", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是否启用图片上传。" }, "number_limits": { "type": "integer", "description": "可上传的最大图片数量。" }, "detail": { "type": "string", "description": "视觉模型的图像细节级别。" }, "transfer_methods": { "type": "array", "items": { "type": "string" }, "description": "图片上传允许的传输方式。`remote_url` 表示通过文件 URL 上传，`local_file` 表示上传本地文件。" } } } } }, "system_parameters": { "type": "object", "description": "系统级参数限制。", "properties": { "file_size_limit": { "type": "integer", "description": "常规文件最大大小（MB）。" }, "image_file_size_limit": { "type": "integer", "description": "最大图片文件大小（MB）。" }, "audio_file_size_limit": { "type": "integer", "description": "最大音频文件大小（MB）。" }, "video_file_size_limit": { "type": "integer", "description": "最大视频文件大小（MB）。" }, "workflow_file_upload_limit": { "type": "integer", "description": "每次工作流执行的最大文件数量。" } } } } }, "ToolIconDetail": { "type": "object", "properties": { "background": { "type": "string", "description": "工具图标的背景颜色。" }, "content": { "type": "string", "description": "表情符号或图标内容。" } } }, "AppMetaResponse": { "type": "object", "properties": { "tool_icons": { "type": "object", "additionalProperties": { "oneOf": [ { "title": "Icon URL", "type": "string", "format": "url", "description": "图标的 URL。" }, { "$ref": "#/components/schemas/ToolIconDetail" } ] }, "description": "工具图标。键为工具名称。" } } }, "WebAppSettingsResponse": { "type": "object", "properties": { "title": { "type": "string", "description": "WebApp 标题。" }, "chat_color_theme": { "type": "string", "description": "聊天主题颜色。" }, "chat_color_theme_inverted": { "type": "boolean", "description": "聊天主题颜色是否反转。" }, "icon_type": { "type": "string", "description": "使用的图标类型。`emoji` 为表情图标，`image` 为上传的图片图标。" }, "icon": { "type": "string", "description": "图标内容（表情或图片 ID）。" }, "icon_background": { "type": "string", "description": "图标背景颜色。" }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "图标图片的 URL。" }, "description": { "type": "string", "description": "WebApp 描述。" }, "copyright": { "type": "string", "description": "版权文本。" }, "privacy_policy": { "type": "string", "description": "隐私政策 URL。" }, "custom_disclaimer": { "type": "string", "description": "自定义免责声明文本。" }, "default_language": { "type": "string", "description": "默认语言代码。" }, "show_workflow_steps": { "type": "boolean", "description": "是否显示工作流步骤。" }, "use_icon_as_answer_icon": { "type": "boolean", "description": "是否使用应用图标作为回答图标。" } } }, "StreamEventWorkflowPaused": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid", "description": "此工作流运行记录的持久化标识符。配合 [获取工作流运行详情](/api-reference/工作流/获取工作流执行情况) 使用以在执行后获取结果。" }, "paused_nodes": { "type": "array", "items": { "type": "string" }, "description": "已暂停的节点 ID 列表。" }, "outputs": { "type": "object", "additionalProperties": true, "description": "暂停时的部分输出。" }, "reasons": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "暂停原因。" }, "status": { "type": "string", "description": "工作流执行状态。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳。" }, "elapsed_time": { "type": "number", "format": "float", "description": "总耗时（秒）。" }, "total_tokens": { "type": "integer", "description": "消耗的总令牌数。" }, "total_steps": { "type": "integer", "description": "已执行的总步数。" } } } } } ] }, "StreamEventAgentLog": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "node_execution_id": { "type": "string", "description": "节点执行 ID。" }, "id": { "type": "string", "description": "Agent 日志条目 ID。" }, "label": { "type": "string", "description": "Log label." }, "parent_id": { "type": "string", "nullable": true, "description": "父日志条目 ID。" }, "error": { "type": "string", "nullable": true, "description": "Agent 步骤失败时的错误消息。" }, "status": { "type": "string", "description": "Agent 步骤状态。" }, "data": { "type": "object", "additionalProperties": true, "description": "Agent 步骤数据。" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Agent 步骤元数据。" }, "node_id": { "type": "string", "description": "Node ID." } } } } } ] }, "StreamEventHumanInputRequired": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "form_id": { "type": "string", "description": "表单实例的标识符，会在错误消息和日志中出现。Service API 调用请使用 `form_token`。" }, "node_id": { "type": "string", "description": "产生该表单的 Human Input 节点 ID。" }, "node_title": { "type": "string", "description": "Human Input 节点的显示标题。" }, "form_content": { "type": "string", "description": "已替换工作流变量的预渲染表单正文。" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "表单输入控件类型。可用值：`paragraph`（多行文本输入）、`select`（从列表中单选）、`file`（单文件上传）和 `file-list`（多文件上传）。" }, "output_variable_name": { "type": "string", "description": "引用该输入提交值在工作流中使用的变量名。对应提交 `inputs` 对象中的键。" }, "default": { "type": "object", "nullable": true, "description": "从工作流上下文解析得到的默认值。未配置默认值时为 `null`。", "properties": { "type": { "type": "string", "description": "默认值来源。`constant` 表示将 `value` 作为字面字符串；`variable` 表示 `selector` 指向工作流变量。" }, "selector": { "type": "array", "items": { "type": "string" }, "description": "当 `type` 为 `variable` 时，变量引用路径（例如 `[\"node_id\", \"var_name\"]`）。至少包含两个元素。" }, "value": { "type": "string", "description": "当 `type` 为 `constant` 时的字面默认值。始终为字符串。" } } } } }, "description": "接收者需要填写的表单输入字段。" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 20, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "操作按钮的标识。当接收者选择该按钮时，作为 `action` 传入 [提交人工介入表单](/api-reference/人工介入/提交人工介入表单)。" }, "title": { "type": "string", "maxLength": 100, "description": "显示给接收者的按钮文本。" }, "button_style": { "type": "string", "description": "按钮视觉样式。可用值：`primary`、`default`、`accent`、`ghost`。" } } }, "description": "接收者提交时可选择的用户操作（按钮）。" }, "display_in_ui": { "type": "boolean", "description": "表单是否也在 Dify 控制台中显示。" }, "form_token": { "type": "string", "nullable": true, "description": "[获取人工介入表单](/api-reference/人工介入/获取人工介入表单) 和 [提交人工介入表单](/api-reference/人工介入/提交人工介入表单) 的访问令牌。当人工介入节点使用邮件或控制台送达时为 `null`（Service API 仅能处理 WebApp 送达的表单）。" }, "resolved_default_values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "按输入的 `output_variable_name` 分组的预填充默认值。所有值均为字符串。" }, "expiration_time": { "type": "integer", "format": "int64", "description": "Unix 时间戳（秒），超过后表单无法再被提交。" } } } } } ] }, "StreamEventHumanInputFormFilled": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "node_id": { "type": "string", "description": "表单被填写的 Human Input 节点 ID。" }, "node_title": { "type": "string", "description": "Human Input 节点的显示标题。" }, "rendered_content": { "type": "string", "description": "包含接收者提交值的渲染后表单内容（`human_input_required` 上的 `form_content` 是未填写的模板）。" }, "action_id": { "type": "string", "description": "接收者所选操作的标识（与传入 [提交人工介入表单](/api-reference/人工介入/提交人工介入表单) 的 `action` 一致）。" }, "action_text": { "type": "string", "description": "所选操作的显示文本。" } } } } } ] }, "StreamEventHumanInputFormTimeout": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "node_id": { "type": "string", "description": "表单过期的 Human Input 节点 ID。" }, "node_title": { "type": "string", "description": "Human Input 节点的显示标题。" }, "expiration_time": { "type": "integer", "format": "int64", "description": "Unix 时间戳（秒），表示表单过期时刻。" } } } } } ] } } }, "tags": [ { "name": "工作流", "description": "用于执行和管理工作流的操作。" }, { "name": "文件操作", "description": "文件上传操作。" }, { "name": "终端用户", "description": "终端用户信息相关操作。" }, { "name": "语音与文字转换", "description": "语音转文字和文字转语音转换。" }, { "name": "应用配置", "description": "应用设置、参数和元数据。" }, { "name": "人工介入", "description": "暂停等待人工输入的工作流恢复操作。" } ] }