> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow 应用 API

> Workflow 应用 API，涵盖工作流执行、运行控制与流式传输、人工介入暂停、运行历史查询

> 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/api-reference/guides/workflow)。

[Workflow 应用](/zh/cloud/use-dify/build/workflow-chatflow) 运行在 `workflow` 模式下，每次调用执行一次已发布的工作流并返回其输出。调用之间不保留会话状态，每次运行都相互独立。

<Info>
  认证方式、基础 URL，以及按终端用户区分数据的 `user` 字段，详见 [快速开始](/zh/api-reference/guides/get-started) 和 [终端用户身份](/zh/api-reference/guides/end-user-identity)。
</Info>

## 运行工作流

* **[执行工作流](/zh/api-reference/workflow-runs/run-workflow)**：使用提供的输入变量，执行应用当前已发布的工作流。

  流式返回时，节点执行过程中会实时推送事件；阻塞式返回时，运行结束后才返回结果。
* **[按 ID 执行工作流](/zh/api-reference/workflow-runs/run-workflow-by-id)**：执行指定的已发布版本，其 `workflow_id` 来自此前的运行响应或运行详情查询结果。

## 跟踪与控制运行

无论选择哪种模式，响应都会携带两个 ID：`task_id` 用于控制运行中的任务，`workflow_run_id` 用于标识运行结束后持久保存的记录。

* **[停止工作流任务](/zh/api-reference/workflow-runs/stop-workflow-task)**：通过 `task_id` 取消运行中的任务。仅适用于流式返回；阻塞式返回的响应送达时，任务已执行完毕，无法取消。
* **[流式获取工作流事件](/zh/api-reference/workflow-runs/stream-workflow-events)**：连接中断或运行暂停后，从 `workflow_run_id` 恢复事件流。

  传入 `include_state_snapshot=true` 可先重放已执行节点的状态，传入 `continue_on_pause=true` 可在多次人工介入暂停间保持流连接。

## 人工介入暂停

当运行到达提交方式为 WebApp 的 [人工介入](/zh/cloud/use-dify/nodes/human-input) 节点时，可通过 API 完成这次暂停的处理：

<Steps>
  <Step title="监听暂停事件">
    运行的事件流会推送 `human_input_required` 事件，其中携带 `form_token` 和本次运行的 `workflow_run_id`，随后以 `workflow_paused` 事件结束。
  </Step>

  <Step title="获取表单">
    使用 `form_token` 调用 [获取人工介入表单](/zh/api-reference/human-input/get-human-input-form)，加载表单内容。
  </Step>

  <Step title="提交填写结果">
    通过 [提交人工介入表单](/zh/api-reference/human-input/submit-human-input-form) 发送接收者的填写内容。提交后运行恢复执行。
  </Step>

  <Step title="继续跟踪事件流">
    使用暂停时事件流中的 `workflow_run_id`，调用 [流式获取工作流事件](/zh/api-reference/workflow-runs/stream-workflow-events) 打开新的事件流，跟踪剩余事件，直到运行结束。
  </Step>
</Steps>

带文件的表单提交与完整事件序列，详见 [人工介入流程](/zh/api-reference/guides/human-input-flow) 指南。

## 查看历史运行

* **[获取工作流执行情况](/zh/api-reference/workflow-runs/get-workflow-run-detail)**：根据 `workflow_run_id` 查询某次运行的状态与输出。
* **[获取工作流日志](/zh/api-reference/workflow-runs/list-workflow-logs)**：返回运行级别的汇总信息（状态、token 用量、步骤数、耗时），而非逐节点的执行日志；可按关键词、状态、时间范围或触发运行的用户筛选。

如需逐节点的事件，应流式跟踪运行本身，而非查看日志：新发起的运行以流式返回调用 [执行工作流](/zh/api-reference/workflow-runs/run-workflow)，已在执行中的运行使用 [流式获取工作流事件](/zh/api-reference/workflow-runs/stream-workflow-events)。

## 处理文件

* **[上传文件](/zh/api-reference/files/upload-file)**：上传图片、文档、音频或视频文件，运行工作流时在文件类型的输入变量中以返回的 `id` 作为 `upload_file_id` 传入。文件仅限上传的终端用户使用。
* **[获取终端用户信息](/zh/api-reference/end-users/get-end-user-info)**：根据终端用户 ID（例如上传文件响应中的 `created_by`）查询该用户的详细信息。

## 语音转写与合成

* **[语音转文字](/zh/api-reference/audio/convert-audio-to-text)**：将上传的音频文件（MP3、M4A、WAV、AMR 或 MPGA，最大 30 MB）转写为文字，让终端用户用语音代替打字提供输入值。
* **[文字转语音](/zh/api-reference/audio/convert-text-to-audio)**：将工作流的文本输出合成为语音。

## 获取应用信息与配置

* **[获取应用基本信息](/zh/api-reference/applications/get-app-info)**：返回应用的名称、描述、标签和模式。
* **[获取应用参数](/zh/api-reference/applications/get-app-parameters)**：返回调用需在 `inputs` 中传入的字段（名称、类型、默认值），以及应用的功能开关，可据此构建请求或客户端界面。
* **[获取应用元数据](/zh/api-reference/applications/get-app-meta)**：返回工具图标等配置元数据。
* **[获取应用 WebApp 设置](/zh/api-reference/applications/get-app-webapp-settings)**：返回 WebApp 的站点配置、主题和自定义选项。