[Modular]: Add Z-Image Inpaint and Controlnet Inpaint modular pipeline

[lucasruan1618]

What does this PR do?

This PR adds inpainting and ControlNet inpainting support for Z-Image through [ModularPipeline]. The pipeline selects the workflow from the supplied inputs:

• Passing image and mask_image runs Z-Image inpainting.
• Passing image, mask_image, and control_image, after registering a compatible ControlNet, runs Z-Image ControlNet inpainting.

The ControlNet is registered through pipe.update_components(controlnet=controlnet). Transformer modules are linked when the component is registered, rather than mutating registered pipeline components during inference.

Modular inpainting example

import torch

from diffusers import ModularPipeline
from diffusers.utils import load_image


pipe = ModularPipeline.from_pretrained("Tongyi-MAI/Z-Image-Turbo")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")

image = load_image(
    "https://github.com/lucasruan1618/Image_storage/blob/main/Input/cute_cat.png?raw=true"
).convert("RGB")
mask_image = load_image(
    "https://github.com/lucasruan1618/Image_storage/blob/main/Input/mask_cat.png?raw=true"
).convert("L")

output = pipe(
    prompt="cat wizard with a detailed red hat, Gandalf-inspired fantasy illustration",
    image=image,
    mask_image=mask_image,
    height=image.height,
    width=image.width,
    strength=0.9,
    num_inference_steps=8,
    generator=torch.Generator(device="cuda").manual_seed(42),
    output="images",
)[0]
output.save("zimage_modular_inpaint.png")

Modular ControlNet inpainting example

import torch

from diffusers import ModularPipeline, ZImageControlNetModel
from diffusers.utils import load_image
from huggingface_hub import hf_hub_download


controlnet_id = "alibaba-pai/Z-Image-Turbo-Fun-Controlnet-Union-2.0"
controlnet = ZImageControlNetModel.from_single_file(
    hf_hub_download(
        controlnet_id,
        filename="Z-Image-Turbo-Fun-Controlnet-Union-2.1.safetensors",
    ),
    torch_dtype=torch.bfloat16,
)

pipe = ModularPipeline.from_pretrained("Tongyi-MAI/Z-Image-Turbo")
pipe.load_components(dtype=torch.bfloat16)
pipe.update_components(controlnet=controlnet)
pipe.to("cuda")

image = load_image(
    f"https://huggingface.co/{controlnet_id}/resolve/main/asset/inpaint.jpg?download=true"
).convert("RGB")
mask_image = load_image(
    f"https://huggingface.co/{controlnet_id}/resolve/main/asset/mask.jpg?download=true"
).convert("L")
control_image = load_image(
    f"https://huggingface.co/{controlnet_id}/resolve/main/asset/pose.jpg?download=true"
).convert("RGB")

output = pipe(
    prompt="A woman standing on a sunny coast, full-body portrait, long purple hair, white dress",
    image=image,
    mask_image=mask_image,
    control_image=control_image,
    controlnet_conditioning_scale=0.75,
    control_guidance_start=0.0,
    control_guidance_end=1.0,
    height=1728,
    width=992,
    num_inference_steps=25,
    generator=torch.Generator(device="cuda").manual_seed(43),
    output="images",
)[0]
output.save("zimage_modular_controlnet_inpaint.png")

Native and modular comparison

Inpainting

Input image	Mask

Native ZImageInpaintPipeline	Modular ModularPipeline

ControlNet inpainting

Input image	Mask	Control image

Native ZImageControlNetInpaintPipeline	Modular ModularPipeline

Before submitting

• Did you use an AI agent (Claude Code, Codex, Cursor, etc.) to help with this PR? If so:
  • Did you read the Coding with AI agents guide?
  • Did you run the self-review skill on the diff?
  • Did you share the final self-review notes in the PR description or a comment?
• Did you read the contributor guideline?
• Did you read our philosophy doc? (important for complex PRs)
• Was this discussed/approved via a GitHub issue or the forum? Please add a link to it if that's the case.
• Did you make sure to update the documentation with your changes? Here are the
  documentation guidelines, and
  here are tips on formatting docstrings.
• Did you write any new necessary tests?
• Are you the author (or part of the team) of the model/pipeline (only applicable for model/pipeline related PRs)?

Who can review?

• Pipelines and models: @yiyixuxu and @asomoza