layer
Layer management. op: create | create_group | delete | duplicate | select | set | reorder | merge_down | flatten (a group is created, addressed and reordered like any layer; there is no separate group tool). Address a layer by layer_id (an id from inspect or a previous layer / bake result) or by layer (its name; names can repeat, so layer_id is the only handle that always tells two apart). Every op except select changes pixels or layer structure, and there is no undo in this session: checkpoint first when in doubt. create adds an empty layer (width/height default to the photo size; fill white, black or transparent, default transparent). create_group adds a group (a folder for other layers). delete removes a layer (a group takes its children with it) and its filters; REFUSED if it is or contains the photo's only remaining layer. duplicate copies a layer directly above the source; REFUSES when the layer (or, for a group, any layer in it) carries an Editmamei filter, since the copy's filter would collide with the original's record: bake it first or delete the filter, then duplicate. select sets the active layer (the default target of add_adjustment and friends when no layer is named) and changes nothing else. set changes opacity, mode (a blend mode from a fixed list), visible and/or name (at least one is required; a name may not be empty). Names are kept unique by suffixing " 2", " 3", ... when taken. reorder changes a layer's stack position and/or moves it into a group (parent_group) or out to top level (to_top_level: true); giving neither keeps the layer in its current group and only changes position; REFUSED if parent_group would nest a group inside itself or one of its own descendants. merge_down bakes ONE layer's live filters (masked ones included) into pixels and merges it into the first VISIBLE layer below it at the same level; REFUSES if the source layer itself is hidden, if the target would be a group, if there is no visible layer below (a hidden one in between is skipped, not merged), or if the result would exceed the size cap resize enforces; a visible text layer involved is rasterized (reported as rasterized_text). flatten collapses the WHOLE photo into a single layer the same way, always drops transparency (reported as has_alpha: false), and REFUSES by default when any layer is hidden, INCLUDING a visible layer inside a hidden group, rather than silently discarding it (discard_hidden: true proceeds and reports what was discarded). On this server a created layer's width x height must stay within the workspace's pixel limit (less at a higher bit depth), and a photo's layers together within its layer limit, each counted at the canvas size (or the largest layer size used in the photo, if bigger).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| op | Yes | 'create' adds a new, empty layer (width/height default to the image size, capped the same way resize's target is; fill white/black/transparent, default transparent). 'create_group' adds a group layer (a folder for other layers). 'delete' removes a layer (a group takes its children with it) and prunes any of its filters from the ledger — REFUSED if it is or contains the image's only remaining layer. 'duplicate' copies a layer, inserted directly above the source — REFUSED when the layer (or, for a group, any descendant) carries an Editmamei filter, since the copy's filter would collide with the original's own ledger record. 'select' sets the active layer (the default target for add_adjustment and friends when no layer is named) and is the one sub-op that changes nothing else. 'set' changes opacity, mode, visible, and/or name (at least one required, name may not be empty) — mode is a blend mode from a fixed list, not a raw name. 'reorder' changes a layer's stack position and/or moves it into a group (parent_group) or out to top-level (to_top_level: true) — neither given keeps the layer in its current group and only changes `position`; REFUSED if parent_group would nest a group inside itself or one of its own descendants. 'merge_down' bakes ONE layer's live filters (masked ones included) into pixels and merges it into the first VISIBLE layer below it in the same group/level — REFUSED if the SOURCE layer itself is hidden (the editor cannot merge a hidden layer down), if that target would be a group, if there is no visible layer below (a hidden one in between is skipped, not merged), or if the merged result would exceed the same size cap resize enforces; a visible text layer involved is rasterized (reported as rasterized_text). 'flatten' collapses the WHOLE image into a single layer the same way, always drops alpha (reported as has_alpha: false), and REFUSES by default when any layer is hidden, INCLUDING a layer whose own visibility is on but sits inside a hidden group (the editor discards a hidden layer outright rather than compositing it in) unless discard_hidden: true is given. | |
| fill | No | create only. The new layer's initial content. | transparent |
| mode | No | set only. A blend mode from a fixed list. 'color' here is HSL-style, a little different from fill's 'color'. | |
| name | No | create/create_group: the new layer's name (default 'Layer'/'Group'). set: renames the target layer; may not be empty. Every case enforces a unique name, suffixing " 2", " 3", ... if the name is already taken (duplicate names are possible elsewhere; this tool does not allow them). | |
| image | Yes | Image id, as returned by open_photo. | |
| layer | No | Layer name. Defaults to the selected layer, or the topmost layer if none is selected. Ignored when layer_id is given. Not used by create, create_group, or flatten. | |
| width | No | create only. Defaults to the image width. | |
| height | No | create only. Defaults to the image height. | |
| opacity | No | set only. | |
| visible | No | set only. | |
| layer_id | No | Canonical layer id (from inspect or a prior layer/bake result) — takes priority over `layer` (name) when both are given, and is the only way to address two layers that happen to share a name. Not used by create, create_group, or flatten. | |
| position | No | create/create_group/reorder: index within the target parent's (or top-level) stack, 0 = topmost. | |
| parent_group | No | create/create_group: the group layer_id to insert the new layer into (omit for top-level). reorder: the group layer_id to move the layer into. Must itself be a group, and cannot be the layer being moved or one of its own descendants. Omit (leaving the layer in its current group) or use to_top_level instead to move it OUT of a group — there is no way to pass "no group" through this field itself. | |
| to_top_level | No | reorder only. Moves the layer to the top level, out of whatever group (if any) it is currently in. Takes priority over parent_group if both are given. | |
| discard_hidden | No | flatten only. Without it, flatten REFUSES when any layer is hidden (naming them) rather than silently discarding them — pass true to proceed; the discarded layers are reported back as discarded_hidden_layers. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| name | No | ||
| deleted | No | ||
| opacity | No | ||
| visible | No | ||
| is_group | No | ||
| layer_id | No | ||
| has_alpha | No | ||
| parent_group | No | ||
| rasterized_text | No | ||
| discarded_hidden_layers | No |