Tools · Printy3D

Running a tool#

POST/v1/jobsjobs:write

Set recipe to tool, name the tool and put its parameters in params. Parameters you leave out take the defaults listed on each tool's page; an unknown parameter or a value out of range answers 422 validation_failed before anything runs.

curl -sS "$API/v1/jobs" -H "Authorization: Bearer $PRINTY3D_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "input_file_id": "'"$FILE_ID"'",
    "recipe": "tool",
    "tool": "cut",
    "params": {
      "planes": [{"origin": [0, 40, 0], "normal": [0, 1, 0]}],
      "keep_both_sides": true
    }
  }'

Points, planes and sizes are in the model's own coordinates, in millimetres. Use the inspect analysis (dimensions_mm) or your own viewer to pick them.

All tools#

tool	What it does	Returns
`cut`	Split the model with up to 8 planes or rectangles, optionally with alignment keys.	Mesh pieces
`mirror`	Add a mirrored copy along x, y or z.	Mesh
`lattice`	Replace the interior with a gyroid, Schwarz-P, BCC, octet or diamond lattice.	Mesh
`label`	Add text: snap-off tag, embossed, engraved or extruded.	Mesh
`remove_small_parts`	Delete loose fragments smaller than a threshold.	Mesh
`convert`	Convert the model to STL, OBJ, PLY, 3MF or GLB.	Mesh file
`measure`	Distance between two points on the surface.	Numbers
`thickness`	Voxel wall-thickness check against a target, with a heatmap.	Numbers, heatmap
`medial`	Ball (inscribed-sphere) wall thickness per vertex, with a heatmap.	Numbers, heatmap
`analyze`	Vertex, face and volume figures plus the engine’s analysis JSON.	Numbers
`structural.components`	List the separate islands; optionally remove small ones.	Numbers, mesh
`structural.fea`	Voxel finite-element solve under gravity; optional thickening or graded hollowing.	Numbers, mesh
`structural.heatmap`	Stress heatmap for a support and a load.	Numbers, heatmap
`structural.fragility`	Safety factor and the points most likely to break.	Numbers, heatmap
`structural.measure_all`	Four fixed scenarios in one job.	Numbers, heatmaps
`structural.relief`	Turn the model’s texture into surface relief.	Mesh

What a tool returns#

job.result is {schema_version, simulated, tool, result}, where result holds the tool's own numbers (described per tool). The same document is the result artifact. Mesh tools also publish one artifact per mesh format they wrote: result_glb, result_obj_zip or result_3mf for one piece, or result_glb_zip, result_obj_zip or result_3mf_zip with a piece_NN/ folder per piece (at most 50). Analysis tools write OBJ files: heatmap, result_obj and result_parts_obj_zip. Any other format of a mesh result is an export.

One tool attempt may run for up to 1800 s.
A tool that is not offered to your plan answers 501 feature_unavailable.
Structural results are guidance only: every one carries guidance_only: trueand is not a certified structural analysis.
Test keys return simulated results with the same shape (simulated: true) and placeholder meshes.