通过 API 调用工作流

将 AI 编程生成的工作流部署为 API 服务后，你可以通过 HTTP 请求在自己的应用或网页中调用该工作流，从而集成对应的 AI 能力。
部署后，扣子编程会为工作流生成一组固定的 API 接口，例如同步执行、流式执行、异步执行、查询异步任务状态和查询工作流参数。 这些接口：

• 鉴权方式、请求路径、任务状态字段、流式事件字段等由扣子编程提供，属于固定协议。
• 接口中的工作流输入参数和工作流输出参数由当前工作流自动生成，属于动态 schema。
  不同工作流的入参、出参可能不同，请以部署页面展示的参数说明为准。

接入准备

部署工作流

已将 AI 编程生成的工作流部署为 API 服务。详情请参见部署工作流。
部署成功后，扣子编程会自动生成 API 服务。你可以在部署总览页面查看 API 请求地址、请求 Header、请求参数示例，并创建用于鉴权的 API Token。

查看 API 访问信息

获取该服务的 API 访问地址、请求Header、请求参数等详细信息。

1. 在工作流开发页面，在右侧单击➕打开新的标签页，在弹出的标签页中选择部署。
2. 在部署的总览页面，单击某条部署记录右侧的更多按钮，选择查看。
3. 在API 请求示例及接口说明页面，查看该服务的 API 访问信息。
   

创建 API Token

调用 API 前，你需要创建 API Token，并在请求 Header 中通过 Authorization 传入。

1. 在工作流开发页面，在右侧单击➕打开新的标签页，在弹出的标签页中选择部署。
2. 在部署的总览页面，单击某条部署记录右侧的更多按钮，选择查看。
3. 在API 请求示例及接口说明页面，单击查看 API Token，单击管理 API Token 生成新的 API Token。复制并妥善保存 API Token。

API 接口说明

选择 API 接口

同步执行工作流

同步执行接口会在工作流执行完成后一次性返回最终结果。建议将工作流执行时间控制在 5 分钟，也就是 300 秒以内。如果服务器在 300 秒内未返回响应，连接可能因超时而中断。
对于生图、渲染等执行耗时较长的工作流，建议优先使用流式执行接口，以便持续接收进度事件并降低连接中断风险。

请求示例

你可以在部署页面复制 Curl、Python 或 Node.js 调用示例。以下示例展示如何使用 Curl 调用同步执行接口：

curl --location 'https://<your_domain>/run' \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{"trigger_source":""}'

其中，请将：

• <your_domain> 替换为部署页面提供的 API 服务域名。
• <YOUR_API_TOKEN> 替换为你创建的 API Token。
• –data 中的参数替换为当前工作流实际需要的输入参数。工作流输入参数由 AI 编程根据当前工作流自动生成，不同工作流可能不同。

返回示例

同步执行接口返回工作流的最终输出，其数据结构与工作流中定义的输出参数保持一致。

{
  "send_status": "success",
  "top3_news_text": "..."
}

返回字段说明

流式执行工作流

流式执行接口会以 Server-Sent Events（SSE）格式持续返回事件。你可以逐条解析事件，获取工作流的开始、结束和最终完成结果的事件信息。

请求示例

你可以在部署页面复制 Curl、Python 或 Node.js 调用示例。以下示例展示如何使用 Curl 调用接口：

curl --location 'https://<your_domain>/stream_run' \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{"trigger_source":""}'

其中，请将：

• <your_domain> 替换为部署页面提供的 API 服务域名。
• <YOUR_API_TOKEN> 替换为你创建的 API Token。
• –data 中的参数替换为当前工作流实际需要的输入参数。工作流输入参数由 AI 编程根据当前工作流自动生成，不同工作流可能不同。

如果需要获取节点开始和节点结束事件，请添加以下 Header：

--header 'x-workflow-stream-mode: debug'

返回示例

id: 0
event: message
data: {"type":"node_start","timestamp":1768877934224,"log_id":"","run_id":"1878882f-f2c5-4572-9138-9a0f7b8c****","node_name":"calculator","input":{"a":1.0,"b":2.0}}

id: 1
event: message
data: {"type":"node_end","timestamp":1768877935232,"log_id":"","run_id":"1878882f-f2c5-4572-9138-9a0f7b8c****","node_name":"send_feishu_message","output":{"send_status":"success"},"time_cost_ms":1008}

id: 2
event: message
data: {"type":"workflow_end","timestamp":1768877936246,"log_id":"","run_id":"1878882f-f2c5-4572-9138-9a0f7b8c****","output":{"send_status":"success","top3_news_text":"..."},"time_cost_ms":2024}

事件字段说明

其中，data 是流式接口的固定事件载体。data.output 中的业务字段由当前工作流或节点的输出参数决定，不同工作流可能不同。

异步执行工作流

异步执行接口会创建一个异步执行任务，并立即返回任务信息。调用端不需要一直保持连接，可以后续通过任务 ID 查询执行状态和结果。

请求示例

你可以在部署页面复制 Curl、Python 或 Node.js 调用示例。以下示例展示如何使用 Curl 调用接口：

curl --location 'https://<your_domain>/async_run' \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{"trigger_source":""}'

其中，请将：

• <your_domain> 替换为部署页面提供的 API 服务域名。
• <YOUR_API_TOKEN> 替换为你创建的 API Token。
• –data 中的参数替换为当前工作流实际需要的输入参数。工作流输入参数由 AI 编程根据当前工作流自动生成，不同工作流可能不同。

返回示例

{
  "task_id": "6a5fa5ade320435a9c44fd5052a3****",
  "status": "pending",
  "created_at": "2026-05-25T15:16:10.151364+08:00",
  "deadline": "2026-05-25T15:31:10.151364+08:00"
}

返回字段说明

查询异步执行任务状态

调用异步执行接口后，你可以使用 task_id 查询任务状态。任务完成后，接口会返回执行结果；任务失败时，接口会返回错误信息。

请求示例

curl --location --request GET 'https://<your_domain>/task/{task_id}' \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>'

其中，请将：

• <your_domain> 替换为部署页面提供的 API 服务域名。
• <YOUR_API_TOKEN> 替换为你创建的 API Token。
• {task_id} 替换为调用 /async_run 后返回的任务 ID。

返回示例

{
    "task_id": "73ba04190aa442f49155ead7fbc1****",
    "status": "running",
    "claim_count": 1,
    "created_at": "2026-05-19T06:12:49.581991+00:00",
    "started_at": "2026-05-19T06:12:49.602150+00:00",
    "completed_at": null,
    "heartbeat_at": "2026-05-19T06:23:19.947105+00:00",
    "deadline": "2026-05-20T06:12:49.577465+00:00",
    "result": null,
    "error": null
}

{
    "task_id": "73ba04190aa442f49155ead7fbc1****",
    "status": "completed",
    "claim_count": 1,
    "created_at": "2026-05-19T06:12:49.581991+00:00",
    "started_at": "2026-05-19T06:12:49.602150+00:00",
    "completed_at": "2026-05-19T06:32:49.697434+00:00",
    "heartbeat_at": null,
    "deadline": "2026-05-20T06:12:49.577465+00:00",
    "result": {
        "sum_result": 21.0
    },
    "error": null
}

返回字段说明

异步任务状态说明

查询工作流参数

查询工作流参数接口用于获取工作流的输入参数和输出参数 schema。调用工作流前，你可以先通过该接口确认请求体中需要传入哪些字段，以及每个字段的数据类型。

请求示例

curl --location 'https://<your_domain>/graph_parameter' \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>'

其中，请将：

• <your_domain> 替换为部署页面提供的 API 服务域名。
• <YOUR_API_TOKEN> 替换为你创建的 API Token。

返回示例

{
  "input_schema": {
    "description": "工作流输入——定时触发",
    "properties": {
      "trigger_source": {
        "default": "cron",
        "description": "触发来源，默认定时任务触发",
        "title": "Trigger Source",
        "type": "string"
      }
    },
    "title": "GraphInput",
    "type": "object"
  },
  "output_schema": {
    "description": "工作流的输出",
    "properties": {
      "send_status": {
        "description": "飞书消息发送状态",
        "title": "Send Status",
        "type": "string"
      },
      "top3_news_text": {
        "description": "推送的3条关键新闻内容",
        "title": "Top3 News Text",
        "type": "string"
      }
    },
    "required": ["send_status", "top3_news_text"],
    "title": "GraphOutput",
    "type": "object"
  }
}

返回字段说明

故障排查

如果 API 调用失败，请按以下方向排查：

• 如果同步执行接口超时，确认工作流是否执行时间过长。对于耗时较长的工作流，建议改用 /stream_run 或 /async_run。
• 如果使用流式执行接口，确认调用端是否支持 SSE，并已按事件流格式逐条解析返回内容。
• 如果异步任务的 heartbeat_at 长时间未更新，或者 status 长时间保持 pending，大概率是沙箱实例过载。此时建议重新发起异步执行任务。
• 将错误码、错误信息或接口返回内容提供给 AI 编程，以便进一步定位和修复问题。