按 ID 执行工作流

post/workflows/{workflow_id}/run

Request example

curl --request POST \
  --url https://api.dify.ai/v1/workflows/{workflow_id}/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "inputs": {
    "query": "Summarize this article"
  },
  "response_mode": "blocking",
  "user": "user_workflow_123"
}'

import requests

url = "https://api.dify.ai/v1/workflows/{workflow_id}/run"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
}
payload = {
    "inputs": {
        "query": "Summarize this article"
    },
    "response_mode": "blocking",
    "user": "user_workflow_123"
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

const response = await fetch('https://api.dify.ai/v1/workflows/{workflow_id}/run', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "inputs": {
      "query": "Summarize this article"
    },
    "response_mode": "blocking",
    "user": "user_workflow_123"
  })
});

const data = await response.json();
console.log(data);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.dify.ai/v1/workflows/{workflow_id}/run',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{
  "inputs": {
    "query": "Summarize this article"
  },
  "response_mode": "blocking",
  "user": "user_workflow_123"
}',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <token>',
    'Content-Type: application/json',
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://api.dify.ai/v1/workflows/{workflow_id}/run"
	payload := strings.NewReader("{\n  \"inputs\": {\n    \"query\": \"Summarize this article\"\n  },\n  \"response_mode\": \"blocking\",\n  \"user\": \"user_workflow_123\"\n}")

	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dify.ai/v1/workflows/{workflow_id}/run"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"inputs\": {\n    \"query\": \"Summarize this article\"\n  },\n  \"response_mode\": \"blocking\",\n  \"user\": \"user_workflow_123\"\n}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

require 'uri'
require 'net/http'

url = URI('https://api.dify.ai/v1/workflows/{workflow_id}/run')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'

request = Net::HTTP::Post.new(url)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = '{
  "inputs": {
    "query": "Summarize this article"
  },
  "response_mode": "blocking",
  "user": "user_workflow_123"
}'

response = http.request(request)
puts response.read_body

Response

{
  "data": {
    "created_at": 1705407629,
    "elapsed_time": 2.45,
    "error": null,
    "finished_at": 1705407631,
    "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156",
    "outputs": {
      "result": "Article summary here"
    },
    "status": "succeeded",
    "total_steps": 4,
    "total_tokens": 280,
    "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345"
  },
  "task_id": "c3800678-a077-43df-a102-53f23ed20b88",
  "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156"
}

event: ping

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": "请审阅草稿。", "inputs": [{"type": "paragraph", "output_variable_name": "comment", "default": null}], "actions": [{"id": "approve", "title": "批准", "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}}

event: ping

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": "reasoning_chunk", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": {"reasoning": "Let me translate that.", "node_id": "node_1", "is_final": false}}

data: {"event": "reasoning_chunk", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": {"reasoning": "", "node_id": "node_1", "is_final": true}}

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}}

{
  "code": "bad_request",
  "message": "Cannot use draft workflow version. Workflow ID: 7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345. Please use a published workflow version or leave workflow_id empty.",
  "status": 400
}

{
  "code": "completion_request_error",
  "message": "Completion request failed.",
  "status": 400
}

{
  "code": "invalid_param",
  "message": "Arg user must be provided.",
  "status": 400
}

{
  "code": "model_currently_not_support",
  "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model.",
  "status": 400
}

{
  "code": "not_workflow_app",
  "message": "Please check if your app mode matches the right API route.",
  "status": 400
}

{
  "code": "provider_not_initialize",
  "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.",
  "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.",
  "status": 400
}

{
  "code": "trigger_workflow_service_mode_unavailable",
  "message": "This workflow uses a trigger entry and cannot be invoked through Web App, Service API, OpenAPI, or MCP.",
  "status": 403
}

{
  "code": "workflow_version_execution_not_allowed",
  "message": "Workflow version execution is not available on your current plan. Please upgrade to a paid plan.",
  "status": 403
}

{
  "code": "not_found",
  "message": "Workflow not found with id: 7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345",
  "status": 404
}

{
  "code": "rate_limit_error",
  "message": "Workflow execution quota limit reached for tenant 8f1e2a90-3b7c-4d55-9a01-6c2f4e8b1d33",
  "status": 429
}

{
  "code": "too_many_requests",
  "message": "Too many requests. Please try again later.",
  "status": 429
}

{
  "code": "internal_server_error",
  "message": "Internal Server Error.",
  "status": 500
}

post/workflows/{workflow_id}/run

Authorization

Authorizationstringheaderrequired#

每个请求都通过 API Key 认证：Authorization: Bearer {API_KEY}。应用接口使用应用 API Key，知识库接口使用知识库 API Key（快速开始）。

API Key 应保存在服务端，切勿嵌入客户端代码。缺失或无效的 Key 会返回 HTTP 401（unauthorized）。

Path parameters

workflow_idstringrequired#

要运行的已发布工作流版本。在执行工作流响应和获取工作流运行详情的 workflow_id 字段中返回。必须指向已发布版本；草稿版本 ID 会返回 bad_request。

Body

application/json

filesobject[]#

文件列表。适用于需要将文件与文本组合输入的场景，仅在模型支持 Vision 能力时可用。要附加本地文件，请先通过上传文件上传，然后将返回的 id 作为 upload_file_id，并设置 transfer_method: local_file。

Show child attributes

Any of

transfer_methodenum<string>#

Options:remote_url

urlstringrequired#

transfer_methodenum<string>#

Options:local_file

upload_file_idstringrequired#

inputsobjectrequired#

工作流输入变量的键值对。变量名称和类型可从获取应用参数响应中的 user_input_form 字段获取。

文件类型变量的值为文件对象数组，包含 type、transfer_method 以及 url 或 upload_file_id。

Show child attributes

{key}string · number · boolean · object · object[]#

Show child attributes

One of

Any of

transfer_methodenum<string>#

Options:remote_url

urlstringrequired#

transfer_methodenum<string>#

Options:local_file

upload_file_idstringrequired#

response_modeenum<string>#

响应模式。使用 blocking 获取同步响应（Cloudflare 超时时间为 100 s），使用 streaming 获取服务器发送事件。未指定时默认为阻塞式返回。

Options:streamingblocking

userstringrequired#

终端用户标识，由你的应用定义，需在应用内唯一。用于限定数据访问范围：工作流运行及其文件仅对携带相同 user 的后续请求可见。参见终端用户身份。

Responses

请求成功。内容类型和结构取决于请求中的 response_mode 参数。

如果 response_mode 为 blocking，返回 application/json 和 WorkflowBlockingResponse 对象。
如果 response_mode 为 streaming，返回 text/event-stream 和 ChunkWorkflowEvent 对象流。

dataobject#

Show child attributes

created_atinteger#

工作流运行创建时的 Unix 时间戳。

created_byobject#

创建者信息。仅存在于流式 workflow_finished 事件中。

elapsed_timenumber#

总耗时（秒）。

errorstring#

工作流失败时的错误消息。

exceptions_countinteger#

执行过程中遇到的异常数量。仅在流式 workflow_finished 事件中出现。

filesobject[]#

工作流执行期间生成的文件。仅存在于流式 workflow_finished 事件中。

finished_atinteger#

工作流运行结束时的 Unix 时间戳。

idstring#

工作流运行 ID。

outputsobject#

工作流的输出数据。

statusstring#

工作流执行状态。running 表示执行中，succeeded 表示成功完成，failed 表示执行出错，stopped 表示手动停止，partial-succeeded 表示部分节点成功但其他失败，paused 表示等待人工介入。

total_stepsinteger#

已执行的工作流总步数。

total_tokensinteger#

所有节点消耗的总令牌数。

workflow_idstring#

工作流 ID.

task_idstring#

进行中的执行任务 ID。配合停止工作流任务使用以取消运行中的工作流。仅在执行期间有效。

workflow_run_idstring#

此工作流运行记录的持久化标识符。配合获取工作流运行详情使用以在执行后获取结果。

执行工作流停止工作流任务