1. Abstract
HY-Motion 1.0 is a series of text-to-motion models from Tencent Hunyuan, based on Diffusion Transformer (DiT) and flow matching, to generate skeleton-driven 3D character animation sequences based on natural language descriptions, which can be further connected to common DCC/engine animation pipelines for redirection and assetization. The project provides both standard (about 1.0B parameters) and lightweight versions (about 0.46B parameters), and uses a complete link of "pre-trained → high-quality fine-tuning → reinforcement learning" for training to improve semantic alignment and physical naturalness.
2. Core features
1. Billion-Scale DiT + Flow Matching: Expands the DiT-style flow matching generation framework to 1 billion parameters, aiming for stronger instruction understanding and action quality.
2. Closed-loop training at all stages: large-scale pre-training learns general action priors, then fine-tunes details and smoothness with high-quality data, and finally further aligns text semantics and action naturalness through reinforcement learning related to human feedback and reward models.
3. Rich category coverage: After cleaning and annotating the data pipeline, it covers 6 categories and 200+ action categories, making it easy to build a more "usable" action library.
4. Engineering reasoning and optional prompt enhancement: Provide local batch reasoning scripts and Gradio interface; It also supports the optional "Duration Prediction and Prompt Rewriting" module (if not enabled, the relevant parameters need to be explicitly turned off).
3. Installation
- Install PyTorch (choose the CUDA/CPU version according to the official guidelines).
2. Pull code and install dependencies: After git clone the repository, execute the pip install -r requirements.txt in the directory.
3. Download weights: Place the model weights in the specified directory (standard version or Lite version) according to the instructions in the repository ckpts/README.md.
4. Run inference: Use local_infer.py for local batch generation (point to the corresponding weight directory through --model_path).
5. Start visualization: Run gradio_app.py to open the local web interface for interactive preview and testing.
4. Typical use cases
- Game and animation prefabrication: Use natural language to quickly generate action drafts to shorten the iteration cycle from storyboard to action library.
- Digital human/virtual anchor action library: Generate materials in batches according to style, rhythm, and emotional commands, and then do bone redirection and cleaning in a unified manner.
- DCC/Engine Pipeline Access: Import the generated skeleton actions into Blender/Maya or Unity/Unreal, and implement them as reusable assets with IK, redirection, and curve editing.
- Data enhancement and retrieval assistance: As an action generator, it is used to expand the coverage of long-tail action descriptions, or to build a retrieval and annotation process for "text-action" alignment (manual random inspection is required).
5. Ecology and competing products
- Ecological location: HY-Motion 1.0 is oriented to the "text → 3D human movement" link, and can be combined with SMPL/SMPLH-related human representations, DCC toolchains, and prompt engineering modules to form a "productionable" action asset process.
- Open source competitor references: MDM (Human Motion Diffusion Model), T2M-GPT, and early text-to-motion baselines and HumanML3D data/benchmarks are widely used in the community. The main differences of HY-Motion 1.0 are the 1B scale and a more complete training closed loop. It is still recommended to compare and evaluate the actual advantages and disadvantages based on your prompt distribution, character skeleton and landing pipeline.
6. Limitations and precautions
- Computing power and latency: 1 billion parameter inference has higher requirements for video memory and throughput, and resource-limited scenarios can give priority to the Lite version.
- Differences between skeleton and character: What is generated is a skeleton-driven action, and landing on a specific character usually requires redirection, bone length adaptation, sole sliding step correction and interspersed correction.
- Prompt rewrite/duration prediction dependency: If the relevant module is enabled, you need to configure the available service address or local model. Otherwise, the corresponding parameters should be turned off to avoid errors.
- Category and data bias: 200+ class coverage does not mean that "any description is stable", and scenarios such as complex interactions, props, and multiple people may require additional constraints or post-processing.
- Licensing and compliance: Weights and codes are licensed by specific communities, and the terms should be carefully checked before commercialization/distribution, and copyright and security reviews should be conducted on the generated content.
7. Project address
https://github.com/Tencent-Hunyuan/HY-Motion-1.0
8. Frequently asked questions
Q: How do I deal with errors related to duration_est/rewrite when running local_infer.py after installing HY-Motion 1.0?
A: If you do not configure the service address or local weight of the prompt override/duration prediction module, you need to turn off the corresponding functions in the inference parameters (such as disabling duration_est and rewrite) or configure the module correctly according to the repository instructions.
Q: How to choose between HY-Motion-1.0 and HY-Motion-1.0-Lite?
A: Choose the standard version when pursuing higher action quality and stronger instruction following, and have sufficient computing power; When you need a lower resource footprint or faster iterations, use Lite first, and then replicate key fragments with Standard Edition.
Q: How does the output of HY-Motion 1.0 connect to the Blender/UE/Unity animation pipeline?
A: The usual process is: export/convert the generated skeleton actions to your toolchain-readable format, then redirect the bones to the target character Rig, and perform post-processing such as IK, sole locking, and curve smoothing. Different project framework standards are different, and a stable redirect template needs to be established.
Q: Is HY-Motion 1.0 suitable for "actions with props/multiplayer/complex scenes"?
A: It is mainly aimed at single-player 3D human motion generation; Complex interactions often require stronger conditional input, post-processing, or specialized data support, so it is recommended to do small-scale verification and prepare for manual correction first.
