Engine API

Všechno, co CutOptim v prohlížeči dělá, začíná jedním výpočtem: mám tyto díly a tento materiál — jak je nejlépe rozřezat? Engine API zpřístupňuje přesně tento výpočet přes internet, takže se může zeptat i jiný program a odpověď dostat zpátky — bez prohlížeče, bez klikání, bez přihlášeného člověka.

A to je celá myšlenka. Není to nový optimalizátor, není to lepší optimalizátor a není to větší tarif. Je to stejné jádro, jen dostupné softwaru místo člověku.

Je to pro mě?

Pro naprostou většinu uživatelů CutOptim je poctivá odpověď ne. Pokud tvůj pracovní den vypadá tak, že otevřeš CutOptim, zadáš díly a materiál a plán vytiskneš nebo vyexportuješ, produktem je aplikace a tato stránka se tě netýká.

Engine API míří na jedinou situaci: plány řezání se mají objevovat v softwaru, který už používáš, aniž by kdokoli chodil do CutOptim. V praxi to znamená jednoho ze dvou lidí:

• Už provozuješ software, do kterého plán řezání patří. ERP, ve kterém máš zakázky, kalkulační nástroj, který zakázky cení, nebo vlastní software stroje. Místo aby operátor přepisoval stejný seznam dílů znovu do CutOptim, zeptá se ten program jádra přímo a plán zobrazí tam, kde se práce už odehrává.
• Necháváš si software postavit. Vlastním vývojářem, místní softwarovou firmou nebo dodavatelem svého stroje. Engine API je to, na co se připojí.

Pokud si nejsi jistý, na které straně té hranice stojíš, dobrý test je tento: mohl by plán vzniknout, aniž by si o něj někdo řekl? Pokud ano, API má smysl. Pokud o vytvoření plánu řezání vždycky rozhoduje člověk, správným nástrojem už je aplikace.

Co umí

Tvůj software pošle jako JSON tytéž dvě věci, které bys zadal do aplikace — seznam dílů a seznam materiálu. Jádro pošle zpátky celou odpověď:

• Celé rozvržení. Každý díl umístěný na konkrétní desce nebo tyči, včetně informace, jestli byl otočený.
• Plán řezání. Ne jen obrázek obdélníků: skutečná gilotinová sekvence řezů v pořadí, takže se plán dá provést na formátovací pile.
• Čísla. Kolik desek nebo tyčí zakázka spotřebuje, využití materiálu v procentech, kolik řezů je potřeba a celkovou cenu použitého materiálu. U desek dostaneš navíc dvě poctivé míry počtu řezů — řezy, které slučují řezy se stejným nastavením dorazu, a průjezdy pily, které počítají každý jednotlivý průjezd — a k tomu celkovou délku řezu.
• Volitelně i výkres. Požádej o include: ["svg","csv","dxf"] a odpověď ponese rozvržení i jako hotový soubor — samostatný 2D výkres SVG, DXF ve formátu R12/AC1009 nebo seznam řezů CSV — přímo v JSON, bez úložiště a bez druhého volání. (SVG je jen 2D.) U 2D požadavků lze navíc žádat labels (data štítků pro každý díl), planHash (otisk plánu), pdf (PDF plánu řezání) a labelsPdf (PDF se štítky) — PDF kódovaná v base64, kreslená stejným kódem jako v aplikaci.
• Vaše vlastní identifikátory, vrácené zpět. Připoj objekt meta — číslo artiklu, řádek zakázky, referenci zákazníka — k jakémukoli dílu nebo řádku materiálu a vrátí se beze změny u každého umístěného kusu i u každé desky nebo tyče, takže plán sedí s tvým vlastním systémem. Právě tohle je pole, po kterém sáhneš, když chceš poslat všechny své desky, každou označit vlastním kódem a zpětně si přečíst, kterou desku optimalizátor zvolil — kód vlož do stock[].meta a vrátí se ti v sheets[].meta. Na rozmístění nemá nikdy vliv. K identifikaci nepoužívej pole material: material je tvrdé rozdělení (díl se řeže jen ze zásoby stejného materiálu), takže označit materiálem každý řádek zásoby a díly nechat neoznačené znamená, že se všechny díly vrátí jako unmatched a výsledek bude prázdný.

Optimalizační režimy jsou čtyři a všechny odpovídají aplikaci — jeden pro 2D desky, jeden pro 1D lineární materiál (tyče, profily, trubky), jeden pro dřevo, jehož materiál má průřez, a nesting podle skutečného tvaru (POST /v1/optimize/nest), který skládá libovolné polygony pro řezání laserem, plazmou a vodním paprskem (režim Nesting aplikace). Každý optimalizační endpoint má navíc bezplatný endpoint pro validaci, který požadavek zkontroluje bez výpočtu (viz níže).

Endpointy

Základní URL je https://api.cutoptim.com. Optimalizační endpointy a endpoint spotřeby nesou klíč v hlavičce Authorization: Bearer <key>; validační a stavový endpoint žádný klíč nepotřebují.

Většina volání se rovnou zodpoví hotovým výsledkem. Jedinou výjimkou je asynchronní jádro max (viz Tři jádra níže): odeslání úlohy max vrátí id úlohy a vy se dotazujete na GET /v1/jobs/{id}, dokud není plán připravený.

Validační endpointy přijímají stejné tělo jako odpovídající optimalizační endpoint a zkontrolují ho, aniž by spustily výpočet: chybně sestavený požadavek se vrátí jako 400 s uvedením přesně toho špatného pole a správně sestavený vrátí valid: true plus upozornění na proveditelnost (například díl, který se nevejde do žádného materiálu). Nic nestojí a nepotřebují klíč, takže si můžeš svá těla požadavků ověřovat už při stavbě integrace — ještě než vůbec máš klíč — a potvrdit si, že požadavek nebude odmítnut, aniž bys utratil jedno ze svých měsíčních volání.

Směr vláken u desek

Překližka a dýhované desky mají vlákna a viditelný díl se musí řezat tak, aby vlákna běžela správným směrem. Na POST /v1/optimize/2d pošli grain na řádku zásoby — "w" nebo "h", tedy stranu desky, podél které vlákna běží — a grain u dílu, tedy stranu dílu, podél které mají vlákna běžet. Každý takový díl se umístí tak, aby jeho vlákna běžela podél vláken jeho desky: otočený o 90°, kdykoli je to k tomu potřeba (rotated: true na umístění, jako u každého otočení), a rotatable se u něj ignoruje. Díl bez grain se dál otáčí volně, i na řádku zásoby bez grain (MDF, melamin); díl S grain si i na takovém řádku ponechá orientaci, kterou mu dávají řádky s vlákny — desky s vlákny a hladké oddělí material. Díl, který by se vešel jen otočený o 90° proti vláknům, se vrátí v unplaced v odeslané velikosti, řádek ve warnings ho jmenuje a POST /v1/validate/2d to ohlásí dřív, než se spotřebuje volání.

V jednom požadavku mohou být řádky zásoby, jejichž vlákna běží různými směry — 2440 × 1220 s "w" a 1220 × 2440 s "h" — a každá deska se vrátí v orientaci svého řádku, s grain zopakovaným v sheets[]. S material se na díl vztahuje směr vláken jen tehdy, když jeho vlastní materiál má desku s vlákny. grain dílu bez zásoby s vlákny v požadavku nemá žádný účinek a řádek ve warnings to uvede. options.trim a vynucené options.firstCut se uplatní na každou desku v orientaci jejího vlastního řádku, i na řádku, jehož vlákna běží druhým směrem. Režim Směr vláken v aplikaci CutOptim běží na stejném kódu. (Od 2026-10-02.)

Shoda vzoru dřeva u desek (matchedSets)

Směr vláken drží vlákna každého dílu správným směrem. Některá čela chtějí víc: čelo zásuvky nad dvěma dvířky, jejichž kresba pokračuje z jednoho dílu do druhého, jako by ty tři byly pořád jedna deska. Na POST /v1/optimize/2d dej těmto řádkům dílů id a pojmenuj je v matchedSets:

{
  "parts": [
    { "id": "DF", "name": "Drawer front", "w": 48.125, "h": 6 },
    { "id": "DOOR", "name": "Door", "w": 24, "h": 30, "qty": 2 },
    { "name": "Shelf", "w": 22.5, "h": 11.25, "qty": 4 }
  ],
  "stock": [{ "w": 96, "h": 48, "qty": 2, "grain": "w" }],
  "options": { "kerf": 0.125 },
  "matchedSets": [
    { "id": "base-1", "name": "Base cabinet fronts", "grain": "w",
      "layout": { "dir": "rows", "lines": [["DF"], ["DOOR", "DOOR"]] } }
  ]
}

• Co je sada. layout.lines vypisuje členy podle parts[].id. S dir: "rows" je každý řádek řadou členů vedle sebe a řady jsou nad sebou shora dolů, takže [["DF"], ["DOOR", "DOOR"]] je čelo zásuvky nad dvěma dvířky; s "cols" je každý řádek sloupcem a sloupce stojí vedle sebe. Díl se může v jedné sadě objevit víckrát (Door, Door), ale patřit smí jen do jedné sady. qty (výchozí 1) je počet instancí, které potřebuješ — tři stejné skříňky jsou qty: 3 — a vlastní qty dílů musí pokrýt každou instanci. Sada má nejméně 2 a nejvýše 24 členů a jeden požadavek přijme nejvýše 50 sad.
• Jak se řeže. Sada projde optimalizátorem jako jeden obdélník — blok — a vrátí se jako její členové, přesně o jeden prořez od sebe, z jednoho kusu desky. grain sady ("w" nebo "h", podél šířky nebo výšky bloku) určuje směr každého člena; vlastní grain člena se uvnitř sady nepoužije a varování pojmenuje každého člena, kterého přebije. Bez grain sady se blok smí otočit, pokud je každý člen rotatable. installGap je mezera mezi členy na skříňce (výchozí: prořez); na desce od sebe stále stojí o jeden prořez.
• Co se vrací. Každý umístěný člen nese matchedSet: id sady, kterou instance je, a její position v pořadí čtení na čele skříňky — shora dolů, zleva doprava, od 1 — plus hint jako "left" nebo "right", kde je to jednoznačné. Odpověď přidá souhrn matchedSets, jednu položku na sadu: její letter (A, B … v pořadí požadavku), kolik instancí bylo řezáno jako jeden blok (asBlock), rozděleno, nebo ponecháno neumístěno, rozměr bloku a warnings sady. Když se blok nevejde na žádnou desku, onMiss: "split" (výchozí) umístí členy po jednom s varováním a onMiss: "unplaced" je uvede v unplaced.
• Varování, ne chyby. Rozměr, který nesedí, je varování u sady, ne odmítnutí. Každý řádek začíná svým kódem — align: (řady nejsou v zákrytu), gap: (prořez je širší než installGap), grain:, split:, unplaced:, unmatched: (žádná zásoba materiálu sady), priority: a grainGroup: — a align a gap se posuzují na 1/64 tvé jednotky nebo čtvrtinu prořezu, podle toho, co je menší. Sada, kterou nelze vůbec rozložit — id člena, které nenese žádný díl, odkazované id na dvou dílech, méně než dva členy, příliš málo dílů pro qty —, je 400 s přesným polem, ještě než se volání účtuje.
• parts[].id je bezpečné posílat. Kontroluje se jen id, na které sada odkazuje (neprázdný tisknutelný řetězec nejvýše 64 znaků, nebo celé číslo, na právě jednom dílu). Každé jiné id se ignoruje, ať obsahuje cokoli, takže čísla artiklů z tvého ERP mohou zůstat na řádcích. A u požadavku bez sad se nic nemění: funkci zapíná jen neprázdné pole matchedSets — chybějící, null, [] nebo hodnota, která není pole, se vyřídí přesně jako dřív.
• Exporty. S sadami získá csv na konci sloupce Set a Position, svg tiskne kód pozice (A1, A2 …) do popisků dílů a rámeček každé sady kreslí do samostatné skupiny matched-sets — options.setOutlines: false tuto skupinu vynechá — a dxf nese kód pozice na vrstvě LABELS. pdf a labelsPdf sady neznačí: kreslí členy jako běžné díly a warnings to říká; značky sady jsou v sheets[].parts[].matchedSet, csv a svg.
• Jádra a endpointy. Jádra heuristic a balanced sady rozkládají (balanced neřadí priority, takže při respectStock tam sada může přijít o své místo, s varováním priority:). Jádro max neprázdné matchedSets odmítne kódem 400, jehož details.unsupported ho pojmenuje, ještě než se volání účtuje; prázdné je běžná úloha max. matchedSets a parts[].id jsou jen 2D: endpointy 1D, dřevo a nest je ignorují.
• grainGroup je zastaralý. Stále se přijímá a stále funguje přesně jako dřív: díly, které sdílejí skupinu, zůstanou na jedné desce. Nikdy je neumísťoval vedle sebe, takže nedává souvislá vlákna přes ně — k tomu použij matchedSets.

Shoda vzoru dřeva v aplikaci CutOptim rozkládá sady stejným jádrem.

Proč má dřevo vlastní endpoint

Lineární materiál zná jediný rozměr, délku, takže každá tyč může posloužit každému dílu. U dřeva to neplatí: díl 50×150 z tyče 50×100 nevyřežete, ať zbývá jakákoli délka. Endpoint pro dřevo proto u každého dílu i u každé položky materiálu přebírá obě strany průřezu, rozdělí zakázku podle průřezu, přiřadí každému průřezu jeho vlastní materiál a průřezy vrátí odděleně — každý s vlastními tyčemi a vlastními součty, vedle čísel za celou zakázku.

Dvě věci, které je dobré znát před integrací:

• Obě strany průřezu lze poslat v libovolném pořadí. 50×100 a 100×50 je tentýž otočený hranol a patří do jednoho průřezu. Rozdíl v tom, jak byla vaše data zrovna zadána, tedy nemůže způsobit, že materiál zmizí.

• „Žádný materiál tohoto průřezu“ a „nevešlo se“ se hlásí odděleně. První je chybějící materiál, druhé problém kapacity a každé se řeší jinak — smíchané v jednom seznamu pošlou vašeho uživatele hledat na špatné místo.

Totéž byste mohli přiblížit několika vlastními voláními 1d a díly si seskupit sami. Stálo by to jeden požadavek z kvóty na průřez místo jednoho na zakázku, přesunulo by to přiřazování materiálu do vašeho kódu a vzniklý součet za zakázku byste museli složit sami — a nemusel by se shodovat s tím, co pro stejnou zakázku ukazuje aplikace CutOptim.

Díly z CAD souboru

Nesting endpoint nepřijímá jen souřadnice. Díl může místo nich nést source — dokument SVG nebo DXF — a server z něj načte obrys i otvory v něm. Je to tentýž čteč, jaký používá aplikace, když na její režim Nesting přetáhnete výkres, takže knihovnu dílů, která už existuje jako CAD soubory, není nutné nejdřív přepsat na seznamy souřadnic.

Soubor nahrazuje pouze geometrii. Množství, materiál, povolená otočení i vaše vlastní metadata zůstávají běžnými poli řádku dílu, přesně jako když posíláte souřadnice. Jeden soubor popisuje jeden díl; když jeden výkres obsahuje několik samostatných součástí, POST /v1/import/nest jej nejprve rozdělí na hotové řádky — a toto volání vyžaduje klíč, ale nespotřebuje požadavek z vaší měsíční kvóty.

Nic se neukládá. Soubor existuje pouze jako samotný požadavek: čte se v paměti a v okamžiku, kdy je zapsána odpověď, mizí. Nezůstává kopie na disku ani v databázi, nic nekončí v logu a poté není co mazat. S jednotkami postupujeme stejně — DXF může deklarovat milimetry nebo palce a my hlásíme, co uvedl, ale souřadnice nikdy nepřepočítáváme, protože žádná hodnota v tomto API nenese jednotku.

Pokaždé stejná odpověď

Jádro je deterministické: stejný vstup vrací vždy stejný výstup. V algoritmu není žádná náhoda ani hodiny.

Zní to akademicky, ale právě to je praktický důvod, proč na tom stavět. Znamená to, že se výsledky dají cachovat — pokud jsi se na přesně tuto zakázku už ptal, můžeš odpověď bezpečně použít znovu místo dalšího dotazu. A také to znamená, že se propojení dá testovat: plán se dá porovnat se známým správným výsledkem a rozdíl je pak skutečný rozdíl, ne šum. Software, který zákazníkovi v pondělí nacení zakázku, ji v pátek nacení stejně.

Existuje jedna výjimka, na kterou si musíte sami sáhnout, a odpověď to říká: jádro max pro nesting (níže) tráví hledáním pevný časový rozpočet, takže to, kam se dostane, závisí na tom, kolik práce se do toho času vejde. Jeho odpovědi nesou deterministic: false. Každé jiné jádro — včetně výchozího jádra nestingu, lbf — je deterministické.

Bezpečné opakování. Když spojení spadne, nevíte, zda požadavek dorazil. Pošlete hlavičku Idempotency-Key — hodnotu, kterou zvolíte pro každou úlohu — a opakujte se stejným klíčem: do 24 hodin vrátí stejný požadavek uloženou odpověď označenou Idempotency-Replayed: true a podruhé se neúčtuje. Ani úloha max se nezařadí dvakrát. Veřejný demo klíč tuto hlavičku ignoruje. (Od 2026-10-15.)

Webhooky pro asynchronní úlohy. Místo dotazování GET /v1/jobs/{id} si na nástěnce zaregistrujte endpoint (URL https://) a když asynchronní úloha max skončí, dostanete podepsaný POST — job.succeeded nebo job.failed. Ověřte hlavičku CutOptim-Signature obdrženým klíčem, odpovězte do 10 sekund a plán načtěte přes GET /v1/jobs/{id}. Neúspěšné doručení se opakuje: 8 pokusů během 24 hodin. (Od 2026-10-19.)

Oficiální SDK. Open-source klienti pro TypeScript, Python a PHP — npm install @cutoptim/engine, pip install cutoptim, composer require cutoptim/engine — s typovanými požadavky, opakováním, které se nikdy neúčtuje dvakrát (každé volání nese Idempotency-Key), pomocníkem pro čekání na asynchronní úlohy a ověřením webhooků. Zdrojový kód na GitHubu; podrobnosti v průvodci SDK (anglicky).

MCP server pro AI asistenty. Claude Code, Cursor, VS Code a Claude Desktop mohou volat engine jako nástroje přes hostovaný server Model Context Protocol na adrese https://api.cutoptim.com/mcp, se stejným API klíčem (Authorization: Bearer …) a ze stejné kvóty: jedno volání nástroje je jedno volání API a nástroje validate_* jsou zdarma. Kdo chce server spouštět lokálně, použije balíček npx -y @cutoptim/mcp (klíč v proměnné CUTOPTIM_API_KEY); server je také v oficiálním MCP Registry jako io.github.cutoptim/engine. Nastavení klientů najdete v průvodci MCP (anglicky).

Tři jádra

API nabízí na výběr z jader. První dvě běží synchronně, třetí asynchronně. Rozdíl není v kvalitě — je to kompromis mezi rychlostí, tím, jestli se výsledek dá rozřezat na formátovací pile, a tím, jak blízko se dostane k teoretickému minimu.

• heuristic je výchozí a je to totéž jádro, které používá aplikace. Vytváří gilotinová rozvržení: nejvyšší využití materiálu, každé rozvržení je řezatelné na formátovací pile a vždy je k němu plný plán řezání. Synchronní.
• balanced si zapneš sám. Používá místo toho volný nesting, který je na hodně velkých zakázkách dramaticky rychlejší — naměřeno asi 25× rychleji na zakázce s 2 000 díly — za cenu o něco nižšího využití materiálu. Důležitá past: jeho rozvržení často nelze rozřezat od hrany k hraně, takže u nich nevrací žádný plán řezání. Synchronní.
• max si zapneš sám, a to pro 2D desky (a odděleně i pro nesting podle skutečného tvaru — viz níže). U 2D je to serverové prohledávání stromu, které dosahuje prokázaného optima u mnohem více zakázek než výchozí jádro, a jeho rozvržení jsou stále řezatelná na gilotině. Cenou je čas: výpočet max trvá sekundy až minutu, takže neodpovídá v samotné odpovědi. Místo toho POST /v1/optimize/2d s engine: "max" vrátí id úlohy a vy se dotazujete na GET /v1/jobs/{id}, dokud není hotová. Stále je deterministické. Sáhni po něm, když se u velké, hodnotné zakázky vyplatí počkat na posledních pár desek. Modeluje jediný formát materiálu v plné velikosti desky a v neomezeném množství, takže požadavek, který navíc nese druhý formát materiálu, trim po stranách, omezené zásoby (respectStock), materiály, skupiny vláken nebo neprázdné matchedSets, je předem odmítnut kódem 400, který přesně pojmenuje, co jádro neumí — ještě než se volání účtuje. Takové zakázky posílejte do heuristic, které je zvládne všechny.

Nesting: lbf a max

Nesting podle skutečného tvaru má svá vlastní dvě jádra. lbf je výchozí: okamžité, synchronní a deterministické. max si zapneš sám a je asynchronní, přesně jako 2D max — POST /v1/optimize/nest s engine: "max" vrátí id úlohy a vy se dotazujete na GET /v1/jobs/{id}.

Nesting max nejdřív spustí průchod lbf, takže má vždy po ruce platnou odpověď. Pak stráví časový rozpočet (options.timeBudgetMs, výchozích 60 sekund, mezi 10 a 180) hledáním rozvržení s menším počtem desek, přičemž plní vždy jednu desku po druhé. Nikdy nevrátí víc desek než lbf: když hledání nenajde zlepšení, dostanete rozvržení lbf a upozornění, které to říká. Protože je hledání časově omezené, jeho odpovědi nesou deterministic: false. Přijímá víc velikostí desek na materiál i respectStock a řadí svůj výsledek podle stejného pravidla jako lbf (níže): plán lbf nahradí jen tehdy, když je lepší — nikdy jen proto, že má méně desek. Polygonová deska nebo vyloučené zóny, které jeho pásové hledání nedokáže modelovat, se v rámci úlohy vyřídí průchodem lbf s upozorněním — nikdy nejsou odmítnuty. Starší název sparrow se přijímá jako alias pro max.

Obdélníkové díly dostanou přesnou mřížku (od 2026-09-28). lbf hledá pozice vzorkováním, které téměř nikdy netrefí mřížku bez jakékoli vůle: tři díly po 500 mm přes šířku desky 1500 mm při nulové mezeře se vejdou přesně, a hledání vzorkováním umístí dva. Obě jádra proto zkoušejí i dvě varianty a podrží tu, která dopadne nejlépe podle stejného pravidla: díly omezené na pravé úhly, které povolují, a obalové obdélníky dílů složené přesným algoritmem skládání obdélníků (obdélníky, které se nepřekrývají, nemohou obsahovat překrývající se díly, takže to platí pro jakýkoli obrys). Při shodě — stejné desky, stejná plocha desek — vyhraje plán, který plní desky odpředu dozadu, a pak ten s menším počtem dílů natočených mimo pravé úhly. Není co zapínat a výsledek se podle řazení může jen zlepšit; plán, který obdélníky dostanou na nejmenší počet desek, jaký plocha dílů dovoluje, navíc způsobí, že max odpoví hned, místo aby hledal.

Zakázka s několika desítkami dílů obvykle potřebuje rozpočet kolem 15 sekund (timeBudgetMs: 15000); úloha skončí zhruba jednu až dvě sekundy po vypršení rozpočtu, plus čas strávený ve frontě. Dotazujte se na GET /v1/jobs/{id} každé dvě až tři sekundy — dotazování nic nestojí z kvóty. Žádný rozpočet neslíbí konkrétní počet desek.

Nesting: odstup od okraje, velikosti desek a co stála každá deska

• Odstup od okraje. options.minSeparation je mezera mezi díly a sama o sobě platí i u okraje desky. options.edgeClearance nastaví okraj zvlášť — třeba 5 mezi díly a 0 nebo 10 u okraje. Když ho vynecháte, okraj drží minSeparation, přesně jako dřív. Funguje na obou jádrech, vyžaduje obdélníkové desky (w a h) a vyloučené zóny drží minSeparation stejně jako díly. Polygonová deska, nebo hodnota, po které na desce nezbyde místo, je odmítnuta kódem 400 ještě dřív, než se volání účtuje.
• Výběr velikosti desky. Když má materiál dva nebo víc řádků zásoby, lbf je zkusí ve vašem pořadí, každou velikost samostatně a v pořadí od nejlevnější, a podrží tu nejlepší — výsledek tedy dál nezávisí na pořadí, ve kterém řádky uvedete. Řazení je: nejvíc umístěných dílů, které musí být vyříznuty (viz níže), pak nejvíc umístěných dílů celkem, pak nejmenší celková plocha desek (materiál), pak nejméně desek. S options.minimizeCost řadí místo toho podle celkové ceny (price, nebo cost u řádku bez ceny) — ale jen když ji nese každý řádek daného materiálu; jinak se vrátí k ploše a řekne to ve warnings.
• Míchání velikostí. Poté se každá deska — nejméně zaplněná první — přerozvrhne samostatně na levnější nebo menší řádky a nahradí se, pokud tím celý plán dopadne lépe. Velikosti se tedy v rámci jednoho materiálu můžou míchat: typicky dvě velké desky a menší poslední, kde bývala poloprázdná poslední deska dřív velká. S options.respectStock se žádný řádek nepoužije víckrát, než je jeho qty. Jádro max používá stejné řazení.
• Díly, které musí být vyříznuty. parts[].priority: true označí díl, který se musí vyříznout. Hraje roli s options.respectStock — omezenou zásobou, kde se nemusí vejít každý díl: takové díly se pak umístí jako první, takže běžný díl nikdy nezabere místo na desce, které potřebuje povinný díl, a každé řazení výše dává přednost plánu, který jich zachová víc, i kdyby umístil méně dílů celkem. Obě jádra to respektují (max podrží rozvržení lbf, kdykoli něco zůstane neumístěné). Bez respectStock se stejně umístí každý díl, který se vejde, takže příznak nic nemění. Povinný díl, který se nevejde na žádnou desku, se i tak objeví v unplaced. (Od 22. 9. 2026 — dřív nesting toto pole přijímal, ale ignoroval ho.)
• Omezená zásoba, na kterou se nevejde všechno. S options.respectStock, když plán stále nechává díly neumístěné, engine navíc plní desky jednu po druhé obalovými obdélníky dílů — každou co nejplněji a díl, který se vejde jen na jednu velikost desky, jde tam jako první (vysoký bok na jedinou velkou desku, ne na zbytkový pás). Tento plán převezme jen tehdy, když umístí více dílů (povinné napřed) nebo spotřebuje méně materiálu; zakázka, kde se vejde všechno, se vrátí přesně jako dřív. Dodržuje povolená natočení každého dílu, minSeparation i edgeClearance. (Od 2026-10-14.)
• Co stála každá deska. Každá deska nese stock — index řádku zásoby z požadavku, ze kterého byla vyřezána —, a odpověď navíc přidává stockUsage: jeden záznam na každý použitý řádek zásoby, s počtem desek, celkovou cenou a hustotou. Jednotkou je řádek zásoby, ne velikost: dva řádky se stejnými rozměry, ale jinou cenou nebo meta, jsou dva záznamy.
• Délka řezu a propaly. Každá deska nese cutLength — součet obvodů obrysů a otvorů umístěných dílů, ve vaší jednotce — a pierces, jeden na každý uzavřený obrys; metrics sčítá obojí. Je to geometrická délka obrysu: bez řezání po společné linii, nájezdů nebo mikrospojů — ty přidává váš CAM.
• Využitá plocha, pro účtování jen části desky. Každá deska nese usedWidth a usedHeight — nejvzdálenější bod, kam sahá kterýkoli umístěný díl, měřeno od počátečního rohu desky, ve vaší jednotce, na skutečné desce (s edgeClearance je odstup od okraje započítán) — a usedArea, jejich součin; stockUsage[].usedArea to sčítá podle řádku zásoby. Přesně to potřebuje ERP k účtování vodorovného řezu (usedHeight × šířka desky), svislého řezu (usedWidth × výška desky) nebo opsaného obdélníku (usedArea) místo celé desky — pravidlo účtování zůstává na vás. Aby byla tahle čísla malá, obě jádra ve výchozím stavu zkompaktují nejméně zaplněnou desku každého materiálu: její díly se znovu rozmístí na téže desce s podmnožinami natočení, která každý díl povoluje — 0/180, 0/90/180/270 a jedno natočení pro každou kopii, v průniku s diskrétním allowedRotations, nikdy nový úhel —, a podrží se rozvržení s nejmenší využitou plochou. S engine: "max" tuto desku poté znovu poskládá i samotné hledání — podél výšky desky a u plánu s jedinou deskou i podél její šířky — a podle stejného pravidla podrží těsnější rozvržení. Počet desek, velikosti, cena a umístěné díly se nikdy nezmění; options.compact: false vrátí nezkompaktované rozvržení. Pokud účtujete pás místo opsaného obdélníku, nastavte podle toho options.compactFor: "horizontal" podrží rozvržení s nejnižší usedHeight (pás přes celou šířku desky), "vertical" s nejmenší usedWidth (pás přes celou výšku desky); výchozí "box" podrží nejmenší usedArea. Pásové režimy navíc zkoušejí každou kopii otočenou o čtvrtinu (90° nebo 270°) tam, kde to allowedRotations dovoluje. Jak malá využitá plocha nakonec bude, závisí na dílech. (Od 22. 9. 2026.)

Limity

Každý požadavek má své hranice, takže zakázka, která se vymkne, jasně selže a nezůstane viset:

Jak získat přístup

Začni na stránce Engine API. Engine API se účtuje odděleně od tarifů aplikace a nezapne ho žádná změna tarifu.

1. Vyzkoušej, pak si ho předplať — nebo napiš. API můžeš volat ještě před platbou: tlačítka Spustit tento příklad v referenci API používají veřejný demo klíč a každý přihlášený účet si může na nástěnce vytvořit bezplatné testovací klíče (vlastní malý měsíční limit, nikdy se neúčtují, předplatné není potřeba). Až budeš připravený, předplatné na stránce Engine API je nejrychlejší cesta — vstupní tarif Studio začíná zkušebním obdobím zdarma a přístup dorazí na účet sám. Pokud chceš nejdřív popsat svou integraci nebo potřebuješ objem nad rámec standardního tarifu, napiš nám a uveď, co chceš propojit a kolik plánů řezu měsíčně to zhruba bude potřebovat.
2. Přístup ti přidáme na účet. Nic jiného se na tvém účtu nemění.
3. Vytvoř si klíč. Karta API klíče je na tvé nástěnce u každého přihlášeného účtu: bez předplatného vytváří testovací klíče, s přístupem k API i ostré (live) klíče. Klíče si tam sám vytváříš, pojmenováváš a mažeš.
4. Zkopíruj si klíč hned. Celý klíč se zobrazí právě jednou, v okamžiku, kdy ho vytvoříš.

Ke klíči se chovej jako k heslu: patří do konfigurace tvého softwaru, ne do e-mailu, do tabulky nebo na snímek obrazovky.

Co dělá karta API klíče na nástěnce

Čtyři ovládací prvky — a stojí za to přesně říct, co který mění, hlavně ten poslední, u kterého mnozí čekají dopad na placení. Nemá ho.

• Tarif, přepnutí a Fakturace. Ukazuje, na kterém tarifu účet je (Studio nebo Scale). Přejít na Scale (nebo Přejít na Studio) po potvrzení změní tarif a měsíční kvóta účtu se změní okamžitě. Fakturace otevře nastavení fakturace, kde aktualizuješ kartu, prohlédneš si faktury nebo předplatné zrušíš.
• Vytvořit klíč. Vygeneruje nový klíč a jednou ho tam zobrazí. Název (ERP integrace, staging) slouží jen k tomu, abyste klíče později rozeznali. Až 10 aktivních klíčů na účet. Testovací klíče se vytvářejí stejně a počítají se zvlášť: mají vlastní malý měsíční limit a nikdy se neúčtují.
• Ukazatel spotřeby. Dvě čísla: celková spotřeba účtu za kalendářní měsíc vůči kvótě a u každého klíče, kolik spotřeboval on. Číslo u klíče odpovídá na to, která integrace kvótu spotřebovává — není to samostatný rozpočet.
• Odvolat. Od dalšího volání ten jeden klíč vyřadí. Řádek zůstává vidět, aby se neztratila historie.

Jedna kvóta pro účet, ne jedna na klíč

Každý aktivní klíč vašeho účtu čerpá ze stejné měsíční kvóty. Druhý klíč nevytvoří druhou kvótu — klíče jsou od toho, abyste oddělili staging od produkce, dali každé integraci vlastní přihlašovací údaj a jeden odvolali, aniž byste rušili ostatní.

GET /v1/usage hlásí stav účtu (used, limit, remaining), takže odpovídá na otázku, kterou skutečně máte — kolik zbývá, než volání začnou selhávat — bez ohledu na to, kterým klíčem jste se ptali. Když kvóta dojde, vrací 402 každý klíč, ne jen ten, který ji spotřeboval.

Tarify, cena a kvóta

Engine API se účtuje odděleně od tarifů aplikace, měsíčně, v EUR, a má dva tarify:

Všechno ostatní je na obou stejné: stejná jádra, všechny čtyři režimy, všechny volby, stejné odpovědi. Každý požadavek se počítá stejně — úloha nestingu stojí jeden požadavek, úplně stejně jako 2D nebo 1D.

• Tvrdý strop, žádné příplatky. Když je měsíční kvóta vyčerpaná, volání vrací 402, dokud se neobnoví první den následujícího měsíce. Žádná nečekaná faktura.
• Dva e-maily, aby tě strop nepřekvapil. Účtu pošleme e-mail při 90 % kvóty a znovu, když je vyčerpaná.
• Změna tarifu je jedno tlačítko na kartě API klíče na tvé nástěnce (Přejít na Scale / Přejít na Studio); nová kvóta platí okamžitě. Přechod na vyšší tarif se účtuje hned za zbytek období; při přechodu na nižší se nic nevrací a nižší cena platí od příštího obnovení. Přepnutí je dostupné po zkušebním období.
• Větší objemy než v tarifu Scale se oceňují individuálně — napiš nám.

Aktuální ceny a kvóty najdeš na stránce Engine API — ta si je čte z naší konfigurace ceníku, takže tam je vždy platné číslo.

Technické podrobnosti — přesnou podobu požadavku a odpovědi, všechny volby, všechny chybové kódy i to, jak funguje verzování — najdeš v referenci API.

Open-source komponenty

Jádra CutOptim stavějí na open-source knihovnách, které na našich serverech běží beze změny:

• jagua-rs — geometrické kolizní jádro za nestingem podle skutečného tvaru (MPL-2.0).
• sparrow — hledání za jádrem max pro nesting (MIT, KU Leuven).
• PackingSolver — prohledávání stromu za jádrem max pro 2D (MIT).

Všechno kolem nich — API, propojení mezi kontraktem a těmito jádry, obdélníkové packery i samotná aplikace — je vlastní kód CutOptim.

Co se tím nemění

Stojí za to to říct naplno, protože Engine API se dá snadno špatně přečíst jako změna produktu:

• Optimalizátor v aplikaci zůstává beze změny. Dál běží v tvém prohlížeči, přesně jako dřív.
• Tarify Zdarma, Pro a Dílna se nemění. Optimalizátor v aplikaci v nich zůstává zahrnutý se stejnými limity jako dřív. Nic se za API nepřesunulo.
• Nic, co v aplikaci uděláš, nespotřebovává požadavky API. Měsíční kvótu API ubírají jen volání, která pošle tvůj vlastní software.

Engine API je doplněk pro ty, kdo CutOptim zapojují do jiného softwaru. Pokud to nejsi ty, nezměnilo se nic.