Preset Management

Create a preset

Saves version 1 and answers 201 with the preset as saved. Each step is {op, model?, prompt?, parameters?} — an op from GET /api/v1/ops — or {operation, params} — a processing-registry key, for what no op covers. Steps run in order, and they are checked when written, so a preset that saves is one a job can run (the 400s below name the step).

ANSWERS WITH warnings (advisory, the preset is saved): what the steps say that is legal and probably not meant — a format a later step shadows, a step the one before it already did.

NOT REFUSED: an AI step beside other steps, or several AI steps. Such a preset runs as one chain job, each item walking its segments in order (POST /api/v1/jobs).

LIMITS: at most 1000 presets per account, and 50 versions on record per preset (both 422 resource_limit_exceeded); built-ins do not count.

SLUG: generated from the name when absent (a numeric suffix keeps it unique); one you send must be free, lowercase letters, digits and hyphens, and not start with builtin-.

CONSISTENCY (subjects): each subject is {name, referenceAssetIds, descriptor}. The images ride along on the generate / edit step and pin the geometry; the descriptor expands into its prompt wherever you write {{subject.<name>}} (/docs/presets). At most 4 subjects and 4 images across all of them, each your own and DONE; a subject with no images is refused. A name is a handle ([a-z0-9][a-z0-9_-]{0,39}, unique in the preset), a descriptor at most 300 characters.

post/api/v1/presets

Request

  • Base URL: https://api.imagestep.dev
  • URL: https://api.imagestep.dev/api/v1/presets
  • Auth: API key in header Authorization

Headers

Idempotency-Keystring

Optional. A client-generated unique key (typically a UUID). Same key + the same request (method, path, query string and body) replays the first response verbatim with Idempotency-Replayed: true, without executing again. Same key + a different one returns 409 idempotency_key_reuse. A repeat that arrives while the first is still running returns 409 request_in_progress, which is retryable. Keys are retained 24 hours. At most 255 characters; a longer one is a 400 invalid_param with param: "Idempotency-Key".

Request body

idstring

Preset id (pre_…; a built-in's starts with builtin-). A job's presetId takes it, the slug, or either with @version.

namestring

Display name (required on create).

slugstring

URL-safe handle, unique per account: lowercase letters, digits and hyphens. Generated from the name when absent (a numeric suffix keeps it unique); one you send must be free. builtin- is reserved.

descriptionstring

Free text for people; not run. "" on a PUT empties it.

versioninteger

Starts at 1 and goes up whenever steps or subjects change; a name, description or slug edit is not a version. Run or read an earlier one as slug@version / ?version=N.

versionCountinteger

How many versions are on record: the current one plus every superseded one. Always present on a read, whether or not versions is, so a list reader can tell a preset with history from one without fetching it.

createdAtstring date-time

When the preset was created

updatedAtstring date-time

When the preset was last saved, a rename included — the order your own rows are listed in. On an earlier version read as slug@N, when that version was saved.

builtInboolean

Whether this is a built-in preset (read-only)

Example request

{
  "name": "Product cut-out, 1200 WebP",
  "slug": "product-cutout",
  "steps": [
    {
      "op": "resize",
      "parameters": {
        "width": 1200,
        "height": 1200,
        "fit": "contain"
      }
    },
    {
      "operation": "sharpen",
      "params": {
        "sigma": 0.5
      }
    },
    {
      "op": "convert",
      "parameters": {
        "format": "webp",
        "quality": 85
      }
    }
  ]
}

Response

The preset as saved, with warnings when there is something to say

Changes

No recorded changes to this operation across all 1 revision of this API.