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 and an ssim score (structural similarity, 1.0 = identical). Every layout also reports perceptual_hash_distance: the Hamming distance between the two dHash values (0..=64), where 5 or less usually means the same picture re-encoded or resized and 20 or more means two different pictures.

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.

Find the text-like blocks (headline, paragraphs, table, caption) of a revision with a binarize + run-length smearing + connected-components pass, and report whether the text will survive a preview downscale. Read-only: it never modifies the image. Blocks come back in reading order (top to bottom, then left to right) in post-EXIF-orientation pixel coordinates, each with its line_count, median_line_height_px and ink_ratio. legibility.line_height_at_1568_px is the median line height once the whole image is shrunk to long edge 1568 (below ~16 the text is usually unreadable), and legibility.recommended_bands splits the image into crops that clear that bar - each entry is already a crop operation, so paste one into a recipe before render_preview long_edge: 1568 and read them in order. legibility.strategy says how it split: "whole" (no split needed), "bands" (full-width horizontal bands) or "blocks" (per-block crops, used when the image is too wide for full-width bands to help). Optional max_blocks (1..=128, default 32) and min_block_area_ratio (0.0..=1.0, default 0.00005) bound how many and how small the blocks may be. No block found means the image has no text-like structure, not an error.

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 revisions' bytes out of the workspace. Pass either revision_id + dest_path (one file) or revision_ids + dest_dir (a batch of up to 64 into one existing directory; one failure does not abort the rest) - exactly one of the two forms. For a batch, filename_template (default "{revision_id}.{ext}") builds each file name from {revision_id} / {index} (1-based, zero-padded) / {ext} (from the MIME type) / {stem} (the file name the lineage was imported from); it must be a plain file name, and if two entries would collide nothing is written. Refuses to overwrite an existing file unless overwrite=true (ask the user first), and never writes inside the workspace store or through a symbolic link.

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, whether GPS (PII) metadata is present, luma statistics, a sharpness score (variance of the Laplacian - relative, so compare it against a known-good capture rather than an absolute; for documents below ~30 usually means motion blur or defocus) and a perceptual_hash (dHash, 16 hex digits) for telling "is this the same picture?" without comparing pixels. Set include_exif=true to also get every EXIF field as {ifd, tag, value} entries; it is off by default because the full dump can carry GPS coordinates and names.

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 - or NEITHER, which previews the revision as it is (use this with overlay="grid" to read crop coordinates off an image before writing a recipe). 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.