Diffusers documentation
JoyAI-Image-Edit
JoyAI-Image-Edit
JoyAI-Image 是一个用于图像理解、文生图以及指令引导图像编辑的统一多模态基础模型。它将一个 8B 多模态大语言模型（MLLM）与一个 16B 多模态扩散 Transformer（MMDiT）相结合。JoyAI-Image 的核心原则是实现理解、生成与编辑之间的闭环协作。
JoyAI-Image-Edit 支持通用图像编辑，以及包括对象移动、对象旋转和相机控制在内的空间编辑功能。
| 模型 | 描述 | 下载 |
|---|---|---|
| JoyAI-Image-Edit | 通过精确且可控的空间操作实现指令引导的图像编辑 | Hugging Face |
import torch
from diffusers import JoyImageEditPipeline
from diffusers.utils import load_image
pipeline = JoyImageEditPipeline.from_pretrained(
"jdopensource/JoyAI-Image-Edit-Diffusers", dtype=torch.bfloat16
)
pipeline.to("cuda") # or "mps", "xpu", "cpu"
image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg")
prompt = "Add wings to the astronaut."
output = pipeline(
image=image,
prompt=prompt,
num_inference_steps=40,
guidance_scale=4.0,
generator=torch.Generator("cuda").manual_seed(0),
).images[0]
output.save("joyimage_edit_output.png")空间编辑
JoyAI-Image 支持三种空间编辑提示词模式：Object Move、Object Rotation 和 Camera Control。为了获得最佳效果，请尽可能严格遵循下方的提示词模板。有关更多信息，请参阅 SpatialEdit。
对象移动
将目标对象移动到输入图像中由红框标记的指定区域。
Move the <object> into the red box and finally remove the red box.
物体旋转
将对象旋转到特定的标准视图。支持的 <view> 值：front、right、left、rear、front right、front left、rear right、rear left。
Rotate the <object> to show the <view> side view.
相机控制
在保持 3D 场景不变的情况下，更改相机视角。
Move the camera.
- Camera rotation: Yaw {y_rotation}°, Pitch {p_rotation}°.
- Camera zoom: in/out/unchanged.
- Keep the 3D scene static; only change the viewpoint.JoyImageEditPipeline
class diffusers.JoyImageEditPipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLWantext_encoder: Qwen3VLForConditionalGenerationtokenizer: Qwen2Tokenizertransformer: JoyImageEditTransformer3DModelprocessor: Qwen3VLProcessortext_token_max_length: int = 2048 )
使用 JoyImage 架构进行图像编辑的扩散流水线。
该流水线通过 Qwen3-VL 文本编码器对文本和图像条件进行编码，使用 3-D transformer 对潜变量进行去噪，并使用 WAN VAE 解码结果。
模型卸载顺序：text_encoder -> transformer -> vae。
__call__
< source >( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Noneprompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 40timesteps: typing.List[int] = Nonesigmas: typing.List[float] = Noneguidance_scale: float = 4.0negative_prompt: typing.Union[str, typing.List[str], NoneType] = Nonenum_images_per_prompt: typing.Optional[int] = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask: typing.Optional[torch.Tensor] = Noneoutput_type: typing.Optional[str] = 'pil'return_dict: bool = Truecallback_on_step_end: typing.Union[typing.Callable[[int, int, typing.Dict], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']max_sequence_length: int = 4096enable_denormalization: bool = True ) → [~pipelines.joyimage.JoyImageEditPipelineOutput] or torch.Tensor
参数
- prompt (str 或 List[str]) — 用于引导生成的提示词或提示词列表。
- height (int) — 生成输出的高度（以像素为单位）。
- width (int) — 生成输出的宽度（以像素为单位）。
- image (PipelineImageInput，可选) —
用于条件控制的参考图像。提供该参数时，流水线将以图像编辑模式运行，且
num_items=2。 - num_inference_steps (int，可选，默认为 40) — 去噪步数。步数越多，通常质量越高，但推理速度会变慢。
- timesteps (List[int], 可选) —
去噪过程的自定义时间步。提供时，
num_inference_steps将根据列表长度推断得出。 - sigmas (List[float], 可选) —
用于去噪过程的自定义 sigmas。与
timesteps互斥。 - guidance_scale (float，可选，默认值为 4.0) — 无分类器引导的尺度。
- negative_prompt (str 或 List[str]，可选) — 用于抑制不期望内容的负面提示词。
- num_images_per_prompt (int，可选，默认为 1) — 每个提示词生成的样本数量。
- generator (torch.Generator 或 List[torch.Generator]，可选) — 用于确定性采样的随机数生成器。
- latents (torch.Tensor, optional) — 目标槽位的预生成噪声潜变量。若未提供，则从高斯分布中采样。可用于从特定的起始噪声张量开始生成。
- prompt_embeds (torch.Tensor, 可选) —
预计算的提示嵌入。提供该参数时，可以省略
prompt。 - prompt_embeds_mask (torch.Tensor, optional) —
prompt_embeds的注意力掩码。 - negative_prompt_embeds (torch.Tensor，可选) — 预计算的负提示嵌入。
- negative_prompt_embeds_mask (torch.Tensor, 可选) —
negative_prompt_embeds的注意力掩码。 - output_type (str，可选，默认为
"pil") — 输出格式。传入"latent"以返回原始潜在表示。 - return_dict (bool，可选，默认为 True) — 是否返回 JoyImageEditPipelineOutput 或普通张量。
- callback_on_step_end (Callable、PipelineCallback、MultiPipelineCallbacks、可选) —
在每个去噪步骤结束时调用的回调，其签名为
(self, step: int, timestep: int, callback_kwargs: Dict)。 - callback_on_step_end_tensor_inputs（List[str]，可选，默认为
["latents"]）—callback_on_step_end中callback_kwargs包含的张量键。 - max_sequence_length (int，可选，默认为 4096) — 用于提示编码的最大序列长度。
- enable_denormalization (bool，可选，默认为 True) — 在 VAE 解码之前对潜变量进行反归一化。
返回值
[~pipelines.joyimage.JoyImageEditPipelineOutput] 或 torch.Tensor
如果 return_dict 为 True，则返回一个包含生成图像的 pipeline 输出对象。
否则，直接返回图像张量。
根据参考图像和文本提示生成编辑后的图像。
示例：
>>> import torch
>>> from diffusers import JoyImageEditPipeline
>>> from diffusers.utils import load_image
>>> model_id = "jdopensource/JoyAI-Image-Edit-Diffusers"
>>> pipe = JoyImageEditPipeline.from_pretrained(model_id, torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> image = load_image("https://huggingface.co/datasets/diffusers/docs-images/resolve/main/astronaut.jpg")
>>> output = pipe(
... image=image, # pass an image for editing; omit for text-to-image generation
... prompt="Add wings to the astronaut.",
... num_inference_steps=40,
... guidance_scale=4.0,
... generator=torch.manual_seed(0),
... )
>>> output.images[0].save("joyimage_edit.png")check_inputs
< source >( promptheightwidthnegative_prompt = Noneprompt_embeds = Nonenegative_prompt_embeds = Noneprompt_embeds_mask = Nonenegative_prompt_embeds_mask = Nonecallback_on_step_end_tensor_inputs = None )
引发
ValueError
ValueError— 当参数组合无效时抛出。
在前向传播之前验证流水线输入。
反转 normalize_latents 以恢复原始的潜在变量尺度。
encode_prompt
< source >( prompt: typing.Union[str, typing.List[str]]device: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024template_type: str = 'image' )
将文本提示编码为嵌入（仅文本路径）。
预计算的 prompt_embeds 会完全绕过编码过程。
encode_prompt_multiple_images
< source >( prompt: typing.Union[str, typing.List[str]]device: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1images: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonetemplate_type: typing.Optional[str] = 'multiple_images'max_sequence_length: typing.Optional[int] = None )
通过 Qwen 处理器对包含内联图像标记的提示进行编码。
每个提示字符串中的 <image>\n 占位符在输入多模态编码器之前，会被替换为 Qwen 视觉特殊标记。
使用 VAE 配置中的逐通道统计量对潜变量进行归一化。
当 VAE 暴露 latents_mean 和 latents_std 时，使用 (latent - mean) / std；否则回退到使用 scaling_factor 进行缩放。
prepare_latents
< source >( batch_size: intnum_channels_latents: intheight: intwidth: intvideo_length: intdtype: dtypedevice: devicegenerator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType]latents: typing.Optional[torch.Tensor] = Noneimage: typing.Optional[typing.List[PIL.Image.Image]] = Noneenable_denormalization: bool = True )
参数
- batch_size — 批次中的样本数量。
- num_channels_latents — 来自 transformer 配置的潜在通道维度。
- height — 以像素为单位的空间高度。
- width — 以像素为单位的空间宽度。
- video_length — 帧数（图像推理时为 1）。
- dtype — 潜在张量的浮点数据类型。
- device — 目标设备。
- generator — 用于可复现采样的随机数生成器。
- latents — 可选，用户提供的目标槽位的初始噪声。当
None时，将采样随机噪声。 - image — 可选的 PIL 参考图像列表，用于 VAE 编码作为条件槽位。
- enable_denormalization — 是否对编码后的参考潜变量进行归一化。
引发
ValueError
ValueError— 如果generator是一个列表，且其长度与batch_size不同。
为去噪循环准备初始含噪潜在张量。
JoyImageEditPipelineOutput
class diffusers.JoyImageEditPipelineOutput
< source >( images: typing.Union[typing.List[PIL.Image.Image], numpy.ndarray] )
JoyImageEdit 生成管线的输出类。