メインコンテンツへスキップ

Documentation Index

Fetch the complete documentation index at: https://dify-6c0370d8-docs-hitl-2.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

⚠️ このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、英語版 を参照してください。
ワークフローが人間の入力ノードに到達すると一時停止し、ストリーミングレスポンスから human_input_required イベントが送出されます。このイベントが運ぶ form_token を使って、ワークフローが再開するまでフォームのライフサイクルを進めます。 各エンドポイントのリファレンスは 人間の入力 API を参照してください。

​
フロー

以下のフローは Workflow アプリと Chatflow アプリの両方に共通します。両者は手順 1 のエントリエンドポイントと手順 6 の再開エンドポイントだけが異なります。
1

アプリをストリーミングモードで起動

  1. Workflow アプリは ワークフローを実行 を呼び出します。Chatflow アプリは チャットメッセージを送信 を呼び出します。
  2. SSE ストリームで human_input_required イベントを監視し、ペイロードから form_token、form_id、task_id を取得します。 SSE ストリームがワークフロー再開前に切断された場合、手順 6 で task_id を使います。
2

フォーム定義を取得

form_token を指定して 人間の入力フォームを取得 エンドポイントを呼び出します。レスポンスにはレンダリング済みの Markdown、入力フィールド定義、利用可能なアクション、事前入力済みのデフォルト値が含まれます。フォームを受信者に表示します。
3

（ファイル入力時のみ）アップロードトークンを発行

フォームに file または file-list 入力が含まれる場合のみ実行します。アップロードトークンを発行 エンドポイントを呼び出すと、短期有効な upload_token が返ります。同じフォームに対する複数のアップロードでこのトークンを再利用できます。
4

（ファイル入力時のみ）ファイルをアップロード

受信者が添付するファイルごとに、次のいずれかを呼び出します。どちらも id を返します。送信時にこの値を upload_file_id として参照します。
5

応答を送信

人間の入力フォームを送信 エンドポイントを呼び出し、受信者の入力値と選択されたアクションを送ります。ファイル入力には、{transfer_method: local_file, upload_file_id} マッピング（手順 4 の結果）と、インラインの {transfer_method: remote_url, url} マッピングのどちらも使えます。トレードオフの詳細は 事前アップロードかインラインリモート URL か を参照してください。送信に成功すると、ワークフローは該当するアクション分岐から再開します。
6

ワークフローの監視を継続

元の SSE ストリームが切断されている場合は、手順 1 の task_id を使います。Workflow または Chatflow のワークフローイベントをストリームエンドポイントに再接続します。

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

ファイル入力には 2 つの送信パターンがあります。
  • 事前アップロードしてから upload_file_id で送信（推奨） バックエンドは、ファイルサイズ・タイプ・拡張子をアップロード時に検証します。受信者はエラーをすぐに確認でき、送信前に再試行できます。
  • transfer_method: remote_url でインライン送信 バックエンドは送信時にファイルを取得します。実装は速いですが、サイズ・タイプ・取得の失敗があると送信全体が拒否され、他のフィールドを再入力する必要が出る場合があります。
受信者からのフィードバックが伴うインタラクティブなフォームでは、事前アップロードのパターンを推奨します。完全に自動化されたインテグレーションで、誰も再入力を待たされない場合のみ、インラインのトレードオフが見合います。

​
認証

フォーム向けの 人間の入力フォームを取得 と 人間の入力フォームを送信 エンドポイントは認証不要です。form_token 自体がアクセス資格情報として機能し、これらのエンドポイントはクライアント IP ごとにレート制限されます。 ファイルアップロードエンドポイントは、手順 3 で取得した Bearer upload_token を必要とします。

​
配信方法の前提

人間の入力 API は、人間の入力ノードで WebApp 配信方法が設定されたフォームのみを対象とします。メール配信のみのフォームは、API に form_token を公開しません。

​
例：ファイル添付付きの送信

このフォームには、feedback 段落入力、attachments ファイルリスト入力、approve / revise アクションがあるものとします。
  1. 人間の入力フォームを取得 エンドポイントを呼び出してフォーム定義を取得します。 
    GET /form/human_input/<form_token>
  2. アップロードトークンを発行 エンドポイントを呼び出してアップロードトークンを取得します。 
    POST /form/human_input/<form_token>/upload-token
    {"upload_token": "hitl_upload_...", "expires_at": ...} が返ります。
  3. ローカルファイルごとに ローカルファイルをアップロード エンドポイントを呼び出します。 
    POST /form/human_input/files/upload
Authorization: Bearer hitl_upload_...
Content-Type: multipart/form-data

file=<binary>
    {"id": "1a77f0df-...", ...} が返ります。
  4. 人間の入力フォームを送信 エンドポイントを呼び出し、受信者の入力と選択されたアクションを送ります。 
    POST /form/human_input/<form_token>
Content-Type: application/json

{
  "inputs": {
    "feedback": "公開して問題ありません",
    "attachments": [
      {"transfer_method": "local_file", "upload_file_id": "1a77f0df-..."}
    ]
  },
  "action": "approve",
  "user": "abc-123"
}
    {} が返ります。ワークフローは approve 分岐から再開します。