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 adalah model dasar multimodal terpadu untuk pemahaman gambar, pembuatan gambar dari teks, dan pengeditan gambar yang dipandu instruksi. Model ini menggabungkan Multimodal Large Language Model (MLLM) 8B dengan Multimodal Diffusion Transformer (MMDiT) 16B. Prinsip utama JoyAI-Image adalah kolaborasi loop tertutup antara pemahaman, pembuatan, dan pengeditan.

JoyAI-Image-Edit mendukung pengeditan gambar umum serta kemampuan pengeditan spasial, termasuk perpindahan objek, rotasi objek, dan kontrol kamera.

Model	Deskripsi	Unduh
JoyAI-Image-Edit	Pengeditan gambar yang dipandu instruksi dengan manipulasi spasial yang presisi dan dapat dikendalikan	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")

Penyuntingan spasial

JoyAI-Image mendukung tiga pola prompt pengeditan spasial: Object Move, Object Rotation, dan Camera Control. Untuk hasil terbaik, ikuti template prompt di bawah ini sedekat mungkin. Untuk informasi lebih lanjut, lihat SpatialEdit.

Gerak Objek

Pindahkan objek target ke area tertentu yang ditandai dengan kotak merah pada gambar input.

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

Rotasi Objek

Putar objek ke tampilan kanonik tertentu. Nilai <view> yang didukung: front, right, left, rear, front right, front left, rear right, rear left.

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

Kontrol Kamera

Ubah sudut pandang kamera sambil mempertahankan adegan 3D tetap tidak berubah.

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

kelas diffusers.JoyImageEditPipeline

< source >

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

Pipeline difusi untuk pengeditan gambar menggunakan arsitektur JoyImage.

Pipeline ini mengkodekan kondisi teks dan gambar melalui pengkode teks Qwen3-VL, melakukan denoising pada latens dengan transformer 3-D, dan mendekode hasilnya dengan WAN VAE.

Urutan offloading model: 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

Parameter

prompt (str atau List[str]) — Prompt atau prompt-prompt untuk memandu generasi.
height (int) — Tinggi output yang dihasilkan dalam piksel.
width (int) — Lebar output yang dihasilkan dalam piksel.
image (PipelineImageInput, opsional) — Gambar referensi yang digunakan untuk kondisioning. Jika disediakan, pipeline beroperasi dalam mode pengeditan gambar dengan num_items=2.
num_inference_steps (int, opsional, default 40) — Jumlah langkah denoising. Semakin banyak langkah umumnya meningkatkan kualitas dengan biaya inferensi yang lebih lambat.
timesteps (List[int], opsional) — Timesteps kustom untuk proses denoising. Ketika diberikan, num_inference_steps disimpulkan dari panjang list.
sigmas (List[float], opsional) — Sigmas kustom untuk proses denoising. Saling eksklusif dengan timesteps.
guidance_scale (float, opsional, default 4.0) — Skala panduan bebas klasifikator.
negative_prompt (str atau List[str], opsional) — Prompt negatif yang digunakan untuk menekan konten yang tidak diinginkan.
num_images_per_prompt (int, opsional, default 1) — Jumlah sampel yang dihasilkan per prompt.
generator (torch.Generator atau List[torch.Generator], opsional) — Generator RNG untuk pengambilan sampel deterministik.
latents (torch.Tensor, opsional) — Latents berisik yang telah dibuat sebelumnya untuk slot target. Disampelkan dari distribusi Gaussian jika tidak disediakan. Dapat digunakan untuk memulai generasi dari tensor noise awal tertentu.
prompt_embeds (torch.Tensor, opsional) — Embedding prompt yang sudah dihitung sebelumnya. Jika disediakan, prompt dapat diabaikan.
prompt_embeds_mask (torch.Tensor, opsional) — Attention mask untuk prompt_embeds.
negative_prompt_embeds (torch.Tensor, opsional) — Embedding prompt negatif yang sudah dihitung sebelumnya.
negative_prompt_embeds_mask (torch.Tensor, opsional) — Attention mask untuk negative_prompt_embeds.
output_type (str, opsional, default "pil") — Format output. Berikan "latent" untuk mengembalikan latents mentah.
return_dict (bool, opsional, default True) — Apakah akan mengembalikan JoyImageEditPipelineOutput atau tensor biasa.
callback_on_step_end (Callable, PipelineCallback, MultiPipelineCallbacks, opsional) — Callback yang dipanggil di akhir setiap langkah denoising dengan tanda tangan (self, step: int, timestep: int, callback_kwargs: Dict).
callback_on_step_end_tensor_inputs (List[str], opsional, default ["latents"]) — Kunci tensor yang disertakan dalam callback_kwargs untuk callback_on_step_end.
max_sequence_length (int, opsional, default 4096) — Panjang maksimum urutan untuk enkoding prompt.
enable_denormalization (bool, opsional, default True) — Denormalisasi latents sebelum decoding VAE.

Mengembalikan

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

Jika return_dict adalah True, mengembalikan objek output pipeline yang berisi gambar yang dihasilkan. Jika tidak, mengembalikan tensor gambar secara langsung.

Buat gambar yang telah diedit berdasarkan gambar referensi dan prompt teks.

Contoh:

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

Membuang

ValueError

ValueError — Pada kombinasi argumen yang tidak valid.

Validasi input pipeline sebelum forward pass.

denormalize_latents

< source >

( latent: Tensor )

Parameter

latent — Tensor laten ternormalisasi.

Invert normalize_latents untuk memulihkan skala laten asli.

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

Parameter

prompt — Prompt string or list of prompt strings.
device — Perangkat target.
num_images_per_prompt — Jumlah output yang akan dihasilkan per prompt.
prompt_embeds — Embedding prompt yang sudah dihitung sebelumnya.
prompt_embeds_mask — Mask perhatian untuk embedding yang sudah dihitung sebelumnya.
max_sequence_length — Panjang maksimum urutan output.
template_type — Kunci template prompt ("image" atau "multiple_images").

Enkode prompt teks menjadi embeddings (jalur teks saja).

Pre-computed prompt_embeds melewati proses encoding sepenuhnya.

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 )

Parameter

prompt — Prompt string(s), optionally containing <image>\n tokens.
device — Perangkat target.
num_images_per_prompt — Jumlah output yang akan dihasilkan per prompt.
images — Tensor piksel yang sesuai dengan token gambar inline.
prompt_embeds — Embedding prompt yang sudah dihitung sebelumnya.
prompt_embeds_mask — Mask perhatian untuk embedding yang sudah dihitung sebelumnya.
template_type — Harus berupa "multiple_images".
max_sequence_length — Jika diatur, pangkas output menjadi panjang ini (menempatkan max_sequence_length token terakhir).

Encode prompt yang berisi token gambar inline melalui prosesor Qwen.

<image>\n placeholder dalam setiap string prompt diganti oleh token khusus visi Qwen sebelum diberikan ke encoder multimodal.

normalize_latents

< source >

( latent: Tensor )

Parameter

latent — Tensor laten mentah dari vae.encode.

Normalisasi latents menggunakan statistik per-channel dari konfigurasi VAE.

Menggunakan (latent - mean) / std ketika VAE mengekspos latents_mean dan latents_std; jika tidak, kembali ke penyesuaian skala dengan 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 )

Parameter

batch_size — Jumlah sampel dalam batch.
num_channels_latents — Dimensi kanal laten dari konfigurasi transformer.
height — Tinggi spasial dalam piksel.
width — Lebar spasial dalam piksel.
video_length — Jumlah frame (1 untuk inferensi gambar).
dtype — dtype bilangan pecahan untuk tensor laten.
device — Perangkat target.
generator — generator RNG untuk pengambilan sampel yang dapat direproduksi.
latents — Noise awal opsional yang disediakan pengguna untuk slot target. Jika None, noise acak akan diambil.
image — Daftar opsional gambar referensi PIL untuk di-VAE-encode sebagai slot kondisioning.
enable_denormalization — Apakah akan menormalisasi latens referensi yang telah dikodekan.

Membuang

ValueError

ValueError — Jika generator adalah daftar yang panjangnya berbeda dari batch_size.

Siapkan tensor laten berisik awal untuk loop denoising.

JoyImageEditPipelineOutput

kelas diffusers.JoyImageEditPipelineOutput

< source >

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

Kelas output untuk pipeline generasi JoyImageEdit.

Update on GitHub

←InstructPix2Pix JoyImage Edit Plus→

Diffusers

JoyAI-Image-Edit

Penyuntingan spasial

Gerak Objek

Rotasi Objek

Kontrol Kamera

JoyImageEditPipeline

kelas diffusers.JoyImageEditPipeline

__call__

check_inputs

denormalize_latents

encode_prompt

encode_prompt_multiple_images

normalize_latents

prepare_latents

JoyImageEditPipelineOutput

kelas diffusers.JoyImageEditPipelineOutput

call