SCAIL：通过3D一致性姿态表示的上下文学习实现工作室级角色动画

本仓库包含**SCAIL（通过上下文学习实现工作室级角色动画）**的官方实现代码，该框架能够在多样且具有挑战性的条件下生成高保真度的角色动画，包括大幅度的动作变化、风格化角色以及多角色交互等场景。

🔎 动机与成果

SCAIL指出了阻碍角色动画达到制作级别的一些关键瓶颈：对不同角色的泛化能力有限，以及在复杂场景下动作不连贯的问题（例如，长期存在的多角色交互难题，还有诸如翻滚、转身等基础动作中的常见失败）。我们重新审视了角色动画的核心组件——如何表示姿态条件以及如何注入姿态条件。我们的框架解决了姿态表示无法同时避免身份泄露并保留丰富运动信息的难题，并促使模型对整个运动序列进行时空推理，从而生成更加自然和连贯的动作。请访问我们的项目页面，查看我们的方法、结果图库以及与其他基线方法的对比。

🌱 社区作品

❤️ 衷心感谢社区朋友们的创意！以下所有成果均在他们慷慨同意下分享。我们惊喜地发现，我们的模型展现出了一些意想不到的能力——能够理解2D角色的3D空间关系、驱动手绘作品，甚至在完全没有动物训练数据的情况下控制四足动物。

🗞️ 更新与计划

• 2026.3.1: 🔥 SCAIL现已原生集成于ComfyUI。
• 2025.12.19: 📣 我们提供SCAIL的Wan官方框架，而非SAT，以方便推理。请查看SCAIL的wan分支。我们将更新SCAIL在SAT上的训练代码，以确保可复现性。
• 2025.12.11: 💥 SCAIL的预览版现已在HuggingFace和ModelScope上开源。
• 2025.12.08: 🔥 我们发布了SCAIL在SAT上的推理代码。

待办事项

• SCAIL-14B-Preview模型权重（512p, 5s）和推理配置
• 提示词优化片段
• 在Wan官方框架上的实现
• SCAIL-Official(1.3B/14B)模型权重（改进稳定性与清晰度，具备原生长视频生成能力）和推理配置

📰 新闻

• 2026.3.1: 感谢toyxyz，现在可以使用Blender 3D绑定与scail-pose配合，从而实现更加动态和多样的形状与姿势，详情见#30。
• 2025.12.19: ComfyUI-SCAIL-Pose现在支持将NLF网格保存为3D glb动画，并可对SCAIL-Pose骨架进行3D预览。
• 2025.12.19: 感谢deepbeepmeep在WanGP中提供了低VRAM的SCAIL预览支持！WanGP版本具有以下优势：3D姿态预处理完全集成、速度优化，并兼容任何PyTorch版本。
• 2025.12.17: 感谢VantageWithAI，GGUF版本现已在SCAIL-Preview-GGUF上线！
• 2025.12.16: ❤️ 非常感谢KJ在适配方面所做的工作——SCAIL现已可在ComfyUI-WanVideoWrapper中使用！！！与此同时，姿态提取与渲染也部分适配到了ComfyUI-SCAIL-Pose，目前尚不支持多角色追踪。
• 2025.12.14: 🥳 感谢社区朋友们的测试！尽管SCAIL的训练样本中只有1.5%是动漫数据，而且我们并未特意收集多角色动漫数据，但该模型仍能很好地泛化到许多复杂的动漫角色。SCAIL-Preview的发布旨在展示我们所提出的姿态表示和模型架构的稳健性，并具有进一步扩展和提升的潜力。

🚀 入门

检查点下载

Chibi Gotham Battle	Homer Bullet Time (w/ Uni3c)	Anime Art Animation
Street Fighter 6 Motion Mimic
Doodle Art Animation	Dual Dance	Group Dance Quadrupeds Animation (w/ ViTPose)

检查点	下载链接	备注
SCAIL-Preview(14B)	🤗 Hugging Face 🤖 ModelScope	使用低于512p分辨率的数据训练。 如果使用其他分辨率，H和W都应能被32整除 （例如：704*1280）。

使用以下命令下载模型权重 （我们已将Wan VAE和T5模块集成到此检查点中，以方便使用）。

# 克隆仓库（跳过自动LFS文件下载）
GIT_LFS_SKIP_SMUDGE=1 git clone https://huggingface.co/zai-org/SCAIL-Preview

文件应按如下方式组织：

SCAIL-Preview/
├── Wan2.1_VAE.pth
├── model
│   ├── 1
│   │   └── mp_rank_00_model_states.pt
│   └── latest
└── umt5-xxl
    ├── ...

环境设置

请确保您的Python版本介于3.10至3.12之间，包括3.10和3.12。

pip install -r requirements.txt

🦾 使用方法

输入准备

输入数据应按如下方式组织，我们在examples/中提供了一些示例数据：

examples/
├── 001
│   ├── driving.mp4
│   ├── ref.jpg
└── 002
    ├── driving.mp4
    └── ref.jpg
...

姿势提取与渲染

使用git子模块下载scail_pose模块，然后按照POSE_INSTRUCTION.md中的说明从驱动视频中提取并渲染姿势。

git submodule update --init --recursive

之后，项目结构应如下所示：

SCAIL/
├── examples
├── sat
├── configs
├── ...
├── scail_pose

进入子目录并按照说明操作：

cd scail_pose
# 按照POSE_INSTRUCTION.md中的说明进行操作

姿势提取和渲染完成后，输入数据应按如下方式组织：

examples/
├── 001
│   ├── driving.mp4
│   ├── ref.jpg
│   └── rendered.mp4（或rendered_aligned.mp4）
└── 002
...

模型推理

在Wan官方框架中进行推理时，请参考SCAIL的wan分支。

在SAT中进行推理时，运行以下命令以通过CLI输入启动推理：

bash scripts/sample_sgl_14Bsc_xc_cli.sh

CLI会要求您以<prompt>@@<example_dir>的格式输入，例如the girl is dancing@@examples/001。example_dir应在姿势提取和渲染后包含rendered.mp4或rendered_aligned.mp4。结果将保存到samples/。

我们也支持直接输入文本，只需将sample_sgl_14Bsc_xc_txt.yaml中的input_file更改为您的输入文件路径，并在输入文件中填写如<prompt>@@<example_dir>的格式，然后运行以下命令：

bash scripts/sample_sgl_14Bsc_xc_txt.sh

请注意，我们的模型是使用长而详细的提示词训练的，尽管可以使用简短甚至为空的提示词，但效果可能不如长提示词理想。我们将提供提示词生成片段，利用Google Gemini读取参考图像和驱动动作，生成如下的详细提示词：“一位卷发女子正在岩石海岸线上欢快地跳舞，身穿一套时尚的蓝色两件套泳衣。她做出各种舞蹈动作，包括旋转、举手以及融入充满活力的海边氛围，身上的纹身和自信的姿态更增添了她的动感魅力。”

您还可以在configs/sampling/下的yaml文件中选择分辨率等采样配置，或直接修改sample_video.py以实现自定义的采样逻辑。

✨ 致谢

我们的实现建立在Wan 2.1的基础上，整体项目架构则基于SAT构建。我们还使用了NLFPose来可靠地提取姿势。感谢他们所做的卓越贡献及开源代码。

📄 引用

如果您在研究中发现本工作有用，请引用：

@article{yan2025scail,
  title={SCAIL: 通过上下文学习三维一致的姿势表示，迈向影棚级角色动画},
  author={Yan, Wenhao and Ye, Sheng and Yang, Zhuoyi and Teng, Jiayan and Dong, ZhenHui and Wen, Kairui and Gu, Xiaotao and Liu, Yong-Jin and Tang, Jie},
  journal={arXiv预印本 arXiv:2512.05905},
  year={2025}
}

🗝️ 许可证

本项目采用Apache许可证2.0版——详情请参阅LICENSE文件。

SCAIL 快速上手指南

SCAIL (Studio-Grade Character Animation via In-Context Learning) 是一个旨在实现工作室级角色动画的开源框架。它通过上下文学习 3D 一致的姿态表示，能够在大动作幅度、风格化角色及多角色互动等复杂场景下生成高保真动画。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐) 或 macOS
• Python 版本: 3.10 - 3.12 (必须在此范围内)
• 硬件要求: 需要支持 CUDA 的 NVIDIA GPU (显存建议 24GB 以上以运行 14B 模型，或使用社区提供的低显存优化版本)
• 依赖管理: 已安装 git 和 pip

安装步骤

1. 克隆项目代码

建议使用国内镜像加速克隆过程（如使用 ModelScope 或 Gitee 镜像，若不可用则使用官方源）。此处以官方源为例，并跳过自动下载大文件以便后续手动整理：

GIT_LFS_SKIP_SMUDGE=1 git clone https://huggingface.co/zai-org/SCAIL-Preview
cd SCAIL-Preview

注：如果您访问 HuggingFace 困难，可前往 ModelScope 下载模型权重文件。

2. 初始化子模块 (姿态提取工具)

SCAIL 依赖 scail_pose 模块进行姿态提取与渲染，需初始化子模块：

git submodule update --init --recursive

3. 安装 Python 依赖

在项目根目录下安装所需依赖：

pip install -r requirements.txt

提示：国内用户可使用清华或阿里镜像源加速安装：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

4. 下载模型权重

本项目已将 Wan VAE 和 T5 模块集成到检查点中。请确保目录结构如下：

SCAIL-Preview/
├── Wan2.1_VAE.pth
├── model
│   ├── 1
│   │   └── mp_rank_00_model_states.pt
│   └── latest
└── umt5-xxl
    ├── ...

如果自动下载失败，请手动从 HuggingFace 或 ModelScope 下载上述文件并放入对应目录。

基本使用

第一步：准备输入数据

在 examples/ 目录下创建文件夹（如 001），放入参考图片 (ref.jpg) 和驱动视频 (driving.mp4)：

examples/
├── 001
│   ├── driving.mp4
│   └── ref.jpg

第二步：姿态提取与渲染

进入 scail_pose 子目录，按照其中的 POSE_INSTRUCTION.md 文档执行姿态提取脚本。处理完成后，该目录下应生成 rendered.mp4 (或 rendered_aligned.mp4)。

cd scail_pose
# 请参考 POSE_INSTRUCTION.md 中的具体命令进行姿态提取
# 完成后返回根目录
cd ..

最终输入目录结构应包含渲染后的姿态视频：

examples/
├── 001
│   ├── driving.mp4
│   ├── ref.jpg
│   └── rendered.mp4

第三步：运行推理

本项目支持两种推理方式：Wan 官方框架（推荐，更便捷）和 SAT 框架。

方式 A：使用 Wan 官方框架 (推荐)

请切换至项目的 wan 分支 并按照该分支下的说明运行，以获得更好的兼容性和性能。

方式 B：使用 SAT 框架 (命令行交互)

在项目根目录运行以下脚本启动交互式推理：

bash scripts/sample_sgl_14Bsc_xc_cli.sh

当提示输入时，请按格式 <提示词>@@<示例目录> 输入，例如：

the girl is dancing@@examples/001

注意：模型基于长详细提示词训练，建议使用 Gemini 等工具生成包含角色细节、动作描述和环境氛围的详细提示词，以获得最佳效果。

生成的视频将保存在 samples/ 目录下。

方式 C：批量文件推理

如需批量处理，修改 configs/sampling/sample_sgl_14Bsc_xc_txt.yaml 中的 input_file 路径，并在该文件中按行填写 <提示词>@@<示例目录>，然后运行：

bash scripts/sample_sgl_14Bsc_xc_txt.sh

分辨率注意事项

模型训练分辨率为 512p。如果使用其他分辨率，请确保宽度和高度均能被 32 整除（例如 704x1280），以避免报错。