Diffusers documentation

JoyAI-Image-Edit

Diffusers

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

JoyAI-Image-Edit

JoyAI-Image é um modelo de fundação multimodal unificado para compreensão de imagens, geração de imagens a partir de texto e edição de imagens guiada por instruções. Ele combina um Modelo de Linguagem Multimodal (MLLM) de 8B com um Transformer de Difusão Multimodal (MMDiT) de 16B. Um princípio central do JoyAI-Image é a colaboração em ciclo fechado entre compreensão, geração e edição.

O JoyAI-Image-Edit suporta edição geral de imagens, bem como capacidades de edição espacial, incluindo mover objetos, rotacionar objetos e controle de câmera.

Model	Descrição	Download
JoyAI-Image-Edit	Edição de imagens guiada por instruções com manipulação espacial precisa e controlável	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")

Edição espacial

O JoyAI-Image suporta três padrões de prompt de edição espacial: Object Move, Object Rotation e Camera Control. Para obter os melhores resultados, siga os modelos de prompt abaixo o mais fielmente possível. Para mais informações, consulte SpatialEdit.

Mover Objeto

Mova um objeto de destino para uma região especificada, marcada por uma caixa vermelha, na imagem de entrada.

Move the <object> into the red box and finally remove the red box.

Rotação de Objeto

Gire um objeto para uma vista canônica específica. Valores de <view> suportados: front, right, left, rear, front right, front left, rear right, rear left.

Rotate the <object> to show the <view> side view.

Controle da Câmera

Alterne o ponto de vista da câmera mantendo a cena 3D inalterada.

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

classe diffusers.JoyImageEditPipeline

< source >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLWantext_encoder: Qwen3VLForConditionalGenerationtokenizer: Qwen2Tokenizertransformer: JoyImageEditTransformer3DModelprocessor: Qwen3VLProcessortext_token_max_length: int = 2048 )

Pipeline de difusão para edição de imagens usando a arquitetura JoyImage.

O pipeline codifica o condicionamento de texto e imagem por meio de um codificador de texto Qwen3-VL, remove o ruído dos latentes com um transformador 3-D e decodifica o resultado com um WAN VAE.

Ordem de offloading do modelo: 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

Parâmetros

prompt (str ou List[str]) — O prompt ou os prompts para orientar a geração.
height (int) — Altura da saída gerada em pixels.
width (int) — Largura da saída gerada em pixels.
image (PipelineImageInput, opcional) — Imagem de referência usada para condicionamento. Quando fornecida, o pipeline opera no modo de edição de imagem com num_items=2.
num_inference_steps (int, opcional, padrão 40) — Número de etapas de desruido. Mais etapas geralmente melhoram a qualidade, mas aumentam o tempo de inferência.
timesteps (List[int], opcional) — Timesteps personalizados para o processo de remoção de ruído. Quando fornecidos, num_inference_steps é inferido a partir do tamanho da lista.
sigmas (List[float], opcional) — Sigmas personalizados para o processo de desruidamento. Mutuamente exclusivo com timesteps.
guidance_scale (float, opcional, padrão 4.0) — Escala de orientação sem classificador.
negative_prompt (str ou List[str], opcional) — Prompt(s) negativo(s) usado(s) para suprimir conteúdo indesejado.
num_images_per_prompt (int, opcional, padrão 1) — Número de amostras geradas por prompt.
generator (torch.Generator ou List[torch.Generator], opcional) — Gerador(es) de RNG para amostragem determinística.
latents (torch.Tensor, opcional) — Latentes ruidosos pré-gerados para o slot de destino. Amostras de uma distribuição gaussiana quando não fornecidos. Pode ser usado para iniciar a geração a partir de um tensor de ruído inicial específico.
prompt_embeds (torch.Tensor, opcional) — Incorporações de prompt pré-computadas. Quando fornecidas, prompt pode ser omitido.
prompt_embeds_mask (torch.Tensor, opcional) — Máscara de atenção para prompt_embeds.
negative_prompt_embeds (torch.Tensor, opcional) — Embeddings de prompt negativo pré-computados.
negative_prompt_embeds_mask (torch.Tensor, opcional) — Máscara de atenção para negative_prompt_embeds.
output_type (str, opcional, padrão "pil") — Formato de saída. Passe "latent" para retornar os latentes brutos.
return_dict (bool, opcional, padrão True) — Se deve retornar um JoyImageEditPipelineOutput ou um tensor simples.
callback_on_step_end (Callable, PipelineCallback, MultiPipelineCallbacks, opcional) — Callback chamado no final de cada etapa de desruidamento com a assinatura (self, step: int, timestep: int, callback_kwargs: Dict).
callback_on_step_end_tensor_inputs (List[str], opcional, padrão ["latents"]) — Chaves de tensor incluídas em callback_kwargs para callback_on_step_end.
max_sequence_length (int, opcional, padrão 4096) — Comprimento máximo da sequência para a codificação do prompt.
enable_denormalization (bool, opcional, padrão True) — Denormaliza os latentes antes da decodificação pelo VAE.

Retorna

[~pipelines.joyimage.JoyImageEditPipelineOutput] ou torch.Tensor

Se return_dict for True, retorna um objeto de saída de pipeline contendo a(s) imagem(ns) gerada(s). Caso contrário, retorna o tensor da imagem diretamente.

Gere uma imagem editada condicionada a uma imagem de referência e a um prompt de texto.

Exemplos:

>>> 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 )

Exceções

ValueError

ValueError — Em qualquer combinação inválida de argumentos.

Valide as entradas do pipeline antes da passagem direta.

denormalize_latents

< source >

( latent: Tensor )

Parâmetros

latent — Tensor latente normalizado.

Inverta normalize_latents para recuperar a escala latente original.

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' )

Parâmetros

prompt — String ou lista de strings de prompt.
device — Dispositivo de destino.
num_images_per_prompt — Número de saídas a gerar por prompt.
prompt_embeds — Embeddings de prompt pré-computados.
prompt_embeds_mask — Máscara de atenção para incorporações pré-calculadas.
max_sequence_length — Comprimento máximo da sequência de saída.
template_type — Chave do modelo de prompt ("image" ou "multiple_images").

Codifique um prompt de texto em embeddings (caminho apenas de texto).

prompt_embeds pré-computados contornam completamente a codificação.

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 )

Parâmetros

prompt — Prompt string(s), optionally containing <image>\n tokens.
device — Dispositivo de destino.
num_images_per_prompt — Número de saídas a gerar por prompt.
images — Tensores de pixels correspondentes aos tokens de imagem embutidos.
prompt_embeds — Embeddings de prompt pré-computados.
prompt_embeds_mask — Máscara de atenção para incorporações pré-calculadas.
template_type — Deve ser "multiple_images".
max_sequence_length — Se definido, trunca a saída para esse comprimento (mantendo os últimos max_sequence_length tokens).

Codifique prompts que contêm tokens de imagem inline por meio do processador Qwen.

Os placeholders <image>\n em cada string de prompt são substituídos pelos tokens especiais de visão do Qwen antes de serem enviados ao codificador multimodal.

normalize_latents

< source >

( latent: Tensor )

Parâmetros

latent — Tensor latente bruto de vae.encode.

Normalize os latentes usando estatísticas por canal da configuração do VAE.

Usa (latente - média) / desvio padrão quando o VAE expõe latents_mean e latents_std; caso contrário, recorre à escala por 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 )

Parâmetros

batch_size — Número de amostras no lote.
num_channels_latents — Dimensão do canal latente da configuração do transformer.
height — Altura espacial em pixels.
width — Largura espacial em pixels.
video_length — Número de quadros (1 para inferência de imagem).
dtype — dtype de ponto flutuante para o tensor latente.
device — Dispositivo de destino.
generator — gerador(es) de RNG para amostragem reprodutível.
latents — Ruído inicial opcional fornecido pelo usuário para o slot de destino. Quando None, um ruído aleatório é amostrado.
image — Lista opcional de imagens de referência em PIL para codificar com VAE como slots de condicionamento.
enable_denormalization — Se normalizar os latentes de referência codificados.

Exceções

ValueError

ValueError — Se generator for uma lista cujo comprimento difere de batch_size.

Prepare o tensor latente inicial com ruído para o loop de desruidamento.

JoyImageEditPipelineOutput

classe diffusers.JoyImageEditPipelineOutput

< source >

( images: typing.Union[typing.List[PIL.Image.Image], numpy.ndarray] )

Classe de saída para pipelines de geração do JoyImageEdit.

Update on GitHub

←InstructPix2Pix JoyImage Edit Plus→

Diffusers

JoyAI-Image-Edit

Edição espacial

Mover Objeto

Rotação de Objeto

Controle da Câmera

JoyImageEditPipeline

classe diffusers.JoyImageEditPipeline

__call__

check_inputs

denormalize_latents

encode_prompt

encode_prompt_multiple_images

normalize_latents

prepare_latents

JoyImageEditPipelineOutput

classe diffusers.JoyImageEditPipelineOutput

call