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

# 执行工作流

> 执行工作流。没有已发布的工作流时无法执行。



## OpenAPI

````yaml /zh/api-reference/openapi_workflow.json post /workflows/run
openapi: 3.0.1
info:
  title: 工作流应用 API
  description: 工作流应用提供无会话支持，适用于翻译、文章写作、摘要 AI 等场景。
  version: 1.0.0
servers:
  - url: https://{api_base_url}
    description: 工作流应用 API 的基础 URL。自托管部署时，替换为你的 API 基础 URL。
    variables:
      api_base_url:
        default: api.dify.ai/v1
        description: API 基础 URL 的主机与路径，不含 `https://` 前缀。
security:
  - ApiKeyAuth: []
tags:
  - name: 工作流
    description: 用于执行和管理工作流的操作。
  - name: 文件操作
    description: 文件上传和下载操作。
  - name: 终端用户
    description: 终端用户信息相关操作。
  - name: 语音与文字转换
    description: 语音转文字和文字转语音转换。
  - name: 应用配置
    description: 应用设置、参数和元数据。
  - name: 人工介入
    description: 暂停等待人工输入的工作流恢复操作。
paths:
  /workflows/run:
    post:
      tags:
        - 工作流
      summary: 执行工作流
      description: 执行工作流。没有已发布的工作流时无法执行。
      operationId: executeWorkflowCn
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowExecutionRequest'
            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
              blocking_example:
                summary: 请求示例 - 阻塞模式
                value:
                  inputs:
                    query: 'Translate this to French: Hello world'
                  response_mode: blocking
                  user: user_workflow_456
              with_file_array_variable:
                summary: Request Example - File array input
                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:
                $ref: '#/components/schemas/WorkflowBlockingResponse'
              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:
              schema:
                type: string
                description: >-
                  服务器发送事件 (SSE) 流。


                  **解析**：每行以 `data: ` 开头，后接一个 JSON 对象，以 `\n\n` 终止。解析 JSON 前先去除
                  `data: ` 前缀，再读取 `event` 字段确定事件类型。忽略 `ping` 事件，该事件每 10
                  秒发送一次以保持连接活跃。


                  **流生命周期**：收到 `workflow_finished`、`workflow_paused` 或 `error`
                  事件时流关闭。错误以流内 `error` 事件的形式返回，HTTP 状态码始终为
                  `200`；请检查事件载荷获取详情，不要依赖状态码判断。


                  **人工介入事件**：

                  - `human_input_required`：工作流到达人工介入节点时与 `workflow_paused`
                  一同触发。使用载荷中的 `form_token` 通过 [人工介入
                  API](/api-reference/人工介入/获取人工介入表单) 处理表单。

                  - `human_input_form_filled`：接收者提交了表单，工作流恢复执行。

                  - `human_input_form_timeout`：表单超时未响应。如定义了超时回退分支，工作流将沿该分支执行。
              examples:
                streamingResponse:
                  summary: 响应示例 - 流式模式
                  value: >-
                    data: {"event": "workflow_started", "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", "inputs": {"query":
                    "Translate this"}, "created_at": 1705407629, "reason":
                    "initial"}} data: {"event": "node_started", "task_id":
                    "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id":
                    "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": {"id":
                    "node_exec_1", "node_id": "node_1", "node_type": "llm",
                    "title": "LLM Node", "index": 1, "created_at": 1705407629}}
                    data: {"event": "text_chunk", "task_id":
                    "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id":
                    "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": {"text":
                    "Bonjour", "from_variable_selector": ["node_1", "text"]}}
                    data: {"event": "workflow_finished", "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"},
                    "elapsed_time": 1.23, "total_tokens": 150, "total_steps": 3,
                    "created_at": 1705407629, "finished_at": 1705407630}}
                humanInputPause:
                  summary: 响应示例 - 人工介入暂停
                  value: >-
                    data: {"event": "workflow_started", "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", "inputs": {"draft":
                    "Hello"}, "created_at": 1705407629, "reason": "initial"}}
                    data: {"event": "human_input_required", "task_id":
                    "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id":
                    "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": {"form_id":
                    "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "form_token":
                    "tok_abc123", "node_id": "approval_node", "node_title":
                    "Approval", "form_content": "Please review the draft.",
                    "inputs": [{"type": "text_input", "output_variable_name":
                    "comment", "default": null}], "actions": [{"id": "approve",
                    "title": "Approve", "button_style": "primary"}],
                    "display_in_ui": false, "resolved_default_values":
                    {"comment": ""}, "expiration_time": 1705494029}} data:
                    {"event": "workflow_paused", "task_id":
                    "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id":
                    "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data":
                    {"workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156",
                    "status": "paused", "created_at": 1705407629,
                    "elapsed_time": 0.5}}
        '400':
          description: |-
            - `not_workflow_app` : App mode does not match the API route.
            - `provider_not_initialize` : 未找到有效的模型提供商凭据。
            - `provider_quota_exceeded` : 模型提供商配额已用尽。
            - `model_currently_not_support` : 当前模型不可用。
            - `completion_request_error` : 工作流 execution request failed.
            - `invalid_param` : Invalid parameter value.
          content:
            application/json:
              examples:
                not_workflow_app:
                  summary: not_workflow_app
                  value:
                    status: 400
                    code: not_workflow_app
                    message: Please check if your app mode matches the right API route.
                provider_not_initialize:
                  summary: provider_not_initialize
                  value:
                    status: 400
                    code: provider_not_initialize
                    message: >-
                      No valid model provider credentials found. Please go to
                      Settings -> Model Provider to complete your provider
                      credentials.
                provider_quota_exceeded:
                  summary: provider_quota_exceeded
                  value:
                    status: 400
                    code: provider_quota_exceeded
                    message: >-
                      Your quota for Dify Hosted OpenAI has been exhausted.
                      Please go to Settings -> Model Provider to complete your
                      own provider credentials.
                model_currently_not_support:
                  summary: model_currently_not_support
                  value:
                    status: 400
                    code: model_currently_not_support
                    message: >-
                      Dify Hosted OpenAI trial currently not support the GPT-4
                      model.
                completion_request_error:
                  summary: completion_request_error
                  value:
                    status: 400
                    code: completion_request_error
                    message: Completion request failed.
                invalid_param:
                  summary: invalid_param
                  value:
                    status: 400
                    code: invalid_param
                    message: Arg user must be provided.
        '429':
          description: |-
            - `too_many_requests` : 该应用的并发请求过多。
            - `rate_limit_error` : 上游模型提供商的速率限制已超出。
          content:
            application/json:
              examples:
                too_many_requests:
                  summary: too_many_requests
                  value:
                    status: 429
                    code: too_many_requests
                    message: Too many requests. Please try again later.
                rate_limit_error:
                  summary: rate_limit_error
                  value:
                    status: 429
                    code: rate_limit_error
                    message: Rate Limit Error
        '500':
          description: '`internal_server_error` : 内部服务器错误。'
          content:
            application/json:
              examples:
                internal_server_error:
                  summary: internal_server_error
                  value:
                    status: 500
                    code: internal_server_error
                    message: Internal Server Error.
components:
  schemas:
    WorkflowExecutionRequest:
      type: object
      required:
        - inputs
        - user
      properties:
        inputs:
          type: object
          description: >-
            工作流输入变量的键值对。文件类型变量的值应为文件对象数组，包含 `type`、`transfer_method` 以及 `url` 或
            `upload_file_id`。请参阅 [获取应用参数](/api-reference/应用配置/获取应用参数) 响应中的
            `user_input_form` 字段，以了解应用所需的变量名称和类型。
          additionalProperties:
            oneOf:
              - type: string
              - type: number
              - type: boolean
              - type: object
              - type: array
                items:
                  $ref: '#/components/schemas/InputFileObject'
        response_mode:
          type: string
          enum:
            - streaming
            - blocking
          description: >-
            响应模式。使用 `blocking` 获取同步响应（Cloudflare 超时时间为 `100 s`），使用 `streaming`
            获取服务器发送事件。未指定时默认为阻塞模式。
        user:
          type: string
          description: >-
            用户标识符，由开发者自定义规则，在应用内必须唯一。此标识符用于限定数据访问范围——工作流运行和文件仅在使用相同的 `user`
            值查询时可见。
        files:
          type: array
          items:
            $ref: '#/components/schemas/InputFileObject'
          nullable: true
          description: >-
            文件列表。适用于需要将文件与文本组合输入的场景，仅在模型支持 Vision 能力时可用。要附加本地文件，请先通过
            [上传文件](/api-reference/文件操作/上传文件) 上传，然后将返回的 `id` 作为
            `upload_file_id`，并设置 `transfer_method: local_file`。
    WorkflowBlockingResponse:
      type: object
      properties:
        task_id:
          type: string
          format: uuid
          description: >-
            进行中的执行任务 ID。配合 [停止工作流任务](/api-reference/工作流/停止-工作流-任务)
            使用以取消运行中的工作流。仅在执行期间有效。
        workflow_run_id:
          type: string
          format: uuid
          description: >-
            此工作流运行记录的持久化标识符。配合 [获取工作流运行详情](/api-reference/工作流/获取-工作流-执行情况)
            使用以在执行后获取结果。
        data:
          $ref: '#/components/schemas/WorkflowFinishedData'
    InputFileObject:
      type: object
      required:
        - type
        - transfer_method
      properties:
        type:
          type: string
          enum:
            - document
            - image
            - audio
            - video
            - custom
          description: 文件类型。
        transfer_method:
          type: string
          enum:
            - remote_url
            - local_file
          description: 传输方式：文件 URL 使用 `remote_url`，上传文件使用 `local_file`。
        url:
          type: string
          format: url
          description: 文件 URL（当 `transfer_method` 为 `remote_url` 时）。
        upload_file_id:
          type: string
          description: >-
            通过 [上传文件](/api-reference/文件操作/上传文件) API 获取的已上传文件 ID（当
            `transfer_method` 为 `local_file` 时使用）。
    WorkflowFinishedData:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: 工作流运行 ID。
        workflow_id:
          type: string
          format: uuid
          description: 工作流 ID.
        status:
          type: string
          description: >-
            工作流执行状态。`running` 表示执行中，`succeeded` 表示成功完成，`failed` 表示执行出错，`stopped`
            表示手动停止，`partial-succeeded` 表示部分节点成功但其他失败，`paused` 表示等待人工介入。
        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 时间戳。
        created_by:
          type: object
          additionalProperties: true
          description: 创建者信息。仅存在于流式 `workflow_finished` 事件中。
        exceptions_count:
          type: integer
          nullable: true
          description: 执行过程中遇到的异常数量。仅在流式 `workflow_finished` 事件中出现。
        files:
          type: array
          items:
            type: object
            additionalProperties: true
          nullable: true
          description: 工作流执行期间生成的文件。仅存在于流式 `workflow_finished` 事件中。
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API_KEY
      description: >-
        API Key 认证。对于所有 API 请求，请在 `Authorization` HTTP 头中包含您的 API Key，并加上
        `Bearer ` 前缀。示例：`Authorization: Bearer {API_KEY}`。**强烈建议将 API Key
        存储在服务端，不要在客户端共享或存储，以避免 API Key 泄漏导致严重后果。**

````