English Version

👋 加入我们的微信社区和Discord

---

继我们成功开源HunyuanVideo后，我们很高兴推出HunyuanVideo-I2V，一个新的图像到视频生成框架，加速开源社区的探索！

本仓库包含官方PyTorch模型定义、预训练权重及推理/采样代码。更多可视化效果请访问项目主页。同时，我们发布了LoRA训练代码，用于定制化特效生成，可创建更有趣的视频效果。

HunyuanVideo: A Systematic Framework For Large Video Generation Model

• 2025年3月6日: 👋 发布HunyuanVideo-I2V的推理代码和模型权重。下载地址

特效类型	参考图像	生成视频
头发生长
拥抱

• HunyuanVideo-I2V（图像到视频模型）
  • LoRA训练脚本
  • 推理代码
  • 模型权重
  • ComfyUI支持
  • 多GPU序列并行推理（提升多卡推理速度）
  • Diffusers集成
  • FP8量化权重

• HunyuanVideo-I2V 🌅
  • 🔥🔥🔥 最新动态
  • 🎥 演示
    • I2V 示例
    • 定制化I2V LoRA效果演示
  • 📑 开源计划
  • 目录
  • HunyuanVideo-I2V 整体架构
  • 📜 运行要求
  • 🛠️ 依赖安装
    • Linux 安装指引
  • 🧱 下载预训练模型
  • 🔑 单 GPU 推理
    • 使用图生视频模型的建议
    • 使用命令行
    • 更多配置
  • 🎉自定义 I2V LoRA 效果训练
    • 要求
    • 训练环境
    • 训练数据构建
    • 开始训练
    • 推理
  • 🔗 BibTeX
  • 致谢

---

基于HunyuanVideo强大的视频生成能力，我们将其扩展至图像到视频生成任务。为此，我们采用图像隐空间拼接技术，有效重构并融合参考图像信息至视频生成流程中。

由于我们使用预训练的Decoder-Only架构多模态大语言模型（MLLM）作为文本编码器，可用于显著增强模型对输入图像语义内容的理解能力，并实现图像与文本描述信息的深度融合。具体而言，输入图像经MLLM处理后生成语义图像tokens，这些tokens与视频隐空间tokens拼接，实现跨模态的全注意力计算。

我们的系统架构旨在最大化图像与文本模态的协同效应，确保从静态图像生成连贯的视频内容。该集成不仅提升了生成视频的保真度，还增强了模型对复杂多模态输入的解析能力。整体架构如下图所示：

下表展示了运行HunyuanVideo-I2V模型（batch size=1）生成视频的硬件要求：

模型	分辨率	GPU显存峰值
HunyuanVideo-I2V	720p	60GB

• 需配备支持CUDA的NVIDIA GPU
  • 测试环境为单卡80G GPU
  • 最低要求: 720p分辨率需至少60GB显存
  • 推荐配置: 建议使用80GB显存GPU以获得更佳生成质量
• 测试操作系统：Linux

首先克隆仓库：

git clone https://github.com/tencent/HunyuanVideo-I2V
cd HunyuanVideo-I2V

我们推荐使用 CUDA 12.4 或 11.8 的版本。

Conda 的安装指南可以参考这里。

# 1. 创建conda环境
conda create -n HunyuanVideo-I2V python==3.11.9

# 2. 激活环境
conda activate HunyuanVideo-I2V

# 3. 通过conda安装PyTorch等依赖
# CUDA 12.4版本
conda install pytorch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 pytorch-cuda=12.4 -c pytorch -c nvidia

# 4. 安装pip依赖
python -m pip install -r requirements.txt

# 5. 安装flash attention v2加速（需CUDA 11.8及以上）
python -m pip install ninja
python -m pip install git+https://github.com/Dao-AILab/flash-attention.git@v2.6.3

如果在特定 GPU 型号上遭遇 float point exception(core dump) 问题，可尝试以下方案修复：

# 确保已安装CUDA 12.4、CUBLAS>=12.4.5.8和CUDNN>=9.00（或直接使用我们的CUDA 12 docker镜像）
pip install nvidia-cublas-cu12==12.4.5.8
export LD_LIBRARY_PATH=/opt/conda/lib/python3.8/site-packages/nvidia/cublas/lib/

另外，我们提供了一个预构建的 Docker 镜像，可以使用如下命令进行拉取和运行。

# CUDA 12.4镜像（避免浮点异常）
docker pull hunyuanvideo/hunyuanvideo-i2v:cuda_12
docker run -itd --gpus all --init --net=host --uts=host --ipc=host --name hunyuanvideo-i2v --security-opt=seccomp=unconfined --ulimit=stack=67108864 --ulimit=memlock=-1 --privileged hunyuanvideo/hunyuanvideo-i2v:cuda_12

下载预训练模型的详细信息请参见 here。

类似于 HunyuanVideo，HunyuanVideo-I2V 支持高分辨率视频生成，分辨率最高可达 720P，视频长度最高可达 129 帧（5 秒）。

• 使用简短的提示：为了有效地引导模型的生成，请保持提示简短且直截了当。
• 包含关键元素：一个结构良好的提示应包括：
  • 主体：指定视频的主要焦点。
  • 动作：描述正在发生的运动或活动。
  • 背景（可选）：设置视频的场景。
  • 镜头（可选）：指示视角或视点。
• 避免过于详细的提示：冗长或高度详细的提示可能会导致视频输出中出现不必要的转场。

cd HunyuanVideo-I2V

python3 sample_image2video.py \
    --model HYVideo-T/2 \
    --prompt "A man with short gray hair plays a red electric guitar." \
    --i2v-mode \
    --i2v-image-path ./assets/demo/i2v/imgs/0.png \
    --i2v-resolution 720p \
    --video-length 129 \
    --infer-steps 50 \
    --flow-reverse \
    --flow-shift 17.0 \
    --seed 0 \
    --use-cpu-offload \
    --save-path ./results 

我们列出了一些常用的配置以方便使用：

参数	默认	描述
--prompt	None	用于视频生成的文本提示。
--model	HYVideo-T/2-cfgdistill	这里我们使用 HYVideo-T/2 用于 I2V，HYVideo-T/2-cfgdistill 用于 T2V 模式。
--i2v-mode	False	是否开启 I2V 模式。
--i2v-image-path	./assets/demo/i2v/imgs/0.png	用于视频生成的参考图像。
--i2v-resolution	720p	生成视频的分辨率。
--video-length	129	生成视频的长度。
--infer-steps	50	采样步骤的数量。
--flow-shift	7.0	流匹配调度器的偏移因子。
--flow-reverse	False	如果反转，从 t=1 学习/采样到 t=0。
--seed	None	生成视频的随机种子，如果为 None，则初始化一个随机种子。
--use-cpu-offload	False	使用 CPU 卸载模型加载以节省更多内存，对于高分辨率视频生成是必要的。
--save-path	./results	保存生成视频的路径。

下表显示了训练 HunyuanVideo-I2V lora 模型（批量大小 = 1）以生成视频的要求：

模型	分辨率	GPU 峰值内存
HunyuanVideo-I2V	360p	79GB

• 需要支持 CUDA 的 NVIDIA GPU。
  • 该模型在单个 80G GPU 上进行了测试。
  • 最低要求: 生成 360p 视频所需的最小 GPU 内存为 79GB。
  • 推荐: 建议使用 80GB 内存的 GPU 以获得更好的生成质量。
• 测试操作系统: Linux
• 注意: 您可以使用 360p 数据进行训练，并直接推断 540p 视频

pip install -r requirements.txt

提示描述：触发词直接写在视频说明中。建议使用短语或简短句子。

例如，AI 头发生长效果（触发词）：rapid_hair_growth, The hair of the characters in the video is growing rapidly. + 原始提示

准备好训练视频和提示对后，参考 这里 进行训练数据构建。

sh scripts/run_train_image2video_lora.sh

我们列出了一些训练特定配置以方便使用：

参数	默认	描述
SAVE_BASE	.	保存实验结果的根路径。
EXP_NAME	i2v_lora	保存实验结果的路径后缀。
DATA_JSONS_DIR	./assets/demo/i2v_lora/train_dataset/processed_data/json_path	由 hyvideo/hyvae_extract/start.sh 生成的数据 jsons 目录。
CHIEF_IP	0.0.0.0	主节点 IP 地址。

python3 sample_image2video.py \
    --model HYVideo-T/2 \
    --prompt "Two people hugged tightly, In the video, two people are standing apart from each other. They then move closer to each other and begin to hug tightly. The hug is very affectionate, with the two people holding each other tightly and looking into each other's eyes. The interaction is very emotional and heartwarming, with the two people expressing their love and affection for each other." \
    --i2v-mode \
    --i2v-image-path ./assets/demo/i2v_lora/imgs/embrace.png \
    --i2v-resolution 540p \
    --infer-steps 50 \
    --video-length 129 \
    --flow-reverse \
    --flow-shift 5.0 \
    --seed 0 \
    --use-cpu-offload \
    --save-path ./results \
    --use-lora \
    --lora-scale 1.0 \
    --lora-path ./ckpts/hunyuan-video-i2v-720p/lora/embrace_kohaya_weights.safetensors \

我们列出了一些 LoRA 特定配置以方便使用：

参数	默认	描述
--use-lora	None	是否开启 LoRA 模式。
--lora-scale	1.0	LoRA 模型的融合比例。
--lora-path	""	LoRA 模型的权重路径。

如果您发现 HunyuanVideo 对您的研究和应用有所帮助，请使用以下 BibTeX 引用：

@misc{kong2024hunyuanvideo,
      title={HunyuanVideo: A Systematic Framework For Large Video Generative Models}, 
      author={Weijie Kong, Qi Tian, Zijian Zhang, Rox Min, Zuozhuo Dai, Jin Zhou, Jiangfeng Xiong, Xin Li, Bo Wu, Jianwei Zhang, Kathrina Wu, Qin Lin, Aladdin Wang, Andong Wang, Changlin Li, Duojun Huang, Fang Yang, Hao Tan, Hongmei Wang, Jacob Song, Jiawang Bai, Jianbing Wu, Jinbao Xue, Joey Wang, Junkun Yuan, Kai Wang, Mengyang Liu, Pengyu Li, Shuai Li, Weiyan Wang, Wenqing Yu, Xinchi Deng, Yang Li, Yanxin Long, Yi Chen, Yutao Cui, Yuanbo Peng, Zhentao Yu, Zhiyu He, Zhiyong Xu, Zixiang Zhou, Zunnan Xu, Yangyu Tao, Qinglin Lu, Songtao Liu, Dax Zhou, Hongfa Wang, Yong Yang, Di Wang, Yuhong Liu, and Jie Jiang, along with Caesar Zhong},
      year={2024},
      archivePrefix={arXiv preprint arXiv:2412.03603},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2412.03603}, 
}

HunyuanVideo 的开源离不开诸多开源工作，这里我们特别感谢 SD3, FLUX, Llama, LLaVA, Xtuner, diffusers and HuggingFace 的开源工作和探索。另外，我们也感谢腾讯混元多模态团队对 HunyuanVideo 适配多种文本编码器的支持。