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 架构、通过字形感知文本编码增强的双语理解能力、渐进式预训练和后训练，以及高效的视频超分辨率网络。借助这些设计，我们开发了一个统一框架，能够在多种时长和分辨率下实现高质量的文本到视频和图像到视频生成。大量实验表明，这款紧凑且高效的模型在开源模型中确立了新的最先进水平。

您可以在 Tencent 组织下找到所有原始的 HunyuanVideo 检查点。

点击右侧边栏中的 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 后端 指南。

pipe.transformer.set_attention_backend("flash_hub")  # or your preferred backend

您可以使用 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 )

参数

使用 HunyuanVideo1.5 进行文本到视频生成的 Pipeline。

该模型继承自 DiffusionPipeline。有关为所有 pipeline 实现的通用方法（下载、保存、在特定设备上运行等），请参阅父类文档。

__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]，可选) — 用于在支持 sigmas 参数的调度器的 set_timesteps 方法中，为去噪过程指定自定义的 sigmas。如果未定义，则使用传入 num_inference_steps 时的默认行为。
  • num_videos_per_prompt (int，可选，默认为 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_embeds 将从 negative_prompt 输入参数生成。
  • negative_prompt_embeds_mask (torch.Tensor, 可选) — 预生成的负面提示嵌入掩码。
  • prompt_embeds_2 (torch.Tensor，可选) — 来自第二个文本编码器的预生成文本嵌入。可用于轻松调整文本输入。
  • prompt_embeds_mask_2 (torch.Tensor, 可选) — 来自第二个文本编码器的提示嵌入预生成掩码。
  • negative_prompt_embeds_2（torch.Tensor，可选）— 来自第二个文本编码器的预生成负向文本嵌入。
  • negative_prompt_embeds_mask_2（torch.Tensor，可选）— 来自第二个文本编码器的负提示嵌入的预生成掩码。
  • output_type (str，可选，默认为 "np") — 生成视频的输出格式。可选值包括 “np”、“pt” 或 “latent”。
  • return_dict (bool，可选，默认为 True) — 是否返回 HunyuanVideo15PipelineOutput 而不是普通元组。
  • attention_kwargs (dict, 可选) — 一个 kwargs 字典，如果指定，将传递给 diffusers.models.attention_processor 中定义的 AttentionProcessor，该处理器在 self.processor 下定义。

返回值

~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 预生成的字形文本嵌入。如果未提供，将使用 self.tokenizer_2 和 self.text_encoder_2 从 prompt 输入参数生成。
  • prompt_embeds_mask_2 (torch.Tensor, 可选) — 由 ByT5 预生成的字形文本掩码。如果未提供，将使用 self.tokenizer_2 和 self.text_encoder_2 从 prompt 输入参数生成。

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 生成准备条件潜变量和掩码。

HunyuanVideo15ImageToVideoPipeline

class diffusers.HunyuanVideo15ImageToVideoPipeline

< >

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

参数

使用 HunyuanVideo1.5 进行图像到视频生成的 Pipeline。

该模型继承自 DiffusionPipeline。有关为所有 pipeline 实现的通用方法（下载、保存、在特定设备上运行等），请参阅父类文档。

__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]，可选) — 用于在支持 sigmas 参数的调度器的 set_timesteps 方法中，为去噪过程指定自定义的 sigmas。如果未定义，则使用传入 num_inference_steps 时的默认行为。
  • num_videos_per_prompt (int，可选，默认为 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_embeds 将从 negative_prompt 输入参数生成。
  • negative_prompt_embeds_mask (torch.Tensor, 可选) — 预生成的负面提示嵌入掩码。
  • prompt_embeds_2 (torch.Tensor，可选) — 来自第二个文本编码器的预生成文本嵌入。可用于轻松调整文本输入。
  • prompt_embeds_mask_2 (torch.Tensor, 可选) — 来自第二个文本编码器的提示嵌入预生成掩码。
  • negative_prompt_embeds_2（torch.Tensor，可选）— 来自第二个文本编码器的预生成负向文本嵌入。
  • negative_prompt_embeds_mask_2（torch.Tensor，可选）— 来自第二个文本编码器的负提示嵌入的预生成掩码。
  • output_type (str，可选，默认为 "np") — 生成视频的输出格式。可选值包括 “np”、“pt” 或 “latent”。
  • return_dict (bool，可选，默认为 True) — 是否返回 HunyuanVideo15PipelineOutput 而不是普通元组。
  • attention_kwargs (dict, 可选) — 一个 kwargs 字典，如果指定，将传递给 diffusers.models.attention_processor 中定义的 AttentionProcessor，该处理器在 self.processor 下定义。

返回值

~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 预生成的字形文本嵌入。如果未提供，将使用 self.tokenizer_2 和 self.text_encoder_2 从 prompt 输入参数生成。
  • prompt_embeds_mask_2 (torch.Tensor, 可选) — 由 ByT5 预生成的字形文本掩码。如果未提供，将使用 self.tokenizer_2 和 self.text_encoder_2 从 prompt 输入参数生成。

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 生成准备条件潜变量和掩码。

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 视频→