Layer Image Editing

Layer Image Editing

Overview

Editing is not generation with an image attached. Each intent maps to its own use_case, and picking the wrong one is the usual reason an edit changes things it should not have touched.

The loop and the spend gate are in the layer skill. If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add layerai/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

Edit from the source, not from the last edit

Every edit pass is a fresh generation that re-renders the whole image, so each one drifts a little: colours shift, a face loses its likeness, a logo degenerates. Three passes stacked on each other look visibly worse than one pass that does all three things.

So when an edit is wrong, go back to the original and write a better instruction. Do not correct the correction. Output assets carry a file_id, so the original is always one argument away.

The exception is genuinely independent regions: masking the left lamp and then masking the right lamp touches disjoint pixels and stacks cleanly.

Masks

A mask marks what may change. Supply it as an uploaded file_id, or use the for_transparency and for_nontransparency flags when the image's own alpha channel already describes the region, which saves authoring a mask by hand for an asset that is already cut out.

Mask edges matter. A hard-edged mask on a soft-edged subject leaves a halo. When the boundary is hair, smoke, or glass, prefer an instruction edit over a mask, because the model resolves the boundary better than your rectangle does.

What to hold constant

State it in the instruction. Models are literal about what you mention and careless about what you do not, so "change the banner to red, keep the pose, lighting, and armour exactly as they are" is a materially different instruction from "make the banner red". The clause costs six words and saves a reroll.

Angles are not a prompt trick

"The same character from behind" appended to a text-to-image prompt produces a different character. Re-rendering an existing asset from another view needs multi_angle, a model whose capabilities report camera_transform, and the view supplied through the structured camera parameter, which orbits to side, back, or top, or zooms. Attach the source with the guidance type that model accepts.

Upscaling

Upscaling adds resolution without changing what the picture depicts. It must never route through a generation model: re-rendering at a larger size is a new image that merely resembles the approved one, and approved art has to survive the step unchanged. Use filter.use_case: "upscaling".

Layers

split_into_layers produces genuinely separate, independently editable elements, for rigging, parallax, or compositing. Before reaching for it, check what the user actually wants: "give me a PSD" usually means "give me the art with a transparent background", which is background_removal and far cheaper. Ask which one they mean when the request is ambiguous.

Worked example

"Take this approved hero portrait and make a 9:16 version for the store."

1. The intent is reframing, not a reroll of the portrait. Generating it again loses the approval.
2. list_base_models with filter.use_case: "reframing", take the first result.
3. The portrait came from an earlier run, so it already has a file_id. No upload.
4. estimate_forge_price with that file as init_image, the target ratio, and an instruction naming what must not change: "extend the scene above and below, keep the character, crop, and lighting untouched." Above 20 CUs, present the table and wait for an explicit yes.
5. execute_forge with exactly those arguments, then poll get_forge_run at poll_interval_seconds.
6. Present the result beside the original so the user can confirm the subject survived.

Common mistakes

• Stacking edits on edits instead of returning to the source image.
• Using image_editing when only one region should change, then explaining the collateral damage.
• Omitting what must stay constant.
• Appending "from behind" to a prompt instead of using multi_angle with camera.
• Re-rendering an approved asset through a generation model to make it bigger.
• Reaching for split_into_layers when the user just wants a transparent background.
• Uploading an asset Layer already produced, which already has a file_id.