SmartCut

SmartCut API

SmartCut は、板材、棒材、ロール材の切断最適化（カットリスト／ネスティング）を行うホステッド API です。このリポジトリには、OpenAPI 仕様、実行可能なサンプル、および独自のソフトウェアに統合するための MCP 設定が含まれています。

機能

• 板材の最適化 — 合板、MDF、ガラス、プラスチック、板金向けのギロチン（端から端まで切断可能な、のこぎりで切断できる）モードと効率モード。
• 棒材（1D）の最適化 — 木材、棒鋼、パイプ、押出材向け。
• 実形状ネスティング — レーザー、プラズマ、ウォータージェット、CNC ルーティング向けに、DXF から不規則な形状の部品をネスティングします。
• 木目方向と部品ごとの向きの固定 — 部品を木目の長さ方向または幅方向に固定するか、自由に回転できるように設定できます。
• エッジバンディング、表面仕上げ、刃の切りしろ、素材のトリミング — 後処理ではなく、最初から入力項目として扱います。
• 機械対応のエクスポート — 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"

結果には素材ごとの項目が含まれ、それぞれに配置された部品とその位置、部品の加工に必要な切断、および残った端材が記載されています。4 つの言語で書かれた、すぐに実行できる完全なサンプルは examples/ にあります。

認証

生の API キーを Authorization ヘッダーに渡します。

Authorization: YOUR_API_KEY

Bearer プレフィックスは不要です。 これは統合時に最もよくある間違いです。Bearer プレフィックスを付けると 401 が返されます。

エンドポイント（v3）

メソッド	パス	機能	同期
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 サーバーを実行するため、エージェントは既存の 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 があります。これは、エージェントが抽出した部品（PDF や切断プランの写真から抽出したもの）を、最適化 API を呼び出すのではなく、ユーザーが確認できるよう、開いている Cutlist Evolution エディターに送信します。

calculate ツールは呼び出し中に結果を待ちます（デフォルトでは約 25 秒で、waitMs で変更できます）。最適化がまだ実行中の場合はジョブ ID を返すため、通常、エージェントは 1 回の呼び出しでレイアウトを取得できます。

クライアントの生成

公式 SDK はありません。これは意図的なものです。 API は JSON ボディと 1 つのヘッダーで構成されるため、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 はサブスクリプション制のホスト型サービスであり、セルフホスト可能なライブラリではありません。ジオメトリエンジンを保守することなく、最適化の品質と鋸向けの形式での出力を利用したい場合に適しています。たとえば、見積もり、注文処理、EC サイトでのサイズ指定カット注文、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

サポート

ここでの Issue は、仕様と例のみを対象としています。API アクセス、請求、クォータ、連携に関するサポートについては、 https://smartcut.dev/contact のお問い合わせフォームをご利用ください。仕様ファイルは生成されるため、プルリクエストでは変更できません。詳しくは openapi/README.md をご覧ください。