The Mask Editor: Inpaint and Iterate on One Region

Regenerating an image to fix one detail re-rolls every pixel: the background you liked is gone, the light shifts, and you have a new problem. Inpainting masks only the region you want to change, fills it from a short prompt, and leaves everything else pixel-identical.

Inpaint or regenerate?

One question decides it: do you want to keep everything except one thing?

  • Keep it, so inpaint. One wrong element in an image you otherwise like: a held prop, a sign with a typo, an off-color object. Everything outside the mask is preserved exactly, which is the guarantee regeneration cannot give you.
  • Change the whole feel, so regenerate. Wrong composition, angle, mood, or palette is not a one-region problem, and neither is a change scattered across the frame (you paint one mask per call).

While you are still exploring, regenerate at quality: low. Reach for the mask once you have a keeper worth protecting.

The loop, start to finish

Here it is on a cinematic frame: a pirate boarding battle, where we want to swap the arm in the foreground for a cannon firing into the shot.

Ask your agent to open the image in the mask editor, and it makes the call for you:

agentbrush_edit_mask_open({ image_path: "images/boarding-battle.png" })

The editor opens in your browser. Type what should fill the region you are about to paint.

Brush over only the region to change. Everything under the red overlay is in play; everything else is locked.

Hit Generate and accept the result. Ask your agent to pull it back into your project, and it calls:

agentbrush_edit_mask_result()

The arm is now a cannon firing into the frame. The crew, the rigging, the smoke, and the light are pixel-identical to the original.

The whole loop, recorded live:

For scripted pipelines, agentbrush_edit_mask does the same in one call. Either way the cost matches generation: low 1 token, medium 5, high 20. Start at low to confirm the content before you commit.

Prompt the region, not the picture

A masked edit is the synthetic-prompt rule at its extreme: the surrounding image is your reference, so say as little as possible. The prompt that produced the cannon was one line, "Replace the arm with a cannon firing in the foreground."

  • Describe what goes in the region, briefly. The model reads the rest of the frame for light, texture, and style; you only point at the patch.
  • Match the register. A photoreal scene wants a photoreal description, a flat illustration wants flat terms. A mismatch shows up as a seam.
  • Add a scale cue for unusual objects. "A data chip the size of a credit card" anchors it to the visible context.
  • Do not re-describe the whole image. You already have it. Re-stating the scene only gives the model room to drift.

Where it breaks down

Big regions. Mask much more than a third of the frame and the boundary starts to show. Regenerate instead.

Scattered changes. One mask per call. A correction in three places means three passes and three seams; a full regenerate with the good version passed as a reference_image_paths anchor is cleaner.

Pose and geometry. Inpainting swaps objects and textures well. It will not re-pose a limb: the surrounding geometry constrains whatever fills the mask.

Hard seams on busy texture. Fur, foliage, and detailed fabric can show an edge. Naming the surrounding texture helps; it is not always solvable in the prompt.

FAQ

Does the mask persist between tries? Yes. Re-running with a new prompt retries the same region; you only repaint when you want to change the region itself.

Can I inpaint a transparent PNG? No, inpainting needs an opaque image. Edit first, then run agentbrush_remove_background on the result.

Why does my patch not match the scene? Usually a prompt that skipped the style register. Name the look and the lighting. If a seam survives several tries, the region is probably too large or the geometry too constrained, so regenerate the full image instead.

How is it billed? Like generation: 1, 5, or 20 tokens for low, medium, high. There is no separate inpainting rate.

For prompting technique, see the AgentBrush prompting guide. To hold a subject steady across whole images rather than one region, generating consistent images from reference images is the complement to inpainting.

Ready to try it? Connect AgentBrush to your agent and open an image with agentbrush_edit_mask_open. The editor is in your browser in seconds.