> ## 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.

# 人工介入 API 集成流程

> 通过 API 处理暂停中的人工介入表单的端到端流程

> 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/use-dify/nodes/hitl-api-integration-flow)。

当工作流执行到人工介入节点时会暂停，并在流式响应中发出 `human_input_required` 事件。该事件携带 `form_token`，集成方可凭其驱动整个表单生命周期，直到工作流恢复执行。

各接口的字段参考，详见 [人工介入 API](/api-reference/人工介入/获取人工介入表单)。

## 流程

下方流程同时适用于 Workflow 和 Chatflow 应用。两者仅在第 1 步的入口接口与第 5 步的恢复接口上有所不同。

<Steps>
  <Step title="以流式模式启动应用">
    1. Workflow 应用调用 [执行工作流](/api-reference/工作流/执行工作流)，Chatflow 应用调用 [发送对话消息](/api-reference/对话流/发送对话消息)。
    2. 在 SSE 流中关注 `human_input_required` 事件，提取其中的 `form_token`。

       每个流式数据块都带有 `task_id`；请保留它，以便在第 5 步需要时恢复监听。
  </Step>

  <Step title="获取表单定义">
    使用 `form_token` 调用 [获取人工介入表单](/api-reference/人工介入/获取人工介入表单) 接口。响应包含渲染后的 Markdown、输入字段定义、可用操作、已预填的默认值，以及一个 `expiration_time`，超过该时间后表单将无法再提交。将表单呈现给接收人。
  </Step>

  <Step title="（仅文件输入）上传本地文件">
    若接收人为 `file` 或 `file-list` 输入附加了本地文件，请先通过 [上传文件](/api-reference/文件操作/上传文件) 上传。该接口返回一个 `id`，提交时作为 `upload_file_id` 引用。执行、上传和提交各次调用请使用同一个 `user`。

    远程文件无需上传：在提交时以 `{transfer_method: remote_url, url}` 映射内联附加即可。
  </Step>

  <Step title="提交响应">
    调用 [提交人工介入表单](/api-reference/人工介入/提交人工介入表单) 接口，附上接收人输入的值、所选的 `action` 以及你的 `user`。`action` 必须是第 2 步表单定义中的某个操作。

    文件输入既可使用 `{transfer_method: local_file, upload_file_id}` 映射（来自第 3 步），也可在提交时直接使用 `{transfer_method: remote_url, url}` 映射。两种模式的权衡详见 [先上传 vs 直接提交远程 URL](#先上传-vs-直接提交远程-url)。

    提交一旦成功即为最终结果：表单随之关闭，工作流沿匹配的操作分支恢复执行，同一个 `form_token` 无法再次提交。若提交被拒绝（操作无效、缺少必填输入，或远程文件抓取失败），表单保持不变，修正输入后可用同一个 `form_token` 重新提交。
  </Step>

  <Step title="继续监听工作流">
    若原 SSE 流已关闭，使用第 1 步中的 `task_id` 调用 [Workflow](/api-reference/工作流/流式获取工作流事件) 或 [Chatflow](/api-reference/对话流/流式获取工作流事件) 的订阅工作流事件接口重新连接。恢复后的运行会像从未暂停过一样，继续流式输出其余节点事件直至完成。
  </Step>
</Steps>

## 先上传 vs 直接提交远程 URL

文件输入支持两种提交模式：

* **先上传，再使用 `upload_file_id`**（推荐）

  [上传文件](/api-reference/文件操作/上传文件) 在上传阶段即校验文件大小、类型和扩展名，接收人可立即看到错误并在提交前重试。

* **使用 `transfer_method: remote_url` 直接提交**

  后端在提交阶段抓取文件。集成更快，但任何大小、类型或抓取失败都会拒绝整次提交，接收人可能需要重填其他字段。

<Tip>
  对于需要接收人反馈的交互式表单，优先选择先上传模式。仅当流程完全程序化、无需任何人重新输入时，直接提交模式的代价才能被抵消。
</Tip>

## 提交方式要求

人工介入 API 仅支持通过人工介入节点的 WebApp 提交方式投递的表单。仅通过邮件投递的表单不会向 API 暴露 `form_token`。

## 示例：带文件的提交

本示例的表单包含一个 `feedback` 段落输入、一个 `attachments` 文件列表输入，以及 `approve` / `revise` 两个操作。

1. 调用 [获取人工介入表单](/api-reference/人工介入/获取人工介入表单) 接口获取表单定义：

   ```http theme={null}
   GET /form/human_input/<form_token>
   Authorization: Bearer {api-key}
   ```

2. 针对每个本地文件，调用 [上传文件](/api-reference/文件操作/上传文件) 接口：

   ```http theme={null}
   POST /files/upload
   Authorization: Bearer {api-key}
   Content-Type: multipart/form-data

   file=<binary>
   user=abc-123
   ```

   返回 `{"id": "1a77f0df-...", ...}`。

3. 调用 [提交人工介入表单](/api-reference/人工介入/提交人工介入表单) 接口，附上接收人输入与所选操作：

   ```http theme={null}
   POST /form/human_input/<form_token>
   Authorization: Bearer {api-key}
   Content-Type: application/json

   {
     "inputs": {
       "feedback": "可以发布",
       "attachments": [
         {"transfer_method": "local_file", "upload_file_id": "1a77f0df-..."}
       ]
     },
     "action": "approve",
     "user": "abc-123"
   }
   ```

   返回 `{}`。工作流沿 `approve` 分支恢复执行。