HandyLay
打开规划器

HandyLay API

HandyLay 提供一个公开的 HTTP 地址，可以为你描述的房间规划瓷砖或地板的排版。返回内容包括该排版需要多少块、其中整块和切割块各有多少、有多少材料最终成为边角料、一张等比平面图，以及一个能在规划器里打开该方案的链接。不需要密钥，也不需要账号。

整个 API 就是一个地址

请求是普通的 GET，因此可以直接粘贴到浏览器里，也可以交给能够抓取网页的助手。下面这个地址为 420 × 360 cm 的房间规划 60 × 60 cm 的瓷砖，填缝 2 mm。

GET https://handylay.app/api/plan?outline=E420 S360 W420 N360&pattern=squares&tileSize=600&joint=2

带缺角或壁龛的房间写法相同，只是绕行更长。这个例子是一个 L 形房间，中间有 40 × 40 cm 的柱子，用 90 × 600 mm 的板材铺人字拼。

GET https://handylay.app/api/plan?outline=E500 S300 W200 S200 W300 N500&subtract=200,150,40,40&pattern=herringbone&tileWidth=90&tileHeight=600

同样的字段也可以作为 JSON 请求体通过 POST 发送，便于从代码中调用。

POST /api/plan

房间用厘米，砖块用毫米

房间尺寸和起铺点使用厘米，砖块尺寸和填缝宽度使用毫米。这样划分对应这些数字的来源：墙是用卷尺量的，砖块尺寸则来自厂商的规格表。

单位写错不会有任何提示，因为 20 mm 的砖和 200 mm 的砖同样合法。当结果看起来离谱时，这通常是第一个该检查的地方。

房间通过绕墙一周来描述

outline 参数按经过顺序列出每面墙。每面墙由方向和长度（厘米）组成：E 向右、S 向下、W 向左、N 向上。420 × 360 cm 的矩形写作 E420 S360 W420 N360。

绕行必须回到起点，否则响应会说明差了多少。L 形房间是 E500 S300 W200 S200 W300 N500，其他由直墙组成的形状同样通过继续追加线段得到。斜墙写作 A 方位角 冒号 长度，方位角以正东为零、顺时针计算度数。

柱子、管井等开口用 subtract 参数中的矩形扣除。无法用绕行描述的房间，可以直接在 polygon 参数中给出顶点列表。

除房间描述外，其余都是可选的

不在下列名单中的名称会作为排版自身的参数传入，例如人字拼的 tileWidth。这份名单从哪里获取，见下文关于排版的章节。

名称含义
outline按绕行顺序列出的房间墙面，例如 E420 S360 W420 N360。
polygon轮廓顶点，写成以空格分隔的 x,y 对。可替代 outline。
holes地面上的洞，写法同 polygon；多个环用分号分隔。
subtract矩形开口，格式为 x,y,宽,高（厘米），多个用分号分隔。
pattern要铺的排版方式。默认 squares。
joint填缝宽度（毫米）。默认使用该排版自带的值。
color整个图案中所有砖块使用的同一个十六进制颜色。
gapColor填缝颜色，十六进制。
start起铺点，格式 x,y（厘米）。这个参数决定靠墙处的切割如何落位。
width图纸宽度（像素）。
walls在房间四周绘制墙体带和墙长标注。默认开启。
formatjson 返回数字，svg 返回图纸本身。
inlineSvg把图纸一并放进 JSON 响应。
credit图纸边缘的 handylay.app 署名。默认开启。
link生成规划器链接。比较不同方案时可关闭。
lang排版名称和规划器链接的语言：en、pl、es 或 zh。

响应带回的是数字，不只是一张图

默认返回 JSON。图纸在其中是一个地址而不是内容，这样读响应时不必翻过几千字节的标记。inlineSvg 参数会把它嵌入进来，format=svg 则从同一地址只返回图片。

warnings 字段是把方案交给别人之前最该处理的部分。它会指出靠墙处出现了无法使用的窄条，或者损耗偏高。把 start 移动半块砖再问一次，通常就能解决。

名称含义
surface.areaM2扣除开口后的地面面积，单位平方米。
surface.perimeterM房间周长，单位米。
surface.wallsCm各面墙的长度（厘米），按顺序排列。
pattern.parameters实际使用的排版参数，包含默认值。
pattern.jointMm填缝宽度（毫米）。
pattern.startCm排版起铺点（厘米）。
tiles.total该排版需要购买的砖块数量。
tiles.whole其中整块铺设的数量。
tiles.cut其中需要切割的数量。
tiles.wastePercent所购材料中最终成为边角料的比例。
tiles.narrowestCutMm所有切割块中最短的一边。数值很小说明出现了窄条。
tiles.sliverCount切下来不足整块十分之一的数量。
warnings这个排版有什么问题，以及通常怎样解决。
svgUrl同一张图纸的独立地址。
plannerUrl在规划器中打开完成的方案，可在其中拖动起铺点。
GET https://handylay.app/api/plan?outline=E420 S360 W420 N360&pattern=bricks&format=svg

每种排版都会自述参数

每种排版有自己的参数：人字拼接受 tileWidth、tileHeight 和 direction。与其猜测名称，不如从另一个地址获取，它会列出全部排版及其取值范围、默认值和已翻译的标签。

GET /api/plan/patterns

目前可用的排版：

  • squares-pattern
  • bricks-pattern
  • vertical-bricks-pattern
  • hexagons-pattern
  • flat-top-hexagons-pattern
  • diamonds-pattern
  • rhombus-pattern
  • isometric-cubes-pattern
  • herringbone-pattern
  • chevron-pattern

不需要密钥，但有额度限制

这个接口是开放的，因为顺着链接过来的助手没有地方保存密钥。控制成本的是输入上限：单个方案最多 20 000 块、绕行最多 64 面墙、最多 32 个开口，以及房间面积的上限。超出任何一项都会返回一条说明该改传什么的消息。

同一地址的请求限制为每分钟三十次。比较多个起铺点时请加上 link=false，因为每个返回规划器链接的请求都会存储一个项目。链接只从最终要交出去的那次调用中获取。

机器可读的描述放在两个地址

OpenAPI 描述用于把这个接口接成助手或自有代码中的工具。llms.txt 文件概括了 HandyLay 是什么、这个 API 能做什么，其形式专为模型阅读而写。