How to run HunyuanVideo-Avatar on a cloud GPU
Rent a GPU on Deploy, then open a terminal in JupyterLab or over SSH. Install from the official Tencent-Hunyuan/HunyuanVideo-Avatar README, download the weights that repository’s weights page names, run the documented audio-driven command, and copy the mp4 files off the instance before you destroy it. Destroying the instance deletes its disk.
Text-to-video from the HunyuanVideo repository, whose README prints its own memory table, is How to run HunyuanVideo on a cloud GPU. Semi-body animation whose README lists tested GPUs as A100(80G), RTX4090D (24G), and V100(16G) is How to run EchoMimicV2 on a cloud GPU. Long-duration audio-driven portrait animation from a different repository is How to run Hallo2 on a cloud GPU. Audio-driven lip sync from a different repository is How to run MuseTalk on a cloud GPU. If the process runs out of memory: How to fix CUDA out of memory on a cloud GPU. The Gradio launch listens on port 8080: How to use SSH port forwarding on a cloud GPU.
LICENSE is the Tencent Hunyuan Community License Agreement, with the release date line “TencentHunyuanVideo-Avatar Release Date: May 28, 2025” (read 2026-11-13). Its opening sentence says the agreement does not apply in the European Union, the United Kingdom, and South Korea, and that it is limited to the Territory. Territory is defined as the worldwide territory excluding the European Union, the United Kingdom, and South Korea. Section 5© says use, reproduction, modification, distribution, or display outside the Territory is unlicensed. Section 2 grants a non-exclusive, non-transferable, royalty-free limited license for the Territory only, under the agreement and the acceptable-use exhibit. Section 4 says that if, on the version release date, the monthly active users of all products or services made available by or for the licensee is greater than 100 million monthly active users in the preceding calendar month, you must request a license from Tencent. That 100 million figure is an upstream license threshold. Section 9 says the agreement is governed by the laws of the Hong Kong Special Administrative Region of the People’s Republic of China. The acceptable-use exhibit includes a rule against impersonating another individual without consent, authorization, or legal right. Only animate a person you have the right to use. The GitHub license field on 2026-11-13 was NOASSERTION. The model API for tencent/HunyuanVideo-Avatar that day reported gated false, top-level license null, and no cardData.license. lastModified was 2025-05-28T15:02:17.000Z. Notice.txt lists third-party components. One copyright line in that file names a closed-model vendor. Copy that line from Notice.txt. This page does not print it. Read LICENSE before you redistribute the program or the weights.
The commands below are copied from the upstream files named in each step. They were not run on a CloudGPU instance for this page. Anything this page adds around them is marked.
What the README says about memory
The requirements section of the GitHub README says an NVIDIA GPU with CUDA support is required, that the model is tested on a machine with 8GPUs, that the minimum GPU memory required is 24GB for 704px768px129f but very slow, and that it recommends a GPU with 96GB of memory for better generation quality. The same section says that if OOM occurs when using a GPU with 80GB of memory, try to reduce the image resolution. The tested operating system line is Linux. Those sentences are the README’s. This page did not remeasure them. The words “very slow” are the README’s. This page does not add a duration.
A news line dated Jun 06, 2025 says HunyuanVideo-Avatar supports single GPU with only 10GB VRAM, with TeaCache included, and it thanks the Wan2GP repository. The section “Run with 10GB VRAM GPU (TeaCache supported)” points at that other repository and does not print a command. This page does not copy that repository’s install. The low-VRAM command this repository does print is the CPU-offload block below. It does not print a GB figure of its own.
The Hugging Face model card README repeats the parallel, single-GPU, CPU-offload, and Gradio commands. It does not include the requirements section, so it does not print 24GB, 80GB, 96GB, or 10GB.
The open-source plan lists ComfyUI with an empty checkbox. This page does not add a ComfyUI install. How to run HunyuanVideo on a cloud GPU is the repository that does document ComfyUI files.
GET /v1/public/compute-capabilities does not list GPUs. It returns feature flags. The memory column is vram_gb from gpu-prices.json, updated_at 2026-11-13T17:08:25.407Z. GET /v1/public/gpu-catalog the same day (generated_at 2026-11-13T17:08:26.374Z) listed the same names and the same vram_gb values, plus Ascend 910B at 64, which is not in gpu-prices.json and is not listed here. The catalog response also includes an availability field. This page does not copy it. Every prices row has gpu_count 1. Every catalog row has min_gpu_count 1. The README’s 8-GPU test, and the scripts that pass --nproc_per_node=8, are separate from that catalog column. This page does not claim a listing with 8 GPUs, and it does not mark a row as enough. Catalog rows at 24, 80, and 96 are the vram_gb values that match the numbers the requirements section prints. Catalog RTX 3080 is 10, which is the number in the Wan2GP news line, not a number this repository’s own command prints. Which listing you can start is on Deploy.
The catalog template list had no HunyuanVideo-Avatar template.
| Catalog name | vram_gb |
|---|---|
| RTX 2080 | 8 |
| RTX 3080 | 10 |
| RTX 2080 Ti | 11 |
| RTX 3080 Ti | 12 |
| V100 16G | 16 |
| A30 | 24 |
| RTX 3090 | 24 |
| RTX 4090 | 24 |
| RTX 4090D | 24 |
| RTX 4080 SUPER 32G | 32 |
| RTX 5090 | 32 |
| RTX 5090D | 32 |
| V100 32G | 32 |
| A100 40G | 40 |
| A800 40G | 40 |
| A40 | 48 |
| RTX 4090 48G | 48 |
| RTX 4090D 48G | 48 |
| RTX A6000 | 48 |
| NVIDIA RTX PRO 5000 72G | 72 |
| RTX PRO 5000 72G | 72 |
| A100 80G | 80 |
| A800 80G | 80 |
| H800 | 80 |
| RTX 6000D | 83 |
| H20 96G | 96 |
| RTX PRO 6000 96G | 96 |
| RTX PRO 6000 Max-Q | 96 |
| H20-3e 141G | 141 |
Install
On Deploy, choose Raw GPU. The README says it recommends CUDA 12.4 or 11.8 for the manual installation. The clone and the Linux block, copied. How to set up a conda environment on a cloud GPU says the -c pytorch conda channel is retired. The two conda install lines below still name that channel, because that is what the README prints. This page did not run them.
git clone https://github.com/Tencent-Hunyuan/HunyuanVideo-Avatar.git
cd HunyuanVideo-Avatar
That cd leaves the shell inside the clone. The README’s later lines cd HunyuanVideo-Avatar and cd HunyuanVideo-Avatar/weights are written for the parent of the clone. The blocks below replace those two cd lines and mark the replacement. The rest of each block is the README’s.
# 1. Create conda environment
conda create -n HunyuanVideo-Avatar python==3.10.9
# 2. Activate the environment
conda activate HunyuanVideo-Avatar
# 3. Install PyTorch and other dependencies using conda
# For CUDA 11.8
conda install pytorch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 pytorch-cuda=11.8 -c pytorch -c nvidia
# For 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. Install pip dependencies
python -m pip install -r requirements.txt
# 5. Install flash attention v2 for acceleration (requires CUDA 11.8 or above)
python -m pip install ninja
python -m pip install git+https://github.com/Dao-AILab/flash-attention.git@v2.6.3
requirements.txt pins torch only through that conda block. It pins diffusers==0.33.0, transformers>=4.50.0, and gradio>4.42.0. The README’s float-point-exception section prints two options. Option 2 replaces the conda torch line with pip install torch==2.4.0 --index-url https://download.pytorch.org/whl/cu118 and then reinstalls requirements.txt, ninja, and the same flash-attention tag. Option 1 prints pip install nvidia-cublas-cu12==12.4.5.8 and an LD_LIBRARY_PATH export. This page did not run either option.
The same README also prints Docker pulls of hunyuanvideo/hunyuanvideo:cuda_12 and hunyuanvideo/hunyuanvideo:cuda_11, a docker run for each, and then pip install gradio==3.39.0 diffusers==0.33.0 transformers==4.41.2 inside the container. That gradio==3.39.0 pin is not the gradio>4.42.0 line in requirements.txt. This page did not pull the images and does not choose between the two pins.
Download the weights
weights/README.md says all models are stored in HunyuanVideo-Avatar/weights by default. Its tree includes weights/ckpts/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states.pt and mp_rank_00_model_states_fp8.pt, plus llava_llama_image, text_encoder_2, whisper-tiny, and det_align. The tree prints the shard extension as safatensors. That spelling is the file’s. The heading is “Download HunyuanVideo-Avatar model”. The next sentence says “To download the HunyuanCustom model”. Both sentences are in that file. The download command is the one that file prints. The cd in front of it is the replacement marked below. The README’s comment about how long the download takes is not copied here.
python -m pip install "huggingface_hub[cli]"
# Added on this page. weights/README.md prints `cd HunyuanVideo-Avatar/weights`
# from the parent of the clone. The install block above is already inside the clone.
# `git rev-parse` still resolves the clone root from weights/ if this block is run again.
cd "$(git rev-parse --show-toplevel)/weights"
huggingface-cli download tencent/HunyuanVideo-Avatar --local-dir ./
The Hugging Face download guide is the newer hf download reference. The huggingface-cli download line is the one weights/README.md prints. This page did not download the repository.
Single-GPU inference, including the low-VRAM command
The single-GPU block sets OUTPUT_BASEPATH=./results-single and points --ckpt at mp_rank_00_model_states_fp8.pt. The README starts that block with cd HunyuanVideo-Avatar. The first line below replaces that cd. The rest is the README’s.
# Added on this page. The README's `cd HunyuanVideo-Avatar` is the path from the parent of the clone.
# The download block leaves the shell in weights/. This returns to the clone root from there, and stays there if the shell is already at the root.
cd "$(git rev-parse --show-toplevel)"
JOBS_DIR=$(dirname $(dirname "$0"))
export PYTHONPATH=./
export MODEL_BASE=./weights
OUTPUT_BASEPATH=./results-single
checkpoint_path=${MODEL_BASE}/ckpts/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states_fp8.pt
export DISABLE_SP=1
CUDA_VISIBLE_DEVICES=0 python3 hymm_sp/sample_gpu_poor.py \
--input 'assets/test.csv' \
--ckpt ${checkpoint_path} \
--sample-n-frames 129 \
--seed 128 \
--image-size 704 \
--cfg-scale 7.5 \
--infer-steps 50 \
--use-deepcache 1 \
--flow-shift-eval-video 5.0 \
--save-path ${OUTPUT_BASEPATH} \
--use-fp8 \
--infer-min
The low-VRAM block in the same README sets OUTPUT_BASEPATH=./results-poor, exports CPU_OFFLOAD=1, and adds --cpu-offload. It starts with the same cd HunyuanVideo-Avatar line. The first line below is the same replacement. The rest is the README’s.
# Added on this page, for the same reason as the single-GPU block.
# After that block the shell is at the clone root. This line stays there.
# If the shell is still in weights/, it returns to the clone root.
cd "$(git rev-parse --show-toplevel)"
JOBS_DIR=$(dirname $(dirname "$0"))
export PYTHONPATH=./
export MODEL_BASE=./weights
OUTPUT_BASEPATH=./results-poor
checkpoint_path=${MODEL_BASE}/ckpts/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states_fp8.pt
export CPU_OFFLOAD=1
CUDA_VISIBLE_DEVICES=0 python3 hymm_sp/sample_gpu_poor.py \
--input 'assets/test.csv' \
--ckpt ${checkpoint_path} \
--sample-n-frames 129 \
--seed 128 \
--image-size 704 \
--cfg-scale 7.5 \
--infer-steps 50 \
--use-deepcache 1 \
--flow-shift-eval-video 5.0 \
--save-path ${OUTPUT_BASEPATH} \
--use-fp8 \
--cpu-offload \
--infer-min
hymm_sp/sample_gpu_poor.py reads videoid from the batch, writes {save_path}/{videoid}.mp4, then runs ffmpeg to {save_path}/{videoid}_audio.mp4 and removes the first file. assets/test.csv has a videoid column. Its first row is 8. With the flags the single-GPU block passes, that row’s muxed file would be results-single/8_audio.mp4. The low-VRAM block uses results-poor the same way. --input is the csv. The image, audio, and prompt columns in that csv point at files under assets/. This page did not run the script.
The parallel example passes --nproc_per_node=8, uses mp_rank_00_model_states.pt rather than the fp8 file, and sets --save-path ${OUTPUT_BASEPATH} without assigning OUTPUT_BASEPATH in that block. This page does not claim the catalog has an 8-GPU listing. The command is the README’s. It was not run.
Gradio
The README’s Gradio section is bash ./scripts/run_gradio.sh. Run it from the clone root. After either inference block, the shell is already there. If it is still in weights/, the marked cd from those blocks returns to the clone root first. That script starts torchrun --nnodes=1 --nproc_per_node=8 --master_port 29605 hymm_gradio/flask_audio.py with the non-fp8 checkpoint, then runs python3 hymm_gradio/gradio_audio.py. hymm_gradio/flask_audio.py calls uvicorn.run(app, host="0.0.0.0", port=80). hymm_gradio/gradio_audio.py posts to http://127.0.0.1:80/predict2 and calls demo.launch(server_name='0.0.0.0', server_port=8080, share=True, allowed_paths=allowed_paths). The saved video path in that file is ./temp/video/ plus datetime.datetime.now().isoformat() plus .mp4. The reference image is ./temp/reference/ with the same timestamp and .png. share=True is in the launch call, so the process also requests a public Gradio link. This page does not remove that argument, and it did not start the app. From your own computer, the launch port is 8080. How to use SSH port forwarding on a cloud GPU is the tunnel. The torchrun line asks for 8 processes. The catalog rows cited above have min_gpu_count 1.
When it fails
CUDA out of memory. The requirements section says that if OOM occurs on a GPU with 80GB of memory, reduce the image resolution. The single-GPU commands pass --image-size 704. The printed low-VRAM flags in this repository are --use-fp8 and --cpu-offload. If the process raises that error, use how to fix CUDA out of memory on a cloud GPU.
“CUDA error: no kernel image is available for execution on the device” on an RTX 5090. The README’s torch lines are pytorch==2.4.0 with CUDA 11.8 or 12.4, and option 2 is torch==2.4.0 from the cu118 index. Those lines do not name compute capability 12.0. The RTX 5090 guide says that card is compute capability 12.0 (sm_120) and that PyTorch 2.7 and later, on a build for CUDA 12.8 or newer, is the line that announced support. This page did not install a torch wheel and did not re-test this package on an RTX 5090. Catalog RTX 5090 and RTX 5090D are 32. That is the catalog number only.
Save the videos, then destroy
Copy results-single or results-poor, including each {videoid}_audio.mp4 that sample_gpu_poor.py writes, and ./temp/video/ if you used Gradio, before you destroy the instance. Save your work before you destroy a cloud GPU is the checklist. The terms say data on local instance storage is permanently deleted when the instance is destroyed.
The pricing page FAQ states the billing rule in these words:
Per-minute options have a 1-minute minimum; unused prepaid minutes are refunded when you destroy the instance. Some configurations use whole-hour billing with a 1-hour minimum; unused time within a charged hour is not refunded on voluntary stop. The billing period, minimum charge and initial prepayment are shown before confirmation. No subscription.
Prices are not copied here.
Frequently asked questions
How much VRAM does the HunyuanVideo-Avatar README print?
The requirements section says the minimum GPU memory is 24GB for 704px768px129f but very slow, recommends a GPU with 96GB, and says that if OOM occurs on a GPU with 80GB, reduce the image resolution. The model is tested on a machine with 8GPUs. A news line says a different repository, Wan2GP, supports single GPU with only 10GB VRAM. The Hugging Face model card does not print those numbers. This page does not mark a catalog row as enough. Which listing you can start is on https://cloudgpu.app/deploy.
Which single-GPU commands does the README print?
The single-GPU block runs hymm_sp/sample_gpu_poor.py with --use-fp8 and --infer-min, the fp8 checkpoint mp_rank_00_model_states_fp8.pt, and --save-path ./results-single. The low-VRAM block adds CPU_OFFLOAD=1 and --cpu-offload, and sets --save-path ./results-poor. The 8-GPU example uses mp_rank_00_model_states.pt and does not assign OUTPUT_BASEPATH. This page did not run the commands.
Where are the videos saved, and which ports does Gradio use?
sample_gpu_poor.py writes {save_path}/{videoid}_audio.mp4 and removes the silent mp4. assets/test.csv supplies videoid. gradio_audio.py writes ./temp/video/ plus an isoformat timestamp plus .mp4. It calls demo.launch with server_name 0.0.0.0, server_port 8080, and share=True. flask_audio.py runs uvicorn on 0.0.0.0 port 80. scripts/run_gradio.sh starts that flask app with nproc_per_node=8. This page did not start the app.
What license and territory does the repository print?
LICENSE is the Tencent Hunyuan Community License Agreement, release date May 28, 2025. It says the agreement does not apply in the European Union, the United Kingdom, and South Korea, and it defines Territory as worldwide excluding those places. Section 4’s figure of greater than 100 million monthly active users is an upstream license threshold. Section 2 uses the word royalty-free. That word and that threshold are license text, not a CloudGPU price and not a storage allowance. The GitHub license field on 2026-11-13 was NOASSERTION. The model API reported gated false and no cardData.license.
Sources (read 2026-11-13, Asia/Shanghai)
- Tencent-Hunyuan/HunyuanVideo-Avatar README (24GB, 96GB, 80GB, 8-GPU test, 10GB Wan2GP news line, conda install, single-GPU and CPU-offload commands, Gradio script, empty ComfyUI checkbox): blob
a9ab2d4ec6b2b0d280f2489ff2f2d8c17cb27146. Repository HEAD8c31d0d489df8418fa36a2a709ebdf0b47c7bf06, committed 2025-12-16T12:32:46Z. https://github.com/Tencent-Hunyuan/HunyuanVideo-Avatar/blob/main/README.md weights/README.md(huggingface-cli download tencent/HunyuanVideo-Avatar --local-dir ./, thesafatensorsspelling, the HunyuanCustom sentence): read from repository HEAD. That file printscd HunyuanVideo-Avatar/weightsfrom the parent of the clone. This page replaces thatcd, and the inference blocks’cd HunyuanVideo-Avatar, withgit rev-parse --show-toplevelhymm_sp/sample_gpu_poor.py({videoid}.mp4,{videoid}_audio.mp4, localwhisper-tinyfolder): read from repository HEADscripts/run_gradio.sh(nproc_per_node=8, thenhymm_gradio/gradio_audio.py): read from repository HEADhymm_gradio/gradio_audio.py(server_name0.0.0.0,server_port8080,share=True,./temp/video/) andhymm_gradio/flask_audio.py(uvicorn0.0.0.0port 80): read from repository HEADLICENSE(Tencent Hunyuan Community License Agreement, Territory, section 4, section 9) andNotice.txt(third-party list; one copyright line not copied here): read from repository HEAD. GitHub license fieldNOASSERTION- Hugging Face model card
tencent/HunyuanVideo-Avatar(inference commands, no requirements GB figures): read 2026-11-13. Model API the same day:gatedfalse,licensenull,lastModified2025-05-28T15:02:17.000Z assets/test.csv(videoidcolumn, first value 8): read from repository HEAD- Public GPU memory: https://cloudgpu.app/gpu-prices.json (
updated_at2026-11-13T17:08:25.407Z) and https://cloudgpu.app/v1/public/gpu-catalog (generated_at2026-11-13T17:08:26.374Z).GET /v1/public/compute-capabilitiesreturned feature flags and no GPU list. The catalog had no HunyuanVideo-Avatar template
Cards you can start are on the Deploy page. Prices are on https://cloudgpu.app/pricing and are not repeated here.
Last updated: 2026-11-13 (Asia/Shanghai).