Diffusers documentation

JoyAI-Image-Edit

Diffusers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).

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 es un modelo de base multimodal unificado para la comprensión de imágenes, la generación de imágenes a partir de texto y la edición de imágenes guiada por instrucciones. Combina un Modelo de Lenguaje Grande Multimodal (MLLM) de 8B con un Transformer de Difusión Multimodal (MMDiT) de 16B. Un principio central de JoyAI-Image es la colaboración en bucle cerrado entre la comprensión, la generación y la edición.

JoyAI-Image-Edit admite la edición general de imágenes, así como capacidades de edición espacial, que incluyen el movimiento de objetos, la rotación de objetos y el control de la cámara.

Modelo	Descripción	Descargar
JoyAI-Image-Edit	Edición de imágenes guiada por instrucciones con manipulación espacial precisa y controlable	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")

Edición espacial

JoyAI-Image admite tres patrones de edición espacial: Object Move, Object Rotation y Camera Control. Para obtener los mejores resultados, siga las plantillas de indicaciones a continuación con la mayor fidelidad posible. Para obtener más información, consulte SpatialEdit.

Mover objeto

Mover un objeto de destino a una región especificada marcada con un recuadro rojo en la imagen de entrada.

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

Rotación de objetos

Gire un objeto a una vista canónica específica. Valores de <view> admitidos: front, right, left, rear, front right, front left, rear right, rear left.

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

Control de cámara

Cambia el punto de vista de la cámara manteniendo la escena 3D sin cambios.

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

clase diffusers.JoyImageEditPipeline

< source >

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

Pipeline de difusión para la edición de imágenes que utiliza la arquitectura JoyImage.

El pipeline codifica el condicionamiento de texto e imagen mediante un codificador de texto Qwen3-VL, elimina el ruido de los latentes con un transformador 3-D y decodifica el resultado con un VAE de WAN.

Orden de descarga de modelos: 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 o List[str]) — El prompt o los prompts para guiar la generación.
height (int) — Altura de la salida generada en píxeles.
width (int) — Ancho de la salida generada en píxeles.
image (PipelineImageInput, opcional) — Imagen de referencia utilizada para el condicionamiento. Cuando se proporciona, la pipeline opera en modo de edición de imagen con num_items=2.
num_inference_steps (int, opcional, valor predeterminado 40) — Número de pasos de desruido. Más pasos generalmente mejoran la calidad a costa de una inferencia más lenta.
timesteps (List[int], opcional) — Pasos de tiempo personalizados para el proceso de desruido. Cuando se proporciona, num_inference_steps se infiere a partir de la longitud de la lista.
sigmas (List[float], opcional) — Sigmas personalizados para el proceso de desruido. Mutuamente excluyente con timesteps.
guidance_scale (float, opcional, valor predeterminado 4.0) — Escala de guía libre de clasificador.
negative_prompt (str o List[str], opcional) — Prompt(s) negativo(s) utilizado(s) para suprimir contenido no deseado.
num_images_per_prompt (int, opcional, valor predeterminado 1) — Número de muestras generadas por indicación.
generator (torch.Generator o List[torch.Generator], opcional) — Generador(es) de RNG para muestreo determinista.
latents (torch.Tensor, opcional) — Latentes ruidosos pregenerados para el slot objetivo. Se muestrean de una distribución gaussiana cuando no se proporcionan. Se pueden usar para iniciar la generación desde un tensor de ruido inicial específico.
prompt_embeds (torch.Tensor, opcional) — Incrustaciones de prompt precalculadas. Si se proporciona, se puede omitir prompt.
prompt_embeds_mask (torch.Tensor, opcional) — Máscara de atención para prompt_embeds.
negative_prompt_embeds (torch.Tensor, opcional) — Incrustaciones de prompt negativo precalculadas.
negative_prompt_embeds_mask (torch.Tensor, opcional) — Máscara de atención para negative_prompt_embeds.
output_type (str, opcional, por defecto "pil") — Formato de salida. Pasa "latent" para devolver latentes crudos.
return_dict (bool, opcional, valor predeterminado True) — Si se devuelve un JoyImageEditPipelineOutput o un tensor simple.
callback_on_step_end (Callable, PipelineCallback, MultiPipelineCallbacks, opcional) — Callback que se invoca al final de cada paso de desruido con la firma (self, step: int, timestep: int, callback_kwargs: Dict).
callback_on_step_end_tensor_inputs (List[str], opcional, valor predeterminado ["latents"]) — Claves de tensor incluidas en callback_kwargs para callback_on_step_end.
max_sequence_length (int, opcional, valor predeterminado 4096) — Longitud máxima de la secuencia para la codificación del prompt.
enable_denormalization (bool, opcional, valor predeterminado True) — Denormaliza los latentes antes de la decodificación con VAE.

Devuelve

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

Si return_dict es True, devuelve un objeto de salida de pipeline que contiene la(s) imagen(es) generada(s). En caso contrario, devuelve el tensor de la imagen directamente.

Genere una imagen editada condicionada a una imagen de referencia y un prompt de texto.

Ejemplos:

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

Lanza

ValueError

ValueError — En cualquier combinación inválida de argumentos.

Validar las entradas de la pipeline antes de la pasada hacia adelante.

denormalize_latents

< source >

( latent: Tensor )

Parámetros

latent — Tensor latente normalizado.

Invierte normalize_latents para recuperar la 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 — Cadena o lista de cadenas de prompt.
device — Dispositivo de destino.
num_images_per_prompt — Número de salidas a generar por indicación.
prompt_embeds — Incrustaciones de prompt precalculadas.
prompt_embeds_mask — Máscara de atención para las incrustaciones precalculadas.
max_sequence_length — Longitud máxima de la secuencia de salida.
template_type — Clave de la plantilla de prompt ("image" o "multiple_images").

Codifica un prompt de texto en embeddings (ruta solo de texto).

Los prompt_embeds precalculados omiten por completo la codificación.

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 — Cadena(s) de texto de entrada, que opcionalmente contienen tokens <image>\n.
device — Dispositivo de destino.
num_images_per_prompt — Número de salidas a generar por indicación.
images — Tensores de píxeles correspondientes a los tokens de imagen en línea.
prompt_embeds — Incrustaciones de prompt precalculadas.
prompt_embeds_mask — Máscara de atención para las incrustaciones precalculadas.
template_type — Debe ser "multiple_images".
max_sequence_length — Si se establece, se trunca la salida a esta longitud (conservando los últimos max_sequence_length tokens).

Codifica los prompts que contienen tokens de imagen en línea mediante el procesador de Qwen.

Los marcadores de posición <image>\n en cada cadena de indicación se reemplazan por los tokens especiales de visión de Qwen antes de ser enviados al codificador multimodal.

normalize_latents

< source >

( latent: Tensor )

Parámetros

latent — Tensor latente sin procesar de vae.encode.

Normaliza los latentes usando estadísticas por canal de la configuración del VAE.

Usa (latente - media) / std cuando el VAE expone latents_mean y latents_std; de lo contrario, recurre a la escalado 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 muestras en el lote.
num_channels_latents — Dimensión de los canales latentes de la configuración del transformer.
height — Altura espacial en píxeles.
width — Ancho espacial en píxeles.
video_length — Número de fotogramas (1 para inferencia de imagen).
dtype — dtype de punto flotante para el tensor latente.
device — Dispositivo de destino.
generator — generador(es) de RNG para muestreo reproducible.
latents — Ruido inicial opcional proporcionado por el usuario para el slot objetivo. Cuando es None, se muestrea ruido aleatorio.
image — Lista opcional de imágenes de referencia en PIL para codificar con VAE como ranuras de condicionamiento.
enable_denormalization — Si se debe normalizar los latentes de referencia codificados.

Lanza

ValueError

ValueError — Si generator es una lista cuya longitud difiere de batch_size.

Prepara el tensor latente inicial con ruido para el bucle de desruido.

JoyImageEditPipelineOutput

clase diffusers.JoyImageEditPipelineOutput

< source >

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

Clase de salida para las tuberías de generación de JoyImageEdit.

Update on GitHub

←InstructPix2Pix JoyImage Edit Plus→

Diffusers

JoyAI-Image-Edit

Edición espacial

Mover objeto

Rotación de objetos

Control de cámara

JoyImageEditPipeline

clase diffusers.JoyImageEditPipeline

__call__

check_inputs

denormalize_latents

encode_prompt

encode_prompt_multiple_images

normalize_latents

prepare_latents

JoyImageEditPipelineOutput

clase diffusers.JoyImageEditPipelineOutput

call