Diffusers documentation
JoyAI-Image-Edit
JoyAI-Image-Edit
JoyAI-Imageは、画像理解、テキストからの画像生成、および指示に基づく画像編集のための統合型マルチモーダル基盤モデルです。8Bのマルチモーダル大規模言語モデル（MLLM）と16Bのマルチモーダル拡散トランスフォーマー（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 の 3 つの空間編集プロンプトパターンをサポートしています。最適な結果を得るには、以下のプロンプトテンプレートをできるだけ忠実に従ってください。詳細については、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アーキテクチャを使用した画像編集のためのDiffusionパイプライン。
パイプラインは、Qwen3-VL テキストエンコーダーによってテキストと画像の条件をエンコードし、3-D トランスフォーマーで潜在変数をデノイズし、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、optional) —
条件付けに使用される参照画像。指定された場合、パイプラインは
num_items=2で画像編集モードとして動作します。 - num_inference_steps (int、optional、デフォルト値は 40)— デノイジングのステップ数です。ステップ数を増やすと、推論速度が遅くなる代わりに、一般的に品質が向上します。
- timesteps (List[int], 任意) —
デノイジングプロセス用のカスタムタイムステップ。指定された場合、
num_inference_stepsはリストの長さから推定されます。 - sigmas (List[float]、任意) —
デノイジングプロセス用のカスタムシグマ。
timestepsとは排他です。 - guidance_scale (float、任意、デフォルト値は 4.0) — Classifier-free guidance のスケール。
- negative_prompt (str または List[str]、optional) — 望ましくないコンテンツを抑制するために使用するネガティブプロンプト。
- num_images_per_prompt (int、任意、デフォルト値は 1)— プロンプトごとに生成されるサンプルの数。
- generator (torch.Generator または List[torch.Generator]、任意) — 決定論的なサンプリング用のRNGジェネレーターです。
- 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、optional、デフォルトは
"pil") — 出力形式。"latent"を渡すと、生の潜在変数を返します。 - return_dict (bool、任意、デフォルトは True) — JoyImageEditPipelineOutput を返すか、プレーンなテンソルを返すかを指定します。
- callback_on_step_end (Callable、PipelineCallback、MultiPipelineCallbacks、optional) —
各デノイジングステップの終了時に呼び出されるコールバックで、シグネチャは
(self, step: int, timestep: int, callback_kwargs: Dict)です。 - callback_on_step_end_tensor_inputs (List[str]、optional、デフォルトは
["latents"]) —callback_on_step_endのcallback_kwargsに含まれるテンソルキー。 - max_sequence_length (int、任意、デフォルトは 4096)— プロンプトエンコード用の最大シーケンス長。
- enable_denormalization (bool、任意、デフォルトは True) — VAEデコードの前に、潜在変数（latents）のデノーマライズを行います。
戻り値
[~pipelines.joyimage.JoyImageEditPipelineOutput] または torch.Tensor
return_dict が True の場合、生成された画像を含むパイプライン出力オブジェクトを返します。
それ以外の場合は、画像テンソルを直接返します。
参照画像とテキストプロンプトを条件として、編集された画像を生成します。
例:
>>> 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 )
パラメータ
- prompt — プロンプト文字列。必要に応じて、
<image>\nトークンを含むことができます。 - device — ターゲットデバイス。
- num_images_per_prompt — プロンプトごとに生成する出力の数。
- images — インライン画像トークンに対応するピクセルテンソル。
- prompt_embeds — 事前計算済みのプロンプト埋め込み。
- prompt_embeds_mask — 事前計算済み埋め込み用のアテンションマスク。
- template_type —
"multiple_images"である必要があります。 - max_sequence_length — 設定されている場合、出力をこの長さに切り詰めます（最後の
max_sequence_lengthトークンを保持します）。
インラインの画像トークンを含むプロンプトを、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 の設定から取得される Latent のチャネル次元数。
- height — ピクセル単位の空間的な高さ。
- width — ピクセル単位の空間的な幅。
- video_length — フレーム数（画像推論の場合は1）。
- dtype — 潜在テンソルに使用する浮動小数点型。
- device — ターゲットデバイス。
- generator — 再現可能なサンプリング用のRNGジェネレーター。
- latents — ターゲットスロット用の、ユーザーが指定する任意の初期ノイズ。
Noneの場合は、ランダムなノイズがサンプリングされます。 - image — VAEエンコードして条件スロットとして使用するPIL参照画像の任意のリスト。
- enable_denormalization — エンコードされた参照潜在変数を正規化するか否かを指定します。
例外
ValueError
ValueError—generatorがリストであり、その長さがbatch_sizeと異なる場合。
デノイジングループ用の初期ノイズ付き潜在テンソルを準備します。
JoyImageEditPipelineOutput
class diffusers.JoyImageEditPipelineOutput
< source >( images: typing.Union[typing.List[PIL.Image.Image], numpy.ndarray] )
JoyImageEdit 生成パイプライン用の出力クラスです。