Hugging Face's logo

Diffusers documentation

HunyuanVideo-1.5

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

HunyuanVideo-1.5

HunyuanVideo-1.5 は、わずか 83 億パラメータで最先端の視覚品質とモーションの一貫性を達成する、軽量かつ高性能な動画生成モデルです。これにより、コンシューマー向け GPU での効率的な推論を可能にしています。この成果は、慎重なデータキュレーション、選択的およびスライディングタイルアテンション (SSTA) を備えた高度な DiT アーキテクチャ、グリフ認識型テキストエンコーディングによるバイリンガル理解の強化、段階的な事前学習と事後学習、そして効率的な動画スーパーリゾリューションネットワークなど、いくつかの重要なコンポーネントに基づいています。これらの設計を活用し、複数の長さや解像度に対応した、高品質なテキストから動画への生成および画像から動画への生成を実現する統合フレームワークを開発しました。広範な実験により、このコンパクトで高機能なモデルが、オープンソースモデルの中で新たな最先端の水準を確立していることが示されています。

すべてのオリジナルのHunyuanVideoチェックポイントは、Tencent組織の下で見つけることができます。

HunyuanVideo モデルのより多くの動画生成タスクの例については、右側のサイドバーをクリックしてください。

以下の例では、hunyuanvideo-community のチェックポイントを使用しています。これは、重みが Diffusers と互換性のあるレイアウトで保存されているためです。

以下の例では、メモリまたは推論速度に最適化されたビデオを生成する方法を示しています。

<hfoptions id="usage"> <hfoption id="memory">

メモリ使用量の削減に関する詳細については、メモリ使用量の削減ガイドを参照してください。

import torch
from diffusers import AutoModel, HunyuanVideo15Pipeline
from diffusers.utils import export_to_video


pipeline = HunyuanVideo15Pipeline.from_pretrained(
    "HunyuanVideo-1.5-Diffusers-480p_t2v",
    dtype=torch.bfloat16,
)

# model-offloading and tiling
pipeline.enable_model_cpu_offload()
pipeline.vae.enable_tiling()

prompt = "A fluffy teddy bear sits on a bed of soft pillows surrounded by children's toys."
video = pipeline(prompt=prompt, num_frames=61, num_inference_steps=30).frames[0]
export_to_video(video, "output.mp4", fps=15)

注記

  • HunyuanVideo1.5 は、可変長のシーケンスに対してアテンションマスクを使用します。最適なパフォーマンスを得るには、パディングを効率的に処理できるアテンションバックエンドの使用を推奨します。

    • H100/H800: _flash_3_hub または _flash_3_varlen_hub
    • A100/A800/RTX 4090: flash_hub または flash_varlen_hub
    • その他の GPU: sage_hub

異なるバックエンドの使用に関する詳細については、Attention backendsガイドを参照してください。

pipe.transformer.set_attention_backend("flash_hub")  # or your preferred backend
  • HunyuanVideo15Pipeline は guider を使用し、実行時に guidance_scale パラメータを受け取りません。

pipe.guider を使用して、デフォルトの guider 設定を確認できます。

>>> pipe.guider 
ClassifierFreeGuidance {
  "_class_name": "ClassifierFreeGuidance",
  "_diffusers_version": "0.36.0.dev0",
  "enabled": true,
  "guidance_rescale": 0.0,
  "guidance_scale": 6.0,
  "start": 0.0,
  "stop": 1.0,
  "use_original_formulation": false
}

State:
  step: None
  num_inference_steps: None
  timestep: None
  count_prepared: 0
  enabled: True
  num_conditions: 2

guider の設定を更新するには、pipe.guider = pipe.guider.new(...) を実行できます。

pipe.guider = pipe.guider.new(guidance_scale=5.0)

Guiderの詳細については、こちらをご覧ください。

HunyuanVideo15Pipeline

class diffusers.HunyuanVideo15Pipeline

< >

( text_encoder: Qwen2_5_VLTextModeltokenizer: Qwen2Tokenizertransformer: HunyuanVideo15Transformer3DModelvae: AutoencoderKLHunyuanVideo15scheduler: FlowMatchEulerDiscreteSchedulertext_encoder_2: T5EncoderModeltokenizer_2: ByT5Tokenizerguider: ClassifierFreeGuidance )

パラメータ

  • transformer (HunyuanVideo15Transformer3DModel) — エンコードされた動画の潜在変数（latents）をデノイズするための、条件付き Transformer（MMDiT）アーキテクチャです。
  • scheduler (FlowMatchEulerDiscreteScheduler) — transformer と組み合わせて、エンコードされた動画の潜在変数（latents）のノイズ除去に使用するスケジューラ。
  • vae (AutoencoderKLHunyuanVideo15) — 潜在表現へのエンコードおよびデコードを行う、動画用の変分オートエンコーダ（VAE）モデルです。
  • text_encoder (Qwen2.5-VL-7B-Instruct) — 具体的には、Qwen2.5-VL-7B-Instruct の Qwen2.5-VL-7B-Instruct バリアントです。
  • tokenizer (Qwen2Tokenizer) — [Qwen2Tokenizer] クラスのトークナイザー。
  • text_encoder_2 (T5EncoderModel) — T5EncoderModel のバリアント。
  • tokenizer_2 (ByT5Tokenizer) — [ByT5Tokenizer] クラスのトークナイザー
  • guider (ClassifierFreeGuidance) — [ClassifierFreeGuidance]classifier free guidance 用。

HunyuanVideo1.5 を使用したテキストから動画への生成を行う Pipeline です。

このモデルは DiffusionPipeline を継承しています。すべてのパイプラインに実装されている汎用的なメソッド（ダウンロード、保存、特定のデバイスでの実行など）については、スーパークラスのドキュメントを参照してください。

__call__

< >

( prompt: str | list[str] = Nonenegative_prompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_frames: int = 121num_inference_steps: int = 50sigmas: list[float] = Nonenum_videos_per_prompt: int | None = 1generator: typing.Union[torch.Generator, 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] = Noneprompt_embeds_2: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask_2: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_2: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask_2: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'np'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = None ) → ~HunyuanVideo15PipelineOutput or tuple

パラメータ

  • prompt (str または list[str]、任意) — 画像生成をガイドするためのプロンプトです。定義されていない場合、代わりに prompt_embeds を渡す必要があります。
  • negative_prompt (str または list[str]、省略可) — 画像生成をガイドしないプロンプトです。未定義の場合、代わりに negative_prompt_embeds を渡す必要があります。
  • height (int, 任意) — 生成される動画のピクセル単位の縦幅。
  • width (int, 任意) — 生成される動画の幅（ピクセル単位）。
  • num_frames (int、デフォルトは121) — 生成される動画のフレーム数です。
  • num_inference_steps (int、デフォルト値は50) — デノイジングのステップ数です。デノイジングのステップ数を増やすと、推論速度が遅くなる代わりに、通常、より高品質な動画が生成されます。
  • sigmas (list[float]、任意) — set_timesteps メソッドで sigmas 引数を受け付けるスケジューラーにおいて、デノイジングプロセスに使用するカスタムのシグマです。定義されていない場合、num_inference_steps が渡された際のデフォルトの動作が使用されます。
  • num_videos_per_prompt (int、任意、デフォルト値は 1) — 1 つのプロンプトごとに生成する動画の数です。
  • generator (torch.Generator または list[torch.Generator]、省略可) — 生成を決定論的にするための torch.Generator。
  • latents (torch.Tensor, 任意) — ガウス分布からサンプリングされた事前生成されたノイジーな潜在変数で、動画生成の入力として使用されます。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダムgeneratorを使用してサンプリングを行い、潜在変数テンソルが生成されます。
  • prompt_embeds (torch.Tensor, 任意) — 事前に生成されたテキスト埋め込みです。テキスト入力（プロンプトの重み付けなど）を簡単に調整するために使用できます。指定されない場合、prompt 入力引数からテキスト埋め込みが生成されます。
  • prompt_embeds_mask (torch.Tensor, 任意) — プロンプト埋め込み用の事前生成されたマスクです。
  • negative_prompt_embeds (torch.Tensor, 任意) — 事前に生成されたネガティブなテキスト埋め込みです。テキスト入力の調整、例えばプロンプトの重み付けなどを簡単に実行できます。指定されない場合、negative_prompt 入力引数から negative_prompt_embeds が生成されます。
  • negative_prompt_embeds_mask (torch.Tensor, 任意) — ネガティブプロンプトの埋め込み用の事前生成されたマスク。
  • prompt_embeds_2 (torch.Tensor, 任意) — 2番目のテキストエンコーダーから生成された事前テキスト埋め込み。テキスト入力の調整を簡単に実行できます。
  • prompt_embeds_mask_2 (torch.Tensor, 任意) — 2番目のテキストエンコーダーからのプロンプト埋め込み用の事前生成されたマスク。
  • negative_prompt_embeds_2 (torch.Tensor, 任意) — 2番目のテキストエンコーダーから生成された事前生成済みネガティブテキスト埋め込み。
  • negative_prompt_embeds_mask_2 (torch.Tensor, 任意) — 2番目のテキストエンコーダーからのネガティブプロンプト埋め込み用の事前生成されたマスク。
  • output_type (str、任意、デフォルトは"np") — 生成された動画の出力形式です。“np”、“pt”、“latent”のいずれかを選択します。
  • return_dict (bool、省略可、デフォルトは True) — HunyuanVideo15PipelineOutput を返すか、プレーンなタプルを返すかを指定します。
  • attention_kwargs (dict, 省略可) — 指定された場合、diffusers.models.attention_processor で定義されている self.processor 内の AttentionProcessor に渡される kwargs 辞書です。

戻り値

~HunyuanVideo15PipelineOutput または tuple

return_dict が True の場合、HunyuanVideo15PipelineOutput が返され、それ以外の場合は、最初の要素が生成された動画のリストである tuple が返されます。

生成用の pipeline への呼び出し関数。

例:

>>> import torch
>>> from diffusers import HunyuanVideo15Pipeline
>>> from diffusers.utils import export_to_video

>>> model_id = "hunyuanvideo-community/HunyuanVideo-1.5-480p_t2v"
>>> pipe = HunyuanVideo15Pipeline.from_pretrained(model_id, torch_dtype=torch.float16)
>>> pipe.vae.enable_tiling()
>>> pipe.to("cuda")

>>> output = pipe(
...     prompt="A cat walks on the grass, realistic",
...     num_inference_steps=50,
... ).frames[0]
>>> export_to_video(output, "output.mp4", fps=15)

encode_prompt

< >

( prompt: str | list[str]device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = Nonebatch_size: int = 1num_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Noneprompt_embeds_2: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask_2: typing.Optional[torch.Tensor] = None )

パラメータ

  • prompt (str または list[str]、省略可能) — エンコードするプロンプト
  • device — (torch.device): torch デバイス
  • batch_size (int) — プロンプトのバッチサイズ。デフォルト値は 1 です。
  • num_videos_per_prompt (int) — プロンプトごとに生成する画像の数
  • prompt_embeds (torch.Tensor, 任意) — 事前に生成されたテキスト埋め込みです。指定されない場合、prompt 入力引数からテキスト埋め込みが生成されます。
  • prompt_embeds_mask (torch.Tensor, 任意) — 事前に生成されたテキストマスクです。指定されない場合、prompt 入力引数からテキストマスクが生成されます。
  • prompt_embeds_2 (torch.Tensor, 任意) — ByT5 によって事前生成されたグリフテキスト埋め込みです。指定されない場合、prompt 入力引数を用いて self.tokenizer_2 および self.text_encoder_2 で生成されます。
  • prompt_embeds_mask_2 (torch.Tensor, 任意) — ByT5 によって事前生成されたグリフテキストマスクです。指定されない場合、prompt 入力引数を用いて self.tokenizer_2 および self.text_encoder_2 で生成されます。

prepare_cond_latents_and_mask

< >

( latentsdtype: typing.Optional[torch.dtype]device: typing.Optional[torch.device] ) → tuple

パラメータ

  • latents — メインの潜変数テンソル (B, C, F, H, W)

戻り値

tuple

(cond_latents_concat, mask_concat) - t2v の場合、両方ともゼロテンソルです

t2v 生成用の条件付き latents とマスクを準備します。

HunyuanVideo15ImageToVideoPipeline

クラス diffusers.HunyuanVideo15ImageToVideoPipeline

< >

( text_encoder: Qwen2_5_VLTextModeltokenizer: Qwen2Tokenizertransformer: HunyuanVideo15Transformer3DModelvae: AutoencoderKLHunyuanVideo15scheduler: FlowMatchEulerDiscreteSchedulertext_encoder_2: T5EncoderModeltokenizer_2: ByT5Tokenizerguider: ClassifierFreeGuidanceimage_encoder: SiglipVisionModelfeature_extractor: SiglipImageProcessorPil )

パラメータ

  • transformer (HunyuanVideo15Transformer3DModel) — エンコードされた動画の潜在変数（latents）をデノイズするための、条件付き Transformer（MMDiT）アーキテクチャです。
  • scheduler (FlowMatchEulerDiscreteScheduler) — transformer と組み合わせて、エンコードされた動画の潜在変数（latents）のノイズ除去に使用するスケジューラ。
  • vae (AutoencoderKLHunyuanVideo15) — 潜在表現へのエンコードおよびデコードを行う、動画用の変分オートエンコーダ（VAE）モデルです。
  • text_encoder (Qwen2.5-VL-7B-Instruct) — 具体的には、Qwen2.5-VL-7B-Instruct の Qwen2.5-VL-7B-Instruct バリアントです。
  • tokenizer (Qwen2Tokenizer) — [Qwen2Tokenizer] クラスのトークナイザー。
  • text_encoder_2 (T5EncoderModel) — T5EncoderModel のバリアント。
  • tokenizer_2 (ByT5Tokenizer) — [ByT5Tokenizer] クラスのトークナイザー
  • guider (ClassifierFreeGuidance) — [ClassifierFreeGuidance]classifier free guidance 用。
  • image_encoder (SiglipVisionModel) — SiglipVisionModel のバリアントです。
  • feature_extractor (SiglipImageProcessor) — SiglipImageProcessor バリアント。

HunyuanVideo1.5 を使用した画像から動画への生成を行う Pipeline です。

このモデルは DiffusionPipeline を継承しています。すべてのパイプラインに実装されている汎用的なメソッド（ダウンロード、保存、特定のデバイスでの実行など）については、スーパークラスのドキュメントを参照してください。

__call__

< >

( image: Imageprompt: str | list[str] = Nonenegative_prompt: str | list[str] = Nonenum_frames: int = 121num_inference_steps: int = 50sigmas: list[float] = Nonenum_videos_per_prompt: int | None = 1generator: typing.Union[torch.Generator, 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] = Noneprompt_embeds_2: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask_2: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_2: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask_2: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'np'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = None ) → ~HunyuanVideo15PipelineOutput or tuple

パラメータ

  • image (PIL.Image.Image) — 動画生成の条件として使用する入力画像です。
  • prompt (str または list[str]、省略可) — 動画生成をガイドするためのプロンプトです。未定義の場合、代わりに prompt_embeds を渡す必要があります。
  • negative_prompt (str または list[str]、省略可) — 動画生成をガイドしないプロンプトです。未定義の場合、代わりに negative_prompt_embeds を渡す必要があります。
  • num_frames (int、デフォルトは121) — 生成される動画のフレーム数です。
  • num_inference_steps (int、デフォルト値は50) — デノイジングのステップ数です。デノイジングのステップ数を増やすと、推論速度が遅くなる代わりに、通常、より高品質な動画が生成されます。
  • sigmas (list[float]、任意) — set_timesteps メソッドで sigmas 引数を受け付けるスケジューラーにおいて、デノイジングプロセスに使用するカスタムのシグマです。定義されていない場合、num_inference_steps が渡された際のデフォルトの動作が使用されます。
  • num_videos_per_prompt (int、任意、デフォルト値は 1) — 1 つのプロンプトごとに生成する動画の数です。
  • generator (torch.Generator または list[torch.Generator]、省略可) — 生成を決定論的にするための torch.Generator。
  • latents (torch.Tensor, 任意) — ガウス分布からサンプリングされた事前生成されたノイジーな潜在変数で、動画生成の入力として使用されます。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダムgeneratorを使用してサンプリングを行い、潜在変数テンソルが生成されます。
  • prompt_embeds (torch.Tensor, 任意) — 事前に生成されたテキスト埋め込みです。テキスト入力（プロンプトの重み付けなど）を簡単に調整するために使用できます。指定されない場合、prompt 入力引数からテキスト埋め込みが生成されます。
  • prompt_embeds_mask (torch.Tensor, 任意) — プロンプト埋め込み用の事前生成されたマスクです。
  • negative_prompt_embeds (torch.Tensor, 任意) — 事前に生成されたネガティブなテキスト埋め込みです。テキスト入力の調整、例えばプロンプトの重み付けなどを簡単に実行できます。指定されない場合、negative_prompt 入力引数から negative_prompt_embeds が生成されます。
  • negative_prompt_embeds_mask (torch.Tensor, 任意) — ネガティブプロンプトの埋め込み用の事前生成されたマスク。
  • prompt_embeds_2 (torch.Tensor, 任意) — 2番目のテキストエンコーダーから生成された事前テキスト埋め込み。テキスト入力の調整を簡単に実行できます。
  • prompt_embeds_mask_2 (torch.Tensor, 任意) — 2番目のテキストエンコーダーからのプロンプト埋め込み用の事前生成されたマスク。
  • negative_prompt_embeds_2 (torch.Tensor, 任意) — 2番目のテキストエンコーダーから生成された事前生成済みネガティブテキスト埋め込み。
  • negative_prompt_embeds_mask_2 (torch.Tensor, 任意) — 2番目のテキストエンコーダーからのネガティブプロンプト埋め込み用の事前生成されたマスク。
  • output_type (str、任意、デフォルトは"np") — 生成された動画の出力形式です。“np”、“pt”、“latent”のいずれかを選択します。
  • return_dict (bool、省略可、デフォルトは True) — HunyuanVideo15PipelineOutput を返すか、プレーンなタプルを返すかを指定します。
  • attention_kwargs (dict, 省略可) — 指定された場合、diffusers.models.attention_processor で定義されている self.processor 内の AttentionProcessor に渡される kwargs 辞書です。

戻り値

~HunyuanVideo15PipelineOutput または tuple

return_dict が True の場合、HunyuanVideo15PipelineOutput が返され、それ以外の場合は、最初の要素が生成された動画のリストである tuple が返されます。

生成用の pipeline への呼び出し関数。

例:

>>> import torch
>>> from diffusers import HunyuanVideo15ImageToVideoPipeline
>>> from diffusers.utils import export_to_video

>>> model_id = "hunyuanvideo-community/HunyuanVideo-1.5-480p_i2v"
>>> pipe = HunyuanVideo15ImageToVideoPipeline.from_pretrained(model_id, torch_dtype=torch.float16)
>>> pipe.vae.enable_tiling()
>>> pipe.to("cuda")

>>> image = load_image("https://huggingface.co/datasets/YiYiXu/testing-images/resolve/main/wan_i2v_input.JPG")

>>> output = pipe(
...     prompt="Summer beach vacation style, a white cat wearing sunglasses sits on a surfboard. The fluffy-furred feline gazes directly at the camera with a relaxed expression. Blurred beach scenery forms the background featuring crystal-clear waters, distant green hills, and a blue sky dotted with white clouds. The cat assumes a naturally relaxed posture, as if savoring the sea breeze and warm sunlight. A close-up shot highlights the feline's intricate details and the refreshing atmosphere of the seaside.",
...     image=image,
...     num_inference_steps=50,
... ).frames[0]
>>> export_to_video(output, "output.mp4", fps=24)

encode_prompt

< >

( prompt: str | list[str]device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = Nonebatch_size: int = 1num_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Noneprompt_embeds_2: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask_2: typing.Optional[torch.Tensor] = None )

パラメータ

  • prompt (str または list[str]、省略可能) — エンコードするプロンプト
  • device — (torch.device): torch デバイス
  • batch_size (int) — プロンプトのバッチサイズ。デフォルト値は 1 です。
  • num_videos_per_prompt (int) — プロンプトごとに生成する画像の数
  • prompt_embeds (torch.Tensor, 任意) — 事前に生成されたテキスト埋め込みです。指定されない場合、prompt 入力引数からテキスト埋め込みが生成されます。
  • prompt_embeds_mask (torch.Tensor, 任意) — 事前に生成されたテキストマスクです。指定されない場合、prompt 入力引数からテキストマスクが生成されます。
  • prompt_embeds_2 (torch.Tensor, 任意) — ByT5 によって事前生成されたグリフテキスト埋め込みです。指定されない場合、prompt 入力引数を用いて self.tokenizer_2 および self.text_encoder_2 で生成されます。
  • prompt_embeds_mask_2 (torch.Tensor, 任意) — ByT5 によって事前生成されたグリフテキストマスクです。指定されない場合、prompt 入力引数を用いて self.tokenizer_2 および self.text_encoder_2 で生成されます。

prepare_cond_latents_and_mask

< >

( latents: Tensorimage: Imagebatch_size: intheight: intwidth: intdtype: dtypedevice: device ) → tuple

パラメータ

  • latents — メインの潜変数テンソル (B, C, F, H, W)

戻り値

tuple

(cond_latents_concat, mask_concat) - t2v の場合、両方ともゼロテンソルです

t2v 生成用の条件付き latents とマスクを準備します。

HunyuanVideo15PipelineOutput

class diffusers.pipelines.hunyuan_video1_5.pipeline_output.HunyuanVideo15PipelineOutput

< >

( frames: Tensor )

パラメータ

  • frames (torch.Tensor、np.ndarray、または list[list[PIL.Image.Image]]) — 動画出力のリストです。batch_size, 長のネストされたリストであり、各サブリストが num_frames. 長のノイズ除去済み PIL 画像シーケンスを含む形式をとります。また、(batch_size, num_frames, channels, height, width) の形状を持つ NumPy 配列や Torch テンソルとしても指定できます。

HunyuanVideo1.5 パイプライン用の出力クラスです。

Update on GitHub

←HunyuanVideo Kandinsky 5.0 Video→