Apply a transform recipe at full resolution and issue a new revision. Pass either recipe ({"operations": [...]}, applied in order, at most one "encode" and it must be last) or preset (a built-in named recipe) - exactly one of the two - and either revision_id (one image) or revision_ids (the same recipe over a batch of up to 64; one failure does not abort the rest). Call list_operations for the operation catalog and the preset names, explain_operation for one operation's full schema. Idempotent: the same (revision_id, resolved recipe) returns the existing derived revision; a preset hashes identically to the equivalent raw recipe. Note: if the recipe's encode format is png, webp, or avif, any ICC color profile on the source is dropped (embedding is only supported for jpeg output); this is reported as a warning, not an error.

Scale two revisions to a long edge of 640px each and compose them on one canvas (side by side, or stacked) with an 8px gap, returned inline as a JPEG. A is placed left/top, B is placed right/bottom. Useful for before/after or A/B visual checks. layout="diff" instead requires A and B to share the exact same dimensions and returns a single pixel-difference heatmap plus mean_abs_diff/max_abs_diff/changed_pixel_ratio.

Detect the dominant quadrilateral (a sheet of paper, a screen, a whiteboard, a sign) in a revision with a contour-based search, and return it as a ready-to-paste perspective operation. This is to perspective what detect_tilt is to rotate: read-only, it never modifies the image, and a null quad means "do not correct". The quad is in post-EXIF-orientation pixel coordinates, ordered tl, tr, br, bl, and output_size_hint is exactly the size perspective will produce from it. Optional min_area_ratio (0.05..=1.0, default 0.2) is the smallest fraction of the frame a candidate may cover. When quad is null the reason is the first warning: no_quad_found, already_rectified (the page already fills the frame) or low_confidence.

Detect the tilt (roll) of a revision: Canny + Hough dominant lines for coarse candidates, refined below 0.1 degree with an edge projection-profile search. Horizontal-only and vertical-only estimates are reported separately so a disagreement can be read as perspective/camera position rather than roll, Set include_score_curve=true to also get the whole search range as a score curve (omitted by default to keep the answer small). Read-only: it never modifies the image. A null recommended angle means "do not correct".

Full reference for one recipe operation: every parameter with its type, range, required/default status and semantics, one or two ready-to-paste JSON examples, and the gotchas worth knowing before using it. A built-in preset name works too and returns its full operation list, so a preset can be read and copied as a raw recipe. An unknown name returns a structured error listing every valid operation and preset. Read-only.

Copy a revision's bytes out of the workspace to a destination path. Refuses to overwrite an existing file unless overwrite=true (ask the user first).

Generate a deterministic grayscale mask as a new PNG revision, with exactly the dimensions of reference_revision_id. kind is "linear_gradient" (angle_degrees, start, end), "radial_gradient" (center_x, center_y, radius, feather), "luminosity_range" (min, max, feather) or "color_range" (hue_center, hue_width, feather); the gradients use only the reference's dimensions, the other two compute weights from its pixels. White = the masked operation applies fully, black = not at all. Reference the returned revision_id from any tone/filter operation as "mask": {"revision_id": "rev_...", "invert": false, "feather_px": 0}, or visualise it with render_preview overlay="mask". Idempotent: the same params over the same reference produce byte-identical PNG bytes and return the existing revision.

Import a local image file into the workspace and issue an immutable revision. Pass either path (one file) or paths (a batch of up to 64; one bad file does not abort the batch, it lands in failed) - exactly one of the two. Idempotent: importing the same bytes again returns the existing revision. If the imported bytes are already the output of a recipe held in this workspace, the result carries a warning plus already_derived_from so the same recipe is not applied twice.

Inspect a revision: dimensions, MIME type, byte size, alpha/ICC presence, EXIF orientation and summary, and whether GPS (PII) metadata is present.

List revisions in the workspace ledger (lineage, recipe hash, dimensions, sizes).

Compact catalog of the recipe vocabulary: every operation with a one-line description and its parameter names with terse type/range hints, plus the built-in preset names. Optional category ("geometry" | "color" | "filter" | "output") narrows the list. Call explain_operation for the full schema of one operation. Read-only.

Render a recipe as a small JPEG preview (long edge <= 768 by default) and return it inline plus a file path, so the composition can be checked before committing to apply_transform. Takes either recipe or preset, exactly like apply_transform. Optional long_edge (256..=1568) sets the preview size: raise it to 1568 when the point of the preview is to READ text in the image; 768 is too small for that. Optional overlay ("grid" | "thirds" | "horizon") draws semi-transparent composition guide lines on the returned preview only (never on the apply_transform output). overlay="mask" instead visualises a mask: pass mask_revision_id (required for this overlay and rejected for the others) and the preview is tinted red where the mask weight exceeds 0.5 and dimmed elsewhere, so the coverage can be eyeballed. Note: if the recipe's encode format is png, webp, or avif, any ICC color profile on the source is dropped (embedding is only supported for jpeg output); this is reported as a warning, not an error.