DreamID-V: video face swapping with a diffusion transformer, from ByteDance

A paper release first, code second, weights third

DreamID-V is the code release of a face swapping method for video, authored by researchers at the Intelligent Creation Team at ByteDance and Tsinghua University, with several equal contributions and two corresponding authors. The README opens with a news list that reads as a timeline, and the order matters. The project page came first on 12/17/2025, the code followed on 01/05/2026, the paper on 01/06/2026, and the description notes an ECCV 2026 oral. The related image version, DreamID, was accepted at SIGGRAPH Asia 2025, and an omni version, DreamID-Omni, was accepted at ICML 2026. For a reader deciding whether to adopt the code, the relevant fact is that this is a research artefact published alongside a paper, not a product with a support commitment. The repository is Apache-2.0 licensed with a LICENSE.txt at the root, the default branch is main, and there are no GitHub releases, so the model weights are the released artefact rather than the source tree.

Three inference paths, one Wan 1.3B backbone

The repository does not ship a single script, it ships three, and the difference between them is the pose estimation and the checkpoint they use. The first is the MediaPipe variant, driven by generate_dreamidv.py. The second is the DWPose variant, generate_dreamidv_dwpose.py, which the README explains was introduced to fix a pose detection issue, improving the stability and robustness of pose extraction. The third is the Faster variant, generate_dreamidv_faster.py, which needs its own dreamidv_faster.pth checkpoint and which the news list describes as achieving a one times inference speed boost with lower VRAM usage. All three take the same core arguments: a size, a directory holding the Wan 2.1 1.3B checkpoint, a path to the DreamID-V checkpoint, a number of sample steps and a base seed. The directory layout in the tree explains the split, with dreamidv_wan, dreamidv_wan_faster, express_adaption, pose and a top level generate.py, alongside the three entry scripts.

Installation is a requirements file and a torch floor

There is no packaging step to speak of, no setup.py and no pyproject in the tree, which is typical for a research release. Installation is a single command, and the requirements file pins more than it floats:

# Ensure torch >= 2.4.0
pip install -r requirements.txt

The requirements list is worth reading before you install, because the pins carry opinions. torch is floored at 2.4.0 and torchvision at 0.19.0, diffusers is pinned exactly to 0.35.2 and transformers to 4.49.0, with tokenizers at 0.21.4 and accelerate at 1.11.0. flash_attn appears without a version, which means the build of that package has to succeed on your machine. The numpy constraint is unusual and explicit: numpy must be less than 2.0, and mediapipe is pinned at 0.10.5 for the same reason, with the comment in the requirements file stating that numpy must be below 2.0. xfuser is pinned to 0.4.4, and the multi-GPU path in the README separately asks for xfuser 0.4.1 or newer. The rest is the usual supporting cast: opencv-python, onnxruntime, imageio, imageio-ffmpeg, tqdm, easydict, ftfy and dashscope.

Weights come from Hugging Face, pose models from a directory

Two downloads are needed before anything runs. The DreamID-V weights are on Hugging Face at XuGuo699/DreamID-V, and the README notes they support 480P and 720P. The second download is the base model: Wan 2.1, specifically the Wan2.1-T2V-1.3B repository, needed for the VAE and the text encoder. On top of that, the pose estimation models have to be placed by hand in a fixed layout, and the README spells the tree out as DreamID-V containing a pose directory containing a models directory with dw-ll_ucoco_384.onnx and yolox_l.onnx. The Faster variant adds its own requirement on top, that dreamidv_faster.pth has been downloaded, and the README states the pose models must be in the correct directory before running. The dataset side of the release is separate: IDBench-Omni and a coming IDBench-V are published as Hugging Face datasets under the same account.

Running the Faster variant on a single GPU

The single GPU command for the Faster variant shows the shape of the interface, with a shell continuation across the arguments:

python generate_dreamidv_faster.py \
    --size 832*480 \
    --ckpt_dir wan2.1-1.3B path \
    --dreamidv_ckpt dreamidv_faster.pth path  \
    --sample_steps 16 \
    --base_seed 42

The arguments are all path or number or seed, and the placeholder paths are literally the words path, which tells you these are meant to be filled in with your own locations. The resolution is given as width by height, the sample steps differ from the other variants, and the base seed is fixed at 42 in the example, which makes the run reproducible. The DWPose variant is the same command with a different script and checkpoint, generate_dreamidv_dwpose.py with dreamidv.pth and twenty sample steps, and the MediaPipe variant uses generate_dreamidv.py with the same twenty steps.

Multi-GPU runs add FSDP, Ulysses and ring attention

The multi-GPU path is described as FSDP plus xDiT USP, and the extra flags make the parallelism strategy explicit. The command installs the fused attention package, then launches torchrun with a node count:

pip install "xfuser>=0.4.1"
torchrun --nproc_per_node=2 generate_dreamidv_faster.py \
    --size 832*480 \
    --ckpt_dir wan2.1-1.3B path \
    --dreamidv_ckpt dreamidv_faster.pth path  \
    --sample_steps 16 \
    --dit_fsdp \
    --t5_fsdp \
    --ulysses_size 2 \
    --ring_size 1 \
    --base_seed 42

The dit_fsdp and t5_fsdp flags shard the diffusion transformer and the text encoder, the ulysses_size flag sets the Ulysses sequence parallel degree, and ring_size sets the ring attention degree. With two processes and a Ulysses size of two, the work is spread across the sequence dimension. The DWPose and MediaPipe variants have the same structure with their own script names and step counts, so the difference between the three paths is confined to the script and the checkpoint, not to the parallel launch.

Reference images must be cropped faces, and quality has a resolution

The usage tips section sets expectations that the scripts themselves do not enforce, and they are worth reading before you spend an afternoon on bad results. Reference images should be cropped face images at a recommended resolution of 512x512, and the README says plainly to avoid full-body photos, because that is what preserves identity. For the highest fidelity output it recommends a resolution of 1280x720, while the model supports 480P and 720P. For simple scenes the sampling steps can be reduced to 20 to cut inference time significantly, and there is a claim that an internal model based on Seedance1.0 reaches high quality in under 8 steps, with a pointer to CapCut to try it. The output size in the sample commands is 832*480, which is neither of the two recommended values, so the defaults in the scripts are a starting point rather than the intended setting.

What the repository does not give you

There are real gaps, and they are the kind you find by looking rather than by reading a claim. There is no GitHub releases, no versioned package, and no installation path other than a requirements file, so the scripts are meant to be run from a checkout. There is no training or fine-tuning code, no evaluation harness, and no dataset loader; the datasets are published on Hugging Face separately, and the benchmarks they refer to are not runnable from this tree. The last push was on 2026-05-22, more than five months before this writing, so the tree is quiet even though the project is a published paper rather than an abandoned experiment. On the licensing side the repository is Apache-2.0, but the model weights on Hugging Face and the Wan 2.1 base model carry their own terms, and this repository inherits code from several open source projects that the acknowledgements section credits, including Wan2.1, Phantom and OpenHumanVid. A team building on this should treat the code licence and the weight licences as separate questions.

Editorial conclusion

DreamID-V fits a research team reproducing a published face swapping result, or a builder who needs identity-consistent video synthesis on a Wan 1.3B backbone and can work with cropped face reference images and the fixed sample scripts. It does not fit a product team expecting a packaged API, a general video generation tool, or a workflow that can use a full-body reference photo. Before running it, download the DreamID-V and Wan-2.1 weights, place the pose estimation models in the documented directory, and check that your GPU memory and torch version match the requirements file, since the Faster variant exists precisely because the base path is heavy.

Frequently asked questions

Official sources

1. bytedance/DreamID-V on GitHub
2. Issues
3. License: Apache-2.0
4. README