SmartCut

SmartCut API

SmartCut 是一款托管式切割优化（切割清单 / 排样）API，适用于板材、线性材料和卷材。本仓库包含 OpenAPI 规范、可运行示例以及 MCP 配置，方便将其集成到你自己的软件中。

功能介绍

• 板材优化 — 提供用于胶合板、中密度纤维板、玻璃、塑料和钣金的闯切模式（从边到边、适合锯切）和效率模式。
• 线性（1D）优化，适用于木材、棒材、管材和挤压型材。
• 真实形状排样，针对从 DXF 导入的不规则零件，适用于激光、等离子、水刀和 CNC 路由加工。
• 纹理方向和单个零件的方向锁定，可将零件固定为沿纹理长度或宽度方向，也可允许自由旋转。
• 封边、表面处理、锯缝和库存裁边均作为一等输入处理，无需后期处理。
• 可直接用于机器的导出文件 — PDF、CSV、DXF、SVG，以及原生锯床格式，包括 PTX（Homag）、Biesse XML 和 Mayer .may。
• 根据同一计算结果生成可打印的零件标签。

快速入门

在 https://smartcut.dev/account 获取密钥，然后：

curl -X POST https://api.smartcut.dev/v3/calculate \
  -H "Authorization: $SMARTCUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d @examples/requests/guillotine.json

这会返回一个作业 ID。轮询直到作业就绪，然后获取结果：

curl "https://api.smartcut.dev/v3/result/ready?id=$JOB_ID" -H "Authorization: $SMARTCUT_API_KEY"
curl "https://api.smartcut.dev/v3/result?id=$JOB_ID"       -H "Authorization: $SMARTCUT_API_KEY"

结果中每块库存材料对应一条记录，列出放置在其上的零件及其位置、所需的切割操作，以及剩余的边角料。examples/ 中提供了四种语言的完整可运行示例。

身份验证

在 Authorization 标头中传入原始 API 密钥：

Authorization: YOUR_API_KEY

不要加上 Bearer 前缀。 这是最常见的集成错误——添加 Bearer 前缀会返回 401。

端点（v3）

method	path	what it does	sync
POST	/v3/calculate	提交计算	异步
POST	/v3/validate	验证输入但不执行计算	同步
POST	/v3/model/analysis	将 3D 模型分析为零件	同步
GET	/v3/result/ready	检查计算是否完成	同步
GET	/v3/result	获取计算结果	同步
GET	/v3/export/pdf	将结果导出为 PDF	同步
GET	/v3/export/csv	将结果导出为 CSV	同步
GET	/v3/export/ptx	将结果导出为 PTX	同步
GET	/v3/export/dxf	将结果导出为 DXF	同步
GET	/v3/export/svg	将结果导出为 SVG	同步
GET	/v3/export/mayer	将结果导出为 Mayer .may	同步
GET	/v3/export/biesse	将结果导出为 Biesse XML CutList	同步
GET	/v3/saws	列出锯床及其支持的导出格式	同步
POST	/v3/labels	生成可打印的零件标签	同步
POST	/webhooks/result	接收计算结果 — 由你提供的 端点
GET	/v3/calls	获取 API 使用统计信息	同步

完整参考文档：https://smartcut.dev/api-docs/v3

异步模式的工作原理

优化所需时间较长，不适合让请求一直阻塞，因此 /v3/calculate 会立即返回一个作业 ID。随后，你可以持续轮询 /v3/result/ready，直到其报告任务完成；也可以注册 Webhook，让 SmartCut 在结果可用时向你发送 POST 请求。无论采用哪种方式，都需要从 /v3/result 获取数据。

Webhook 注册、签名验证和重试行为的文档见 https://smartcut.dev/docs/webhooks。

MCP 服务

SmartCut 运行着托管的 Model Context Protocol 服务，因此 Agent 可以使用你现有的 API 密钥直接运行优化。

POST https://api.smartcut.dev/mcp

采用 Streamable HTTP 传输。身份验证使用 Authorization 标头中的同一原始密钥，不带 Bearer 前缀。Claude Desktop 和其他客户端的配置位于 mcp/。

工具：calculate、validate、status、result、cancel、usage、export、 labels、list_cut_types——此外还有 import_parts，它与其他工具不同：它会将 Agent 提取的零件（来自 PDF 或切割 计划照片）推送到已打开的 Cutlist Evolution 编辑器中，供用户确认，而不是调用优化 API。

calculate 工具会在单次调用中等待结果（默认约 25 秒，可通过 waitMs 覆盖）；如果优化仍在运行，则会改为返回任务 ID，因此 Agent 通常一次调用就能获得排版结果。

生成客户端

没有官方 SDK，这是有意为之。 API 只需要一个 JSON 请求体和一个标头，因此 fetch 本身就是客户端——而使用你自己的习惯方式生成的客户端，会比手写客户端更适合你的代码库。将任意生成器指向此规范：

npx openapi-typescript openapi/v3.json -o smartcut.d.ts
npx @hey-api/openapi-ts -i openapi/v3.json -o src/smartcut
openapi-generator-cli generate -i openapi/v3.json -g python -o ./smartcut-python

示例

语言	文件
curl	examples/curl/optimise.sh
Node	examples/node/optimise.mjs
Python	examples/python/optimise.py
PHP	examples/php/optimise.php

每个示例都会读取 examples/requests/ 中的请求负载，该负载由规范生成——因此示例不会与架构定义偏离。

这是什么，不是什么

SmartCut 是一项托管订阅服务，而不是可自托管的库。它适用于报价、订单处理、电商定尺切割结账和 CAM 交接等场景，在这些场景中，你希望获得高质量优化和锯切格式输出，同时无需维护几何引擎。如果你需要一个无需网络调用和账户即可在进程内运行的装箱器，那么这并不适合你，开源装箱库才是正确选择。

链接

• 文档 — https://smartcut.dev/docs
• 交互式 API 参考 — https://smartcut.dev/api-docs/v3
• 获取 API 密钥 — https://smartcut.dev/account
• 已发布的基准测试 — https://smartcut.dev/benchmarks
• WooCommerce 插件 — https://github.com/jgmedialtd/smartcut-wp-plugin

支持

此处的问题仅限于规范和示例。如需 API 访问、账单、配额或集成支持，请使用 https://smartcut.dev/contact 上的联系表单。规范文件由程序生成，不能通过拉取请求修改——请参阅 openapi/README.md。