> ## Documentation Index > Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # ワークフローを実行 > **対象アプリ**：Workflow。 デプロイした Workflow のバージョンを、ブロッキングまたはストリーミングで実行します。 **標準 API の対応する操作**：[ワークフローを実行](/ja/3.13.x/develop/api/workflow-runs/run-workflow)。相違点は次のとおりです。 - `workflow_id` とボディの未知のフィールドは無視されます。 - `trace_id` と `trace_session_id` を受け付けます。 - リクエストボディの上限は 8 MiB です。 - ストリームに TTS、人間の入力、エージェントログ、検索ソースのイベントは含まれません。人間の入力が必要な手順に達した実行は失敗します。 - エラーコードが異なります。 ## OpenAPI ````yaml /ja/3.13.x/develop/api/openapi_service.json post /v2/workflows/run openapi: 3.0.1 info: title: Dify サービス API description: >- Dify アプリケーションとナレッジベースのための REST API です。アプリケーション系エンドポイントはアプリの API キーで、ナレッジ系エンドポイントはナレッジベースの API キーで認証します。 version: 1.0.0 servers: - url: https://{api_base_url} description: Dify サービス API のベース URL です。ご利用のデプロイ環境の API ベース URL に置き換えてください。 variables: api_base_url: default: api.example.com/v1 description: API ベース URL のホストとパス（`https://` を除く）。 security: - ApiKeyAuth: [] tags: - name: チャットメッセージ description: チャットメッセージとインタラクションに関連する操作です。 - name: ファイル操作 description: ファイルのアップロードとプレビューの操作です。 - name: エンドユーザー description: エンドユーザー情報に関連する操作です。 - name: メッセージフィードバック description: ユーザーフィードバックの操作です。 - name: 会話管理 description: 会話管理に関連する操作です。 - name: 音声・テキスト変換 description: テキスト読み上げと音声認識の操作です。 - name: アプリケーション設定 description: アプリケーション設定と情報を取得する操作です。 - name: アノテーション管理 description: ダイレクト返信用のアノテーション管理に関連する操作です。 - name: 人間の入力 description: 人間の入力を要する一時停止中のワークフローの再開操作です。 - name: ワークフロー実行 description: ワークフローの実行と管理のための操作です。 - name: 完了メッセージ description: テキスト生成に関連する操作です。 - name: ナレッジベース description: ナレッジベースの作成、設定、取得を含むナレッジベース管理の操作です。 - name: ドキュメント description: ナレッジベース内のドキュメントの作成、更新、管理のための操作です。 - name: チャンク description: ドキュメントチャンクと子チャンクの管理のための操作です。 - name: メタデータ description: ナレッジベースのメタデータフィールドとドキュメントメタデータ値の管理のための操作です。 - name: タグ管理 description: ナレッジベースタグとタグバインディングの管理のための操作です。 - name: モデル description: 利用可能なモデルを取得するための操作です。 - name: ナレッジパイプライン description: データソースプラグインとパイプライン実行を含むナレッジパイプラインの管理と実行のための操作です。 - name: デプロイ環境 description: >- デプロイ環境が `v2` ベース URL で提供するエンドポイントです。デプロイ環境が提供するのはこのグループのエンドポイントだけで、それ以外のパスを呼び出すと `404 not_found` が返ります。認証とエラーは標準の Service API とは異なります。デプロイ環境については、このグループの各ページが正式な情報源です。 paths: /v2/workflows/run: post: tags: - デプロイ環境 summary: ワークフローを実行 description: >- **対象アプリ**：Workflow。 デプロイした Workflow のバージョンを、ブロッキングまたはストリーミングで実行します。 **標準 API の対応する操作**：[ワークフローを実行](/ja/3.13.x/develop/api/workflow-runs/run-workflow)。相違点は次のとおりです。 - `workflow_id` とボディの未知のフィールドは無視されます。 - `trace_id` と `trace_session_id` を受け付けます。 - リクエストボディの上限は 8 MiB です。 - ストリームに TTS、人間の入力、エージェントログ、検索ソースのイベントは含まれません。人間の入力が必要な手順に達した実行は失敗します。 - エラーコードが異なります。 operationId: runDeployedWorkflowJa parameters: - name: X-Trace-Id in: header required: false schema: type: string description: ボディの `trace_id` と同じです。最初に読み取られます。 - name: trace_id in: query required: false schema: type: string description: ボディの `trace_id` と同じです。ヘッダーの次に読み取られます。 - name: X-Trace-Session-Id in: header required: false schema: type: string description: ボディの `trace_session_id` と同じです。最初に読み取られます。 - name: trace_session_id in: query required: false schema: type: string description: ボディの `trace_session_id` と同じです。ヘッダーの次に読み取られます。 requestBody: required: true content: application/json: schema: type: object required: - inputs - user properties: inputs: type: object description: >- アプリの入力変数の値を、変数名をキーとして指定します。対象環境に現在デプロイされているバージョンの入力変数に従って値を渡してください。 単一ファイル変数にはファイルオブジェクトを、ファイルリスト変数にはその配列を渡します。各オブジェクトの構造は `files` の各要素と同じです。 additionalProperties: oneOf: - type: string - type: number - type: boolean - type: object - type: array items: type: object required: - type properties: type: type: string enum: - image - document - audio - video - custom description: >- ファイルタイプ。アップロード済みファイルでは、保存時に Dify が判定したタイプと一致する必要があります。`custom` を指定した場合は対象外です。 transfer_method: type: string enum: - remote_url - local_file description: >- 転送方法です。ファイル URL の場合は `remote_url`、アップロードファイルの場合は `local_file` です。このフィールドがない項目は、エラーにならず無視されます。 url: type: string format: url description: '`remote_url` の項目で使うファイル URL です。' upload_file_id: type: string description: >- [ファイルをアップロード](/ja/3.13.x/develop/api/deployed-environments/upload-file) が返す `id` です。`transfer_method` が `local_file` の場合は必須です。 response_mode: type: string enum: - streaming - blocking description: |- レスポンスをどう返すかを指定します。 - `streaming`：実行が生成したイベントが順次届きます。短い応答以外はこちらを使います。 - `blocking`：実行の完了後に 1 つのレスポンスを返します。 default: blocking user: type: string description: >- エンドユーザーの識別子。アプリ側で定義し、アプリ内で一意にします。データアクセスをスコープします。ワークフロー実行とそのファイルは、同じ `user` を持つ後続のリクエストにのみ表示されます。[エンドユーザーの識別](/ja/3.13.x/develop/api/guides/end-user-identity) を参照してください。 files: type: array items: type: object required: - type properties: type: type: string enum: - image - document - audio - video - custom description: >- ファイルタイプ。アップロード済みファイルでは、保存時に Dify が判定したタイプと一致する必要があります。`custom` を指定した場合は対象外です。 transfer_method: type: string enum: - remote_url - local_file description: >- 転送方法です。ファイル URL の場合は `remote_url`、アップロードファイルの場合は `local_file` です。このフィールドがない項目は、エラーにならず無視されます。 url: type: string format: url description: '`remote_url` の項目で使うファイル URL です。' upload_file_id: type: string description: >- [ファイルをアップロード](/ja/3.13.x/develop/api/deployed-environments/upload-file) が返す `id` です。`transfer_method` が `local_file` の場合は必須です。 nullable: true description: >- ワークフローに渡すファイルです。ローカルファイルの場合は、まず [ファイルをアップロード](/ja/3.13.x/develop/api/deployed-environments/upload-file) でアップロードし、返された `id` を `upload_file_id` として `transfer_method: local_file` で指定します。 受け付けるかどうかは、許可するタイプや個数など、ワークフロー自身のファイル設定で決まります。ファイルを受け付けないワークフローでは、これらの項目は無視されます。 trace_id: type: string description: >- 可観測性データに伝播されるトレース識別子です。英数字、ハイフン、アンダースコアを 128 文字まで使用できます。条件に合わない値は、エラーにならず読み飛ばされます。 trace_session_id: type: string description: 可観測性データに伝播されるトレースセッション識別子です。前後の空白を除いて 1〜200 文字です。 minLength: 1 maxLength: 200 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 files: - type: image transfer_method: remote_url url: https://cloud.dify.ai/logo/logo-site.png blocking_example: summary: リクエスト例 - ブロッキングモード value: inputs: query: 'Translate this to French: Hello world' response_mode: blocking user: user_workflow_456 with_file_array_variable: summary: リクエスト例 - ファイル配列入力 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` パラメータに依存します。 - `response_mode` が `blocking` の場合、`application/json` で `WorkflowBlockingResponse` オブジェクトを返します。 - `response_mode` が `streaming` の場合、`text/event-stream` で `ChunkWorkflowEvent` オブジェクトのストリームを返します。 content: application/json: schema: type: object properties: task_id: type: string format: uuid description: >- この実行のタスク ID です。ブロッキングモードでは最後のボディにのみ含まれます。そのため [ワークフロータスクを停止](/ja/3.13.x/develop/api/deployed-environments/stop-workflow-task) が実用的なのは、ストリーミングの場合だけです。 workflow_run_id: type: string format: uuid description: このワークフロー実行の ID です。 data: type: object properties: id: type: string format: uuid description: ワークフロー実行 ID です。 workflow_id: type: string format: uuid description: ワークフロー ID です。 status: type: string description: >- `succeeded`、`failed`、`partial-succeeded`、`stopped` のいずれかです。 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 タイムスタンプです。 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: examples: streaming: summary: レスポンス例 - ストリーミングモード value: >+ event: ping data: {"event": "workflow_started", "task_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "workflow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "data": {"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "workflow_id": "b0e1d1a8-6c2f-4c8e-9d3e-1f2a3b4c5d6e", "inputs": {"query": "Summarize this text: The quick brown fox jumps over the lazy dog.", "sys.files": [], "sys.user_id": "user_workflow_123", "sys.app_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "sys.workflow_id": "b0e1d1a8-6c2f-4c8e-9d3e-1f2a3b4c5d6e", "sys.workflow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"}, "created_at": 1787788860, "reason": "initial"}} data: {"event": "text_chunk", "task_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "workflow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "data": {"text": "The sentence describes a fox jumping over a lazy dog.", "from_variable_selector": ["end", "result"]}} data: {"event": "workflow_finished", "task_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "workflow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "data": {"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "workflow_id": "b0e1d1a8-6c2f-4c8e-9d3e-1f2a3b4c5d6e", "status": "succeeded", "outputs": {"result": "The sentence describes a fox jumping over a lazy dog."}, "error": null, "elapsed_time": 1.2, "total_tokens": 31, "total_steps": 3, "created_by": {"id": "7d4e2f1b-8a9c-5b3d-9e6f-1a2b3c4d5e6f", "user": "user_workflow_123"}, "created_at": 1787788860, "finished_at": 1787788862, "exceptions_count": 0, "files": []}} schema: type: string description: >- サーバー送信イベント（SSE）のストリームです。解析は [ストリーミングレスポンスの処理](/ja/3.13.x/develop/api/guides/streaming) に従ってください。 **イベント**：最初に `workflow_started` が届きます。続いてノードイベントの `node_started`、`node_finished`、`node_retry`、およびイテレーションとループの各バリアントが届きます。`text_chunk` の差分はこれらと並行して届きます。`text_chunk` の差分を順番に連結すると出力になります。 最後のフレームは結果によって変わります。 - 成功、部分的な成功、または停止：`workflow_finished` の `status` がその結果を示します。 - ワークフローの失敗：`workflow_finished` のステータスは `failed` で、理由は `data.error` に入ります。 - ストリームが開いた後に判明した失敗（タイムアウト、取り消し、内部エラーなど）：`error` フレームが届き、ストリームが終了します。 ストリームが開く前の失敗は、ストリーミングモードでも通常の HTTP エラーレスポンスで返ります。500 `execution_failed` と 504 `request_timeout` は、ストリームが開いた後にしか発生しません。そのためストリーミングモードでは、HTTP ステータスではなく `error` フレームとして届きます。 **アドオン**：`ping` フレームはデータを持ちません。ストリームの開始時に 1 回届き、その後はおよそ 10 秒ごとに、出力の途中でも届きます。モデルが推論を出力する場合は、`reasoning_chunk` の差分がそれを運びます。 **共通フィールド**：`ping` と `error` を除く各イベントには `task_id` と `workflow_run_id` が含まれ、内容は `data` に入ります。 **`error` フレーム**：いずれも `workflow_run_id` に加えて、`code`、`status`、`message` を持ちます。 '400': description: >- - `invalid_param`：`inputs` または `user` がありません。`message` はそれぞれ `inputs is required`、`user is required` です。 - `invalid_param`：`response_mode` が `blocking` でも `streaming` でもありません。`message` は `response_mode must be blocking or streaming` です。 - `invalid_param`：`trace_session_id` の型または長さが条件を満たしません。`message` は `trace_session_id must be a string` または `trace_session_id must be 1 to 200 characters after trimming` です。 - `invalid_request`：リクエストボディを解析できませんでした。`message` は `invalid request body` です。 - `invalid_request`：API キーが Workflow 以外のアプリのものです。`message` は `run route does not match the deployed app mode` です。 - `invalid_request`：ファイル項目が検証に失敗しました。`message` に原因が入ります。たとえば `unsupported file type`、`too many files`、`invalid upload_file_id`、`declared file type does not match the file`、`file input takes a single file`、`file list input takes a list of files` です。 - `invalid_request`：`user` に NUL 文字が含まれています。`message` は `workflow file is invalid` です。 - `invalid_request`：`user` の先頭または末尾に空白文字があります。`message` は `workflow run identity is invalid` です。 - `invalid_request`：ボディが大きすぎると判断されました。`message` は `request payload is too large` です。 content: application/json: examples: invalid_param: summary: invalid_param value: code: invalid_param message: inputs is required status: 400 invalid_request: summary: invalid_request value: code: invalid_request message: run route does not match the deployed app mode status: 400 invalid_request_file: summary: invalid_request（ファイル項目） value: code: invalid_request message: declared file type does not match the file status: 400 '401': description: >- - `token_invalid`：API キーがない、形式が不正、または不明です。 - `unauthorized`：API キーが取り消されています。 - `runtime_identity_invalid`：リクエストの署名付き ID が、実行の受け付け前に期限切れになりました。アップロードに時間がかかると発生します。リクエストを送り直してください。 content: application/json: examples: token_invalid: summary: token_invalid value: code: token_invalid message: invalid api token status: 401 unauthorized: summary: unauthorized value: code: unauthorized message: Access token is invalid status: 401 runtime_identity_invalid: summary: runtime_identity_invalid value: code: runtime_identity_invalid message: runtime identity is invalid status: 401 '403': description: '`forbidden`：**アクセスポイント** で、アプリの API アクセスが無効になっています。' content: application/json: examples: forbidden: summary: forbidden value: code: forbidden message: The app's API service has been disabled. status: 403 '404': description: >- `not_found`：リクエストが `upload_file_id` で参照したファイルが存在しないか、別の `user` に属しています。 content: application/json: examples: not_found: summary: not_found value: code: not_found message: workflow file was not found status: 404 '409': description: >- - `request_canceled`：実行開始後に停止リクエストが届きましたが、実行は時間内に正常に終了しませんでした。それ以外の場合、停止した実行はステータス `stopped` で終了し、このエラーは返りません。 - `request_canceled`：実行中にデプロイが変更されたため、実行が取り消されました。現在のデプロイに対して再試行してください。 content: application/json: examples: request_canceled_mid_run: summary: request_canceled（停止） value: code: request_canceled message: request canceled status: 409 request_canceled_deployment_changed: summary: request_canceled（デプロイ変更） value: code: request_canceled message: deployment changed; retry against the current deployment status: 409 '413': description: >- `request_too_large`：リクエストボディが 8 MiB を超えています。実行中にもう一度サイズを検査し、同じメッセージを 400 `invalid_request` として返します。 content: application/json: examples: request_too_large: summary: request_too_large value: code: request_too_large message: request payload is too large status: 413 '429': description: '`queue_full`：環境の実行キューが満杯です。バックオフして再試行してください。' content: application/json: examples: queue_full: summary: queue_full value: code: queue_full message: worker queue is full status: 429 '500': description: >- - `execution_failed`：ワークフローを実行できませんでした。人間の入力が必要な手順に達した実行も、この形で失敗します。**呼び出しログ** で該当の実行を確認し、ワークフローを修正してから再試行してください。 - `internal_error`：リクエストの内容とは関係のないエラーが環境で発生しました。再試行し、それでも続く場合は管理者に連絡してください。 - `internal_error`：ブロッキングモードで、結果が返らないまま実行が終了しました。再試行し、それでも続く場合は管理者に連絡してください。 - `internal_server_error`：ストリーミングモードで、結果が返らないまま実行が終了しました。このエラーはストリーム内の `error` イベントとして返り、`status` は 500 です。再試行し、それでも続く場合は管理者に連絡してください。 content: application/json: examples: execution_failed: summary: execution_failed value: code: execution_failed message: workflow execution failed status: 500 execution_failed_request: summary: execution_failed（リクエスト失敗） value: code: execution_failed message: workflow request failed status: 500 internal_error: summary: internal_error value: code: internal_error message: internal error status: 500 internal_server_error: summary: internal_server_error value: code: internal_server_error message: Internal Server Error, please contact support. status: 500 '503': description: >- - `deployment_undeployed`：この環境からアプリがアンデプロイされています。 - `deployment_not_ready`：デプロイが進行中です。しばらくしてから再試行してください。 - `apprunner_not_deployed`：環境が利用できません。環境の削除中などに発生します。 - `enterprise_unavailable`：プラットフォーム側のルーティングサービスが一時的に利用できません。しばらくしてから再試行してください。 - `service_not_ready`：デプロイされたバージョンが、この環境で提供できる状態になっていません。しばらくしてから再試行してください。 - `service_not_ready`：`user` が 512 バイトを超えているか、実行が参照するファイルが重複を除いて 100 個を超えています。`message` は `run admission is temporarily unavailable` です。再試行しても解決しないため、`user` を短くするか、ファイル数を減らしてください。 content: application/json: examples: deployment_undeployed: summary: deployment_undeployed value: code: deployment_undeployed message: deployment is not deployed status: 503 deployment_not_ready: summary: deployment_not_ready value: code: deployment_not_ready message: deployment is in progress status: 503 apprunner_not_deployed: summary: apprunner_not_deployed value: code: apprunner_not_deployed message: apprunner not deployed for this environment status: 503 enterprise_unavailable: summary: enterprise_unavailable value: code: enterprise_unavailable message: enterprise routing service unavailable status: 503 service_not_ready: summary: service_not_ready value: code: service_not_ready message: revision is not serving status: 503 service_not_ready_admission: summary: service_not_ready（リクエスト過大） value: code: service_not_ready message: run admission is temporarily unavailable status: 503 '504': description: >- `request_timeout`：実行がプラットフォームのワークフロー実行の最大時間を超えたため、停止されました。この上限はプラットフォームの管理者が設定します。 content: application/json: examples: request_timeout: summary: request_timeout value: code: request_timeout message: request timed out status: 504 servers: - url: https://{deployed_api_base_url} description: >- すべてのデプロイ環境が共有するベース URL です。標準の Service API アドレスで `/v1` を `/v2` に置き換えたものです。 variables: deployed_api_base_url: default: api.example.com description: >- アプリの **アクセスポイント** タブで、いずれかのデプロイ環境の **バックエンドサービス API** カードから完全な URL をコピーし、先頭の `https://` と末尾の `/v2` を除いてください。 components: securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API_KEY description: >- すべてのリクエストは API キーで認証します：`Authorization: Bearer {API_KEY}`。アプリのエンドポイントにはアプリの API キーを、ナレッジのエンドポイントにはナレッジベースの API キーを使用します（[Dify API クイックスタート](/ja/3.13.x/develop/api/guides/get-started)）。 キーはサーバーサイドで保管し、クライアントコードには決して埋め込まないでください。キーが欠落または無効なリクエストは HTTP `401`（`unauthorized`）で失敗します。 ````