Image Edit Capabilities

This page summarizes the current image-to-image edit contact sheets, command logs, and model/package status for MLX-Gen. It separates these related concepts:

• latent-img2img: whole-image variation or restyle from one source image. --image-strength controls how far the output may drift.
• edit-reference: instruction editing from one source image, usually with stronger composition hold than latent img2img.
• structured control: text-to-image generation guided by a control image. This is separate from source-image edit/inpaint.
• multi-reference: two or more images are supplied as references for one composition.
• generative reframe: larger-view generation with --reframe-padding. This is a zoom-out style edit, not source-preserving outpaint.
• canvas outpaint: canvas extension with --outpaint-padding, independent per side. Qwen Image Edit variants use generative canvas expansion plus adaptive source restoration. Every FLUX.2 Klein model — distilled 4B/9B and base 4B/9B — uses source-locked denoising and a narrow latent transition band instead of post-generation source pasting, and exposes the conditioning canvas through --outpaint-fill.

If you need a plain-language guide to choosing between these modes, see Image Edit Modes. For the current Qwen-specific route map and upstream pipeline correspondence, see Qwen route matrix.

Use mlxgen capabilities --model <model> to inspect route support before a run. Use the contact sheets and status tables below when you need visual release evidence for exact source handles or MLX-Gen optimized packages.

Status Labels

Status	Meaning
PASS	The row generated and the output visually satisfied the requested edit for this profile.
PARTIAL	The row generated and is usable for some work, but one requested constraint was weak.
FAIL	The row generated or routed, but the output did not satisfy the requested edit.
STALE	Historical evidence only. The row exists for review, but it is not the current contract.

The canonical validation source image is docs/assets/examples/spaceship-snow/01_t2i_spaceship_snow.png.

Regular Qwen Image Edit

Qwen/Qwen-Image-Edit is the original single-reference edit checkpoint. It supports edit-reference with one input image. It does not support multi-reference composition; use Qwen/Qwen-Image-Edit-2509 or Qwen/Qwen-Image-Edit-2511 for multi-reference edit routing.

Model	Package	Capabilities validated	Result
Qwen/Qwen-Image-Edit	source	pencil sketch, crash edit	PASS
AbstractFramework/qwen-image-edit-8bit	q8 optimized variant	pencil sketch, crash edit	PASS
AbstractFramework/qwen-image-edit-4bit	mixed q4/q8 optimized variant	pencil sketch, crash edit	PASS

These rows used a 768x432, 30-step, guidance 4 profile with --scheduler flow_match_euler_discrete.

Qwen Masked Edit / Inpaint

MLX-Gen exposes masked edit on the Qwen edit route through --mask-path. The current exact accepted proof row is:

• AbstractFramework/qwen-image-edit-2511-8bit on qwen.inpaint

This first public proof is intentionally narrow. It validates the q8 route only, uses one source image plus one mask at a time, and keeps the rest of the Qwen structured-control backlog separate until those rows have their own visible proof.

Model	Package	Capabilities validated	Result
AbstractFramework/qwen-image-edit-2511-8bit	q8 optimized variant	masked edit / inpaint with --mask-path	PASS

The proof uses the dedicated lightx2v/Qwen-Image-Edit-2511-Lightning adapter as the recommended fast public path for 4-step masked edits. The published contact sheet compares the practical regular 20-step q8 path against the 4-step Lightning path on two conditions:

• engine enhancement inside a small localized mask;
• crash repair inside a larger hull/cockpit mask.

MLX-Gen also publishes a same-canvas control sheet using the Lightning adapter in both result columns. Those rows use the same 768x432 source image, the same prompt, the same seed, and the same Lightning adapter. The only difference is --mask-path. Without --mask-path, the model is free to recompose the whole scene, so framing drift is expected. With --mask-path, the edit stays local:

Exact commands and timings:

• masked edit command log
• masked edit timings on M5 Max

Qwen Structured Control

MLX-Gen exposes one exact Qwen structured-control route through --controlnet-image-path. The current accepted public row is:

• AbstractFramework/qwen-image-8bit on qwen.control
• exact sidecar: InstantX/Qwen-Image-ControlNet-Union:diffusion_pytorch_model.safetensors

This slice is intentionally narrow. It is a text-to-image route with one control image, not a source-image edit route. Base-Qwen localized control-inpaint has its own separate validated row below.

Model	Package	Capabilities validated	Result
AbstractFramework/qwen-image-8bit	q8 optimized variant	structured control with --controlnet-image-path	PASS

The accepted proof uses the dedicated lightx2v/Qwen-Image-Lightning adapter as the fast 4-step path and compares same-prompt, same-seed no-control versus controlled runs on two conditions:

• canny-guided pagoda layout;
• pose-guided portrait layout.

In both rows, the control image materially changes layout while the no-control baseline stays on the same prompt, seed, and Lightning adapter. That is the proof that the control image is doing real work rather than only the prompt carrying the scene.

Exact commands and timings:

• structured-control command log
• structured-control timings on M5 Max

Qwen Base Control-Inpaint

MLX-Gen exposes one exact base-Qwen localized control-inpaint route through the same public image + mask + prompt request shape. The current accepted public row is:

• AbstractFramework/qwen-image-8bit on qwen.control-inpaint
• exact sidecar: InstantX/Qwen-Image-ControlNet-Inpainting:diffusion_pytorch_model.safetensors

This route is different from Qwen edit masked inpaint. It keeps the generic --mask-path user contract, but the backend is the base Qwen model plus the dedicated inpainting ControlNet sidecar.

Model	Package	Capabilities validated	Result
AbstractFramework/qwen-image-8bit	q8 optimized variant	base-Qwen control-inpaint with --mask-path	PASS

The accepted proof is still narrow and exact:

• same 768x432 source image, mask, prompt, and seed across the comparison row;
• exact Qwen Lightning 4-step fast path;
• two localized conditions: engine enhancement and crash repair.

Published artifacts:

• control-inpaint report
• control-inpaint command log
• control-inpaint timings on M5 Max

Qwen 2509 And Distilled FLUX.2 Matrix

The 5x4 edit validation profile tests the same spaceship source across:

• B: cinematic latent/style variation;
• C: crash edit from the source image;
• D: pencil sketch edit;
• E: multi-reference composition from the model's own pencil/crash and cinematic rows.

Family	Exact handles/packages	Modes validated	Result summary	Contact sheet
FLUX.2 Klein 4B distilled	black-forest-labs/FLUX.2-klein-4B, AbstractFramework/flux.2-klein-4b-8bit, AbstractFramework/flux.2-klein-4b-4bit	latent-img2img, edit-reference, multi-reference	source, q8, and q4 passed B/C/D/E	matrix
FLUX.2 Klein 9B distilled	black-forest-labs/FLUX.2-klein-9B, AbstractFramework/flux.2-klein-9b-8bit, AbstractFramework/flux.2-klein-9b-4bit	latent-img2img, edit-reference, multi-reference	source, q8, and q4 passed B/C/D/E	matrix
Qwen Image Edit 2509	Qwen/Qwen-Image-Edit-2509, AbstractFramework/qwen-image-edit-2509-8bit, AbstractFramework/qwen-image-edit-2509-4bit	edit-reference, multi-reference	source and q8 passed B/C/D/E; q4 passed B/C/D and was partial on E	matrix
Qwen Image Edit 2511	Qwen/Qwen-Image-Edit-2511, AbstractFramework/qwen-image-edit-2511-8bit, AbstractFramework/qwen-image-edit-2511-4bit	edit-reference, multi-reference	source, q8, and q4 passed the 2026-06-06 pencil/crash/composition profile	matrix
FIBO Edit	briaai/Fibo-Edit	Not supported through unified mlxgen generate	no public image-edit support in the current release; capability discovery fails closed	N/A

Base FLUX.2 Klein source models have a separate starship proof set because their canvas-expansion contract is different: base models do not expose reframe.

Reframe And Outpaint

--reframe-padding and --outpaint-padding are single-image edit-reference routes. Reframe is a generative zoom-out workflow. Outpaint splits by backend: Qwen Image Edit uses generative canvas expansion plus adaptive source restoration, while every FLUX.2 Klein model runs strict outpaint with source-locked denoising and an interior transition band. Distilled Klein publishes both routes as separate capability rows, flux2.reframe and flux2.outpaint; base Klein publishes flux2.outpaint only.

Exact LoRA-backed public proof exists for:

• AbstractFramework/qwen-image-edit-2511-8bit on qwen.reframe
• AbstractFramework/qwen-image-edit-2511-8bit on qwen.outpaint
• AbstractFramework/flux.2-klein-base-4b-8bit on flux2.outpaint

See LoRA for those exact route-level A/B sheets.

Family	Exact handles/packages	Reframe	Outpaint	Contact sheet
Qwen Image Edit	Qwen/Qwen-Image-Edit, AbstractFramework/qwen-image-edit-8bit, AbstractFramework/qwen-image-edit-4bit	source/q8/q4 PASS	source/q8/q4 PASS	matrix
Qwen Image Edit 2509	Qwen/Qwen-Image-Edit-2509, AbstractFramework/qwen-image-edit-2509-8bit, AbstractFramework/qwen-image-edit-2509-4bit	source/q8/q4 PASS	source/q8/q4 PASS	matrix
Qwen Image Edit 2511	Qwen/Qwen-Image-Edit-2511, AbstractFramework/qwen-image-edit-2511-8bit, AbstractFramework/qwen-image-edit-2511-4bit	source/q8/q4 PASS	source/q8/q4 PASS	matrix
FLUX.2 Klein 4B	black-forest-labs/FLUX.2-klein-4B, AbstractFramework/flux.2-klein-4b-8bit, AbstractFramework/flux.2-klein-4b-4bit	source/q8/q4 PASS	q8 PASS on the latent-lock profile; June 8 edit-path rows STALE	matrix, latent-lock outpaint
FLUX.2 Klein 9B	black-forest-labs/FLUX.2-klein-9B, AbstractFramework/flux.2-klein-9b-8bit, AbstractFramework/flux.2-klein-9b-4bit	source/q8/q4 PASS	q8 PASS on the latent-lock profile; June 8 edit-path rows STALE	matrix, latent-lock outpaint
FLUX.2 Klein Base 9B	black-forest-labs/FLUX.2-klein-base-9B, AbstractFramework/flux.2-klein-base-9b-8bit, AbstractFramework/flux.2-klein-base-9b-4bit	not exposed	source PASS; prepared package proof pending	edit matrix, seams
FLUX.2 Klein Base 4B	black-forest-labs/FLUX.2-klein-base-4B, AbstractFramework/flux.2-klein-base-4b-8bit, AbstractFramework/flux.2-klein-base-4b-4bit	not exposed	source PASS; multi-reference row PARTIAL; prepared package proof pending	edit matrix, seams

Strict FLUX.2 outpaint runs on every Klein model. Guidance is the setting that does not carry across the two weight families: base Klein runs true CFG at 4.0, and step-distilled Klein runs at 1.0. Omit --guidance and each model takes its own default. Prepared base Klein q8/q4 packages expose the same route surface through mlxgen capabilities, and their starship contact-sheet proof is still pending. Base Klein reframe is intentionally rejected.

Use the dedicated Reframe and Outpaint guide for copy/pasteable examples, canvas/mask assets, the validation manifests, and exact commands. The mixed June 8 profile id is reframe_outpaint_2026_06_08, the FLUX.2 Klein base source-model profile id is flux2_klein_base_starship_2026_06_10, and the distilled strict-outpaint profile id is flux2_klein_outpaint_latent_lock_2026_09_01.

Every supported route run on one source at one padding value, with per-route timings and source drift, is published in Reframe and Outpaint; the artifacts, command log and measurements live in outpaint-model-matrix-2026-09-01.

Outpaint padding is independent per side, so one call can extend a single side, both sides of an axis, or all four at different depths. Expanding On Any Side covers that surface on AbstractFramework/flux.2-klein-9b-8bit: three source aspect ratios (landscape 640x448, square 512x512, portrait 448x640) run through eight padding configurations each, at 16 steps, guidance 1, seed 99 and an empty prompt. Contact sheets, per-band measurements and the command log are in outpaint-axis-coverage-2026-09-02.

These workflows are not native masked fill/inpaint pipelines. Reframe remains openly generative. Strict FLUX.2 outpaint aims to keep the source crop stable, but relies on latent-space editing rather than direct pixel masking: the source region is decoded from latents, so it is reproduced rather than preserved bit-for-bit. Every run records how far the source region moved as outpaint_source_restore_difference in its metadata sidecar. Use masked editing when a region must stay untouched.

Outpaint Capability Fields

Outpaint-capable capability rows publish the conditioning-canvas contract and the validated envelope, so an application can read both from mlxgen capabilities JSON before starting a job. The payload carries schema_version 16.

Field	flux2.outpaint on flux.2-klein-base-4b-8bit	flux2.outpaint on flux.2-klein-4b-8bit	qwen.outpaint on qwen-image-edit-2511-8bit
supports_outpaint	true	true	true
supports_outpaint_fill	true	true	false
outpaint_fill_modes	["auto", "edge", "neutral", "solid", "blur"]	["auto", "edge", "neutral", "solid", "blur"]	["edge"]
outpaint_default_fill_mode	"auto"	"auto"	"edge"
outpaint_auto_edge_fill_max_stretch	12.0	12.0	null
outpaint_recommended_lora	"fal/flux-2-klein-4B-outpaint-lora"	null	null
outpaint_preservation	"adaptive-content-aware-source-blend"	"adaptive-content-aware-source-blend"	"adaptive-content-aware-source-blend"
outpaint_validated_padding	"5%,80%,5%,60%"	"5%,80%,5%,60%"	"5%,80%,5%,60%"
outpaint_validated_fill_mode	"edge"	"edge"	"edge"
outpaint_validated_max_canvas_pixels	282880	282880	282880
outpaint_pass_modes	["auto", "1", "2"]	["auto", "1", "2"]	["auto", "1", "2"]
outpaint_default_passes	"auto"	"auto"	"auto"
outpaint_auto_split_corner_ratio	0.3	0.3	0.3
lora_status	"validated"	"mapped-unvalidated"	"validated"

Base and distilled Klein publish the same conditioning-canvas contract because they run the same route. outpaint_recommended_lora and the outpaint_validated_* envelope are published per route, so each row states only its own evidence: the green-canvas adapter is trained on FLUX.2 Klein base 4B and its A/B proof is a base row, so distilled rows carry outpaint_recommended_lora: null.

supports_outpaint_fill: false alongside a single-entry outpaint_fill_modes means the fill algorithm is fixed for that route: the Qwen edit backend always builds an edge-extended canvas and takes no --outpaint-fill option. Asking such a route for a different mode is refused by route, naming the capability and the fixed canvas. Rows that do not support outpaint report supports_outpaint and supports_outpaint_fill as false, empty outpaint_fill_modes, and null for the rest.

outpaint_pass_modes and outpaint_default_passes publish the --outpaint-passes contract, and outpaint_auto_split_corner_ratio the depth past which auto runs a request that pads both axes as two single-axis passes (the shallower of the deepest vertical padding over the source height and the deepest horizontal padding over the source width; null on a route that never splits). See Deep Padding On Two Axes.

outpaint_preservation names how the route keeps the source pixels, and is the same string the generated artifact records in its metadata. Every outpaint route publishes adaptive-content-aware-source-blend: the source region is held in latent space behind a narrow transition band while the canvas is denoised (FLUX.2 Klein through its own lock, Qwen Image Edit through its masked-edit input), then the original crop is pasted back while the generated source window still matches it.

The validated envelope is the padding, fill mode, and canvas size the published proof runs used. Outside it, outpaint is supported but unvalidated. outpaint_recommended_lora is optional: the route runs without it, and LoRA carries the A/B sheet for the adapter. For the option surface and the printed run line, see Outpaint Conditioning Canvas.

FLUX.2 Klein 4B

This matrix validates source, q8, and q4 packages on the same canonical spaceship source. The columns cover the standardized sequence: source image, cinematic latent variation, hard-landing edit, pencil-sketch edit, and multi-reference composition.

FLUX.2 Klein 9B

This matrix validates source, q8, and q4 packages on the same canonical spaceship source. The columns cover the same standardized sequence as Klein 4B so the two model sizes can be compared directly.

FLUX.2 Klein Base 4B And 9B Source Proof

The current base-model proof uses the cropped starship source across source-model base 4B/9B only. It validates latent img2img, single-image edit-reference, multi-reference, and strict outpaint on the same starship case. Source-model text-to-image smoke is published separately.

The dedicated seam-review sheet zooms the source-window boundaries for the strict outpaint rows:

Source-model text-to-image smoke:

Qwen Image Edit 2509

This matrix validates the Qwen Image Edit 2509 source checkpoint plus q8 and q4 MLX-Gen optimized packages. Source and q8 pass the full standardized edit-reference and multi-reference sequence; q4 remains partial on the multi-reference composition row in this profile.

Qwen Image Edit 2511

The current Qwen Image Edit 2511 proof uses the same source image across the upstream source checkpoint, the q8 MLX-Gen package, and the q4 MLX-Gen package. The profile validates a single-image pencil sketch, a single-image hard-landing crash edit, and a two-reference composition from the generated pencil and crash images.

FIBO Edit

FIBO Edit is not a supported public image-edit route in MLX-Gen at the moment. mlxgen capabilities --model briaai/Fibo-Edit exposes no unified generation capabilities for this model. The dedicated compatibility command remains for maintainer parity work, but user-facing image editing should use Qwen Image Edit, Qwen Image Edit 2509/2511, or FLUX.2 Klein routes with passing contact sheets.

Latent I2I Only

Some image models support latent image-to-image variation but are not edit/reference models. In the standard spaceship profile, Z-Image Turbo and ERNIE Image Turbo q4/q8 packages passed the single latent cinematic variation row. Qwen Image 2512 q4/q8 ran the latent route but did not preserve the spaceship identity for this prompt, so it is not documented here as a good edit model.

Use latent I2I for style/variation workflows, not precise composition or object-state editing:

mlxgen generate \
  --model AbstractFramework/z-image-turbo-8bit \
  --image docs/assets/examples/spaceship-snow/01_t2i_spaceship_snow.png \
  --i2i-mode latent \
  --image-strength 0.35 \
  --prompt "Make this same spaceship in the snow look like polished cinematic science-fiction concept art at blue hour. Preserve the exact camera angle, ship position, snowy canyon, and overall layout. Sharpen hull panels and add cold blue shadows; no crash, no damage." \
  --width 432 \
  --height 240 \
  --steps 20 \
  --seed 9201 \
  --output output.png

Z-Image Turbo Native Inpaint

Z-Image Turbo has one exact native inpaint proof row through unified mlxgen generate:

• AbstractFramework/z-image-turbo-8bit on z-image.inpaint

This is intentionally narrower than the Qwen edit surface. The accepted public proof is one same-prompt same-seed engine-thruster case that compares the latent route against the mask route on the same source image.

Model	Package	Capabilities validated	Result
AbstractFramework/z-image-turbo-8bit	q8 optimized variant	native inpaint with --mask-path	PASS

The accepted row compares:

• latent baseline: same source, prompt, and seed with --image-strength 0.35
• native inpaint: same source, prompt, and seed with --mask-path

The masked-area crop sheet is published separately because that is where the route difference is most readable:

Published artifacts:

• native-inpaint report
• native-inpaint command log
• native-inpaint timings on M5 Max

Masked Edit 5x5 Matrix (FLUX.2 Klein, Base Qwen, Z-Image Non-Turbo)

The masked-edit routes shipped in 0.20.0/0.21.0 have a standardized multi-case matrix: one shared source, five masks (object insertion, lens recolor, arm retexture, sticker removal, and an unscored partial-object-removal limitation demonstration), same seed, five exact rows.

Model	Route	insert	recolor	retexture	sticker removal	Aggregate
AbstractFramework/flux.2-klein-4b-8bit	flux2.inpaint	PASS	PASS	PASS	PASS	PASS
AbstractFramework/flux.2-klein-base-4b-8bit	flux2.inpaint	PASS	PASS	PASS	PASS	PASS
Qwen/Qwen-Image (source bf16)	qwen.base-inpaint	PASS	PARTIAL	PASS	PASS	PARTIAL
AbstractFramework/qwen-image-4bit	qwen.base-inpaint	PASS	PARTIAL	PASS	PASS	PARTIAL
AbstractFramework/qwen-image-2512-8bit	qwen.base-inpaint	PASS	PARTIAL	PASS	PASS	PARTIAL
AbstractFramework/z-image-8bit	z-image.inpaint	PASS	PARTIAL	FAIL	PASS	FAIL

The PARTIAL and FAIL cells are documented behavior, not gaps in the proof, and both led to shipped consequences: the base-Qwen warm start anchors masked content to the source at the default --mask-strength 0.85 (the measured 0.95 setting recolors fully — s095 regression sheet in the bundle), and the non-turbo Z-Image geometry artifact reproduced across seeds and CFG settings, so non-turbo Z-Image masked editing is withdrawn from the public surface for the moment (the row above stays as the withdrawal evidence). See Masked editing for route-selection advice and the matrix bundle for zoom sheets, preservation metrics, prompts, and the seed-43 reproduction of the Z-Image failure. Registry profile: masked_edit_matrix_5x5_2026_07_15.

Exact Validation Commands

The full command logs are published with the proof assets:

• regular Qwen Image Edit command log
• Qwen Image Edit 2511 parity command log
• Qwen Image Edit 2511 masked edit command log
• Qwen base control-inpaint command log
• Z-Image Turbo native inpaint command log
• 5x4 FLUX.2 and Qwen Image Edit 2509 command log
• reframe and outpaint command log
• FLUX.2 Klein base starship command log
• latent I2I command log