Settings and presets

How a photo is rendered. Changing any of it never runs the model again, so it is free and instant.

The settings object

The same shape everywhere: the defaults of a batch, the settings of a single-image call, and the patch you send to /apply.

Field	Values	Meaning
`presetId`	a preset id, `original`, `custom`	Canvas size and marketplace rules. `original` keeps the source size. `custom` needs `customSize`.
`customSize`	`{ width, height }` 100–8000 px	Only with `custom`.
`background`	`{ mode, color? }`	`transparent`, `white`, `solid` (hex `color`), `image` (a file sent at creation or with `/apply`). Presets that require white force white.
`align`	`center`, `top-left`, `top-right`, `bottom-left`, `bottom-right`	Where the product sits on the canvas.
`fill`	0.5–1	How much of the canvas the product spans. Default: the preset’s rule.
`foregroundScale`	0.25–1	Draw the product smaller on the same canvas, anchored by `align`.
`scale`	1, 2, 4	Integer upscale of the whole canvas.
`flip`, `rotate`	boolean; 0, 90, 180, 270	Mirror and rotate before framing.
`sharpen`	0–100
`brightness`, `contrast`	−30…30	Percent.
`saturation`	−50…50	Percent.

Presets

GET/v1/presets

The marketplace presets with their canvas, background rule, output format, upload limit, and source / verifiedAt: where the numbers were checked and when. Marketplaces change their rules; the export for a preset is what the preset says today.

curl https://trycutstack.com/v1/presets -H "Authorization: Bearer $CUTSTACK_API_KEY" \
  | jq '.presets[] | {id, label, width, height, background, format, verifiedAt}'

Changing finished photos

POST/v1/jobs/{id}/apply

Re-renders from the stored cutouts: another preset, another background, a different alignment. All photos or a list. Free.

curl -X POST https://trycutstack.com/v1/jobs/$JOB/apply \
  -H "Authorization: Bearer $CUTSTACK_API_KEY" -H "Content-Type: application/json" \
  -d '{ "itemIds": "all", "settings": { "presetId": "etsy", "background": { "mode": "solid", "color": "#f4f1ea" } } }'

With a background image: multipart with payload (the same JSON) and an image part, shared by the selection. Unspecified fields keep their value, so a patch of one field changes one thing.

Previewing

POST/v1/jobs/{id}/items/{itemId}/preview

{ settings, maxSide } renders one finished photo once, at up to maxSide pixels, and returns the image. Nothing is stored. Useful to show a client a choice before applying it to 200 photos.

The model runs once per photo, at upload. Everything on this page is composition on top of that cutout. What does run the model again: a retry, and the strongest-model re-run. See Review queue.

Next: Review queue. The photos worth a look, and what to do with them.