Model or dataset
Tencent-Hunyuan/HY-Motion-1.0 avatar
Tencent-Hunyuan/HY-Motion-1.0

HY-Motion 1.0: a billion parameter text to motion model whose Lite variant saves two gigabytes of VRAM

HY-Motion model for 3D human motion or 3D character animation generation.

2,671 stars225 forksPythonNOASSERTION

At a glance

What is it?
Tencent-Hunyuan/HY-Motion 1.0 generates skeleton-based 3D animation from text with Diffusion Transformer and Flow Matching, shipped as a 1.0B model and a 0.46B Lite model plus a CLI, a Gradio app and a VLM based evaluation metric. Its requirements file pins a 2020-vintage FBX binding and adds a third-party package index, its two installation steps disagree about your PyTorch version, and the repository carries a License.txt while its metadata names no licence at all.
Who is it for?
Use HY-Motion 1.0 if you need humanoid locomotion and gesture animation from English text and have a GPU with at least 24GB of VRAM to spare, and read the limitation list before you write prompts, because five categories of request are explicitly unsupported. Verify three things first.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • Tencent-Hunyuan/HY-Motion-1.02,671 ★ · +94
Star history
Repository2026-09-302026-11-15
Tencent-Hunyuan/HY-Motion-1.02.6k2.7k

94 Stars in the last 46 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The install step and the requirements file disagree about your PyTorch version

The installation section has two steps, and the first one is not compatible with the second on its own terms. It says to install PyTorch from the official site, then to clone the repository and install from the requirements file:

bash
git clone https://github.com/Tencent-Hunyuan/HY-Motion-1.0.git
cd HY-Motion-1.0/
# Make sure git-lfs is installed
git lfs pull
pip install -r requirements.txt

That requirements file pins torch to 2.5.1 and torchvision to 0.20.1 with no range at all, so whichever build of PyTorch you just installed from the official site is replaced by the pinned one. The same file pins diffusers at 0.26.3, transformers at 4.53.3, accelerate at 0.30.1 and huggingface_hub at 0.30.0, which is a coherent set, but it is a set chosen by the repository rather than by your driver or your CUDA build.

Two lines are looser than the rest. numpy is written as >=1.24.0,<2.0 and scipy as >=1.10.0, so those two float within bounds while everything else is nailed to an exact version. The pins are strict enough that an environment with a newer numpy will be downgraded rather than accepted, and the page gives no compatibility table to check your own stack against.

The first line of requirements.txt points pip at an index outside PyPI

The requirements file opens with a line that is not a package at all:

code
--extra-index-url https://gitlab.inria.fr/api/v4/projects/18692/packages/pypi/simple

That is a package index served from a GitLab project at Inria, added as an extra index rather than as a replacement, so pip searches both it and PyPI when resolving any dependency in this file. Nothing on the page says which package needs it. The pins are otherwise all from the usual public ecosystem, including fbxsdkpy at 2020.1.post2, a binding for the proprietary FBX SDK that is the oldest entry in the file by a wide margin and the only one whose terms are not visible on the page at all.

The practical consequence sits in how extra-index-url behaves rather than in what the project intends. With two indexes in play, a name that resolves in both places can be satisfied by either, so the index becomes part of your build's trust boundary whether or not any single package is fetched from it. If you pin this project into an environment that already has an index policy, that line is the one to reconcile first, and it is worth finding out which dependency introduced it before you decide whether to keep it.

Skipping the prompt module without the two disable flags is a hard error

The CLI is one script, local_infer.py, and the model is chosen with a path:

bash
python3 local_infer.py --model_path ckpts/tencent/HY-Motion-1.0
python3 local_infer.py --model_path ckpts/tencent/HY-Motion-1.0-Lite

The failure worth knowing about is documented as a note under the parameters. The Duration Prediction and Prompt Rewrite Module is optional, configured through --prompt_engineering_host and --prompt_engineering_model_path, and its weights are downloaded separately from a different account on HuggingFace. If you do not set those parameters you must also set --disable_duration_est and --disable_rewrite, and the note says plainly that otherwise the script will raise an error because the host is unavailable. So an omitted optional feature produces a hard stop, not a fallback, and the two disable flags are what turn it off cleanly.

The same feature has a second failure mode in the Gradio path. The page notes that if you have enough VRAM for the model but gradio fails with a VRAM-related error, you should run it with prompt engineering disabled through an environment variable: DISABLE_PROMPT_ENGINEERING=True python3 gradio_app.py. Two different mechanisms for the same toggle, one an argument pair and one an environment variable, because they belong to two different entry points.

Lite halves the parameters and returns two gigabytes of VRAM

The model zoo has two rows and both are dated 2025-12-30. HY-Motion-1.0 is the standard text2motion model at 1.0B parameters with a minimum of 26GB VRAM. HY-Motion-1.0-Lite is the lightweight one at 0.46B parameters with a minimum of 24GB.

Those two numbers deserve a second look, because they are the whole argument for the Lite variant. Going from 1.0B to 0.46B parameters is a reduction of more than half, and it moves the VRAM floor by 2GB, which is under eight percent of the larger figure. Whatever dominates that 24GB is not the weight count, so the practical gap between the two rows is small and the reason is not stated. Anyone choosing between them on hardware headroom is choosing on two gigabytes.

There is a second caveat attached to the table. It says the figures do not include the VRAM needed for LLM-based prompt engineering, which is the same optional module from the CLI. So the honest reading is that 24GB and 26GB are floors for the motion model alone, and a machine that just clears 26GB may still need headroom for the prompt rewriting step. The page also suggests three ways to lower the requirement: --num_seeds=1, a text prompt of fewer than 30 words, and motion under five seconds.

The prompting guide asks for 60 words, the memory note asks for 30

Two length thresholds appear on the page, and they belong to different contexts. For output quality the prompting guide asks for English and a prompt under 60 words. For memory pressure the note under the model table asks for fewer than 30 words, together with --num_seeds=1 and motion under five seconds. A prompt between 30 and 60 words is therefore inside the recommended range for quality and outside the one suggested for a tight memory budget, which is not a contradiction so much as two goals stated separately.

The same guide defines what a prompt should contain and, more usefully, what it must not. Focus on action descriptions and on movements of limbs and torso. Then five categories are marked unsupported: non-humanoid characters such as animals, subjective or visual attributes such as complex emotions, clothing or physical appearance, environment and camera descriptions including objects, scenes and angles, motions involving two or more people, and special modes such as seamless loop or in-place animations.

For anything outside English the guide routes you back through the same prompter module, which means a non-English workflow depends on the optional download. The four example prompts follow the same rule, each starting with A person and describing a sequence of two actions.

The root carries a License.txt while the metadata names no licence

The repository root is small and explains most of the layout by itself: .gitattributes, .gitignore, License.txt, README.md, README_zh_cn.md, assets/, ckpts/, examples/, gradio_app.py, hymotion/, local_infer.py, requirements.txt, scripts/, ssae/ and stats/. Three of those entries carry weight.

ckpts/ holds the weights, and the page sends you to ckpts/README.md for the download instructions rather than embedding them, so the model files are expected to arrive separately from the code. README_zh_cn.md is a Chinese version of the same page, linked from the first line, so the project maintains its documentation in two languages. ssae/ holds the evaluation code released in January 2026.

License.txt is the one that needs attention. The repository's own metadata carries no recognised licence identifier for this project, while a licence text file sits in the root, and the visible page states no licence terms at all. Those two facts do not agree, and the contents of that file are not on the page, so the terms are something you have to read yourself before you build on it. Anything that depends on redistribution rights, including commercial use and model weight licensing, should wait on that file rather than on the absence of a licence field.

The evaluation metric shipped two months after the models

The news section records two events in reverse order. On 29 January 2026 the project released the evaluation prompts and code for SSAE, a VLM-based metric for assessing the semantic alignment of generated videos, with usage details in the ssae directory. On 30 December 2025 it released the inference code and pretrained models of HY-Motion 1.0, with a HuggingFace Space and an official site. So the model came first and the way to measure it came later, and the metric is a video assessment tool built on a vision language model rather than a motion metric.

The model itself is described as a series of text-to-3D human motion models based on Diffusion Transformer and Flow Matching, producing skeleton-based animation that can be fed into 3D pipelines, and claiming to be the first to scale DiT-based text-to-motion models to a billion parameters. Training is described in three stages: large-scale pre-training on more than 3,000 hours of motion data, fine-tuning on 400 hours of curated high-quality 3D motion data, and reinforcement learning from human feedback and reward models.

There is no GitHub release to match those tags. The branch is master, it was last pushed on 18 July 2026, and the model files are versioned by the dated directory names in ckpts/ instead, which is where to look when you need to know which weights you are running.

Editorial conclusion

Use HY-Motion 1.0 if you need humanoid locomotion and gesture animation from English text and have a GPU with at least 24GB of VRAM to spare, and read the limitation list before you write prompts, because five categories of request are explicitly unsupported. Verify three things first. Decide whether you want the prompt engineering module, since omitting it without the two disable flags makes the CLI raise an error, and omitting it under memory pressure in the Gradio app needs an environment variable instead. Read requirements.txt closely, since it pins an older PyTorch than the one the install step tells you to fetch, and it adds a package index hosted outside PyPI. And resolve the licence question yourself, because the repository ships a License.txt while its metadata carries no licence identifier and the page does not state the terms.

Frequently asked questions

How much VRAM does HY-Motion 1.0 need to run?

The model zoo lists 26GB minimum for HY-Motion-1.0 at 1.0B parameters and 24GB for HY-Motion-1.0-Lite at 0.46B. Those figures exclude the VRAM needed for the LLM-based prompt engineering feature, and the page suggests --num_seeds=1, prompts under 30 words and motion under five seconds to reduce the requirement.

How do I install and run HY-Motion 1.0 locally?

Install PyTorch from its official site, then clone the repository, run git lfs pull and pip install -r requirements.txt, and fetch the weights following ckpts/README.md. Run it either as a batch script with python3 local_infer.py --model_path ckpts/tencent/HY-Motion-1.0 or through python3 gradio_app.py, which serves an interface on http://localhost:7860. macOS, Windows and Linux are supported.

What can HY-Motion 1.0 not generate?

Five categories are marked unsupported: non-humanoid characters such as animals, subjective or visual attributes such as emotions, clothing or appearance, environment and camera descriptions, motions with two or more people, and special modes such as seamless loop or in-place animations.

Which HY-Motion 1.0 models are available?

Two, both dated 2025-12-30: HY-Motion-1.0, the standard text2motion model at 1.0B parameters, and HY-Motion-1.0-Lite, the lightweight one at 0.46B. Weights are downloaded from the project's HuggingFace repository, and the download steps are kept in ckpts/README.md.

What licence applies to HY-Motion 1.0?

The page states no licence terms, and the repository metadata carries no recognised licence identifier. A License.txt file does sit at the repository root, so the terms have to be read from that file directly, particularly for commercial use or redistribution of the weights.

Official sources

  1. Issues
  2. Project website
  3. README
  4. Tencent-Hunyuan/HY-Motion-1.0 on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/tencent-hunyuan-hy-motion-1-0.svg)](https://hysenlabs.com/projects/tencent-hunyuan-hy-motion-1-0)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/tencent-hunyuan-hy-motion-1-0.svg)](https://hysenlabs.com/projects/tencent-hunyuan-hy-motion-1-0)

Was this useful?