Preset steps

A preset is a saved list of steps. Each step is an op from the op catalogue wherever one exists — {op, parameters}, with a closed, validated parameter set. Where no op covers what you need — a sharpen, a colour matrix, a progressive JPEG — a step names one of the processing engine’s own operations instead: {operation, params}. This page is that list. You write it when you author a preset; whatever runs the preset later only names it.

{
  "name": "Print sharpen",
  "slug": "print-sharpen",
  "steps": [
    {
      "op": "resize",
      "parameters": {
        "width": 1800,
        "height": 1200,
        "fit": "inside"
      }
    },
    {
      "operation": "sharpen",
      "params": {
        "sigma": 1.5,
        "m1": 1.5,
        "m2": 0.7
      }
    },
    {
      "operation": "jpeg",
      "params": {
        "quality": 100,
        "progressive": true
      }
    }
  ]
}

Five rules

1. Params go to Sharp verbatim. params is handed to the Sharp method of the same name, so the signature is Sharp’s at the version the processing image pins. Each row below links to it; nothing here restates it.
2. A parameter that names another image takes one of your assets — {"assetId": "<id>"} — or inline data. That is composite.images[].input, joinChannel.images[], boolean.operand and overlay.input. The asset has to be yours — any other id is 404 not_found when the job is submitted, dry run included, and one still uploading is 400 invalid_state — and a step that reads one runs as a job, never synchronously. A string is refused: a storage key is not a caller’s to name, and anything else the engine would read as a path on its own disk. For the same reason a list is refused there (Sharp reads it as paths to join), and so is a {text: {fontfile}} layer — name an installed font with font.
3. Three keys are decoder directives, not Sharp methods. autoOrient, density and animated are read before the first byte is decoded, because by then the way the file is opened is already decided. Their position in steps does not matter.
4. Finishers run last, in your order; maxBytes runs after them. mask, blurRegion, overlay and caption need the finished pixels’ size, so they run once every other step has, as one composite and one encode. A mask declared before a blurRegion erases it. The byte budget is measured on the very end, so it is always the final act.
5. An unknown key is refused when you save; a wrong parameter shape, when the step runs. Saving checks the key (400 invalid_param on steps[i].operation) and the image parameters of rule 2, not the rest of params — that is Sharp’s signature, and a second copy would drift. Sharp checks it as the step is built: synchronously the call is 400 invalid_param naming the key; in a job the item fails on its first attempt with invalid_param and retryable: false. Never retried, never silently skipped.

One default sits under all of it: every pipeline orients the image by its EXIF tag before your first step, so crop, pad and resize speak the coordinates you see in a viewer. To keep the stored pixels untouched, add {"operation": "autoOrient", "params": false}.

Stability

The keys below are a closed set, and the set is what is promised. A key can be removed once an op replaces it — the replaced by column says which, and a step that can be written as an op should be. Parameter signatures follow the pinned Sharp version; a Sharp upgrade that changes a signature changes it here, without a compatibility layer. Ops keep a stable, validated contract for exactly this reason: prefer them.

What a preset is, how versions and subjects work, and how to run one: presets. Worked examples, ready to save: recipes. The ops themselves, with their parameter contracts: the op catalogue.