> ## 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}` マッピングのどちらも使えます。トレードオフの詳細は [事前アップロードかインラインリモート URL か](#事前アップロードかインラインリモート-url-か) を参照してください。

    送信が成功すると確定し、フォームは閉じられ、ワークフローは該当するアクション分岐から再開するため、同じ `form_token` で再送信することはできません。送信が拒否された場合（無効なアクション、必須入力の欠落、リモートファイルの取得失敗）、フォームはそのまま変わりません。入力を修正し、同じ `form_token` で再送信してください。
  </Step>

  <Step title="ワークフローの監視を継続">
    元の SSE ストリームが切断されている場合は、手順 1 の `task_id` を使います。[Workflow](/api-reference/ワークフロー/ワークフローイベントをストリーム) または [Chatflow](/api-reference/チャットフロー/ワークフローイベントをストリーム) のワークフローイベントをストリームエンドポイントに再接続します。再開した実行は、一時停止しなかった実行と同じように、残りのノードイベントを完了までストリーミングします。
  </Step>
</Steps>

## 事前アップロードかインラインリモート URL か

ファイル入力には 2 つの送信パターンがあります。

* **事前アップロードしてから `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` 分岐から再開します。