{ "hf_id": "MiniMaxAI/MiniMax-H3", "meta": { "title": "MiniMax-H3", "slug": "minimax-h3", "provider": "MiniMax", "description": "Open-weight general-purpose multimodal generation model — jointly generates 24 FPS video with native stereo audio from text, image, video, and audio references, served via vLLM-Omni", "date_added": "2026-08-02", "date_updated": "2026-10-21", "tasks": [ "omni" ], "performance_headline": "FastH3 VSA generates 15 s of 1344×768 video with synchronized stereo audio in 10.8 s server-side on 8×B300", "default_hardware": "b300", "related_recipes": [ "Wan-AI/Wan2.2-T2V-A14B-Diffusers", "nvidia/Cosmos3-Super-Image2Video" ], "hardware": { "gb200": "verified", "b300": "verified", "dgx_spark_gb10": "verified", "rtx_4090_2x": "verified", "rtx_pro_5000_4x": "verified", "rtx_5090_2x": "verified", "rtx_pro_6000_2x": "verified", "mi300x": "verified", "mi325x": "verified", "mi355x": "verified", "ascend_950pr": "verified" } }, "model": { "model_id": "MiniMaxAI/MiniMax-H3", "min_vllm_version": "0.26.0", "docker_image": { "nvidia": "vllm/vllm-omni:minimax-h3", "amd": "vllm/vllm-omni-rocm:minimax-h3" }, "docker_source": { "mount_path": "/path/to/vllm-omni" }, "architecture": "dense", "parameter_count": "64B", "active_parameters": "64B", "context_length": 0, "base_args": [ "--trust-remote-code", "--host", "0.0.0.0", "--port", "8000", "--num-gpus", "4", "--usp", "4", "--ring", "1", "--vae-patch-parallel-size", "4", "--vae-parallel-mode", "tile", "--vae-use-tiling" ], "base_env": { "VLLM_WORKER_MULTIPROC_METHOD": "spawn", "VLLM_OMNI_VIDEO_SYNC_TIMEOUT": "1800" }, "install": { "pip": { "command": "uv venv\nsource .venv/bin/activate\nuv pip install vllm==0.26.0\n", "note": "H3 also needs current vLLM-Omni main for the modular FL2VA/Ref2VA pipeline — see the extra install block below." }, "docker": { "command": "docker pull vllm/vllm-omni:minimax-h3", "note": "The H3 images bundle CUDA/ROCm and media dependencies, but predate the merged modular MiniMax-H3 pipeline. Clone current vLLM-Omni main; Docker mounts it read-only and prepends it to PYTHONPATH." }, "extras": [ { "note": "Gated checkpoint — request access on the model card, then download it locally. Serve the root directory: both DiTs remain in subdirectories while the modular service shares the encoder and VAEs.", "command": "hf download MiniMaxAI/MiniMax-H3 --local-dir /path/to/MiniMax-H3", "install_modes": [ "pip", "docker" ] }, { "note": "Ascend pip path: build vLLM v0.26.0 with the NPU target and vLLM Ascend from the matching release branch. This replaces the CUDA wheel shown in the pip tab above.", "command": "git clone --depth 1 --branch v0.26.0 https://github.com/vllm-project/vllm.git\ncd vllm && VLLM_TARGET_DEVICE=empty pip install -e . && cd ..\ngit clone --depth 1 --branch releases/v0.26.0rc https://github.com/vllm-project/vllm-ascend.git\ncd vllm-ascend && git submodule update --init --recursive && pip install -e . && cd ..\n", "install_modes": [ "pip" ], "brand": "Huawei" }, { "note": "pip path only: install current vLLM-Omni main for the modular MiniMax-H3 pipeline.", "command": "git clone --depth 1 https://github.com/vllm-project/vllm-omni.git /path/to/vllm-omni && cd /path/to/vllm-omni && uv pip install -e .", "install_modes": [ "pip" ] }, { "note": "Optional FastH3 adapters: download the Dense / Data-Free baseline and the recommended VSA / Data-Free artifact under the already-mounted H3 root. FastH3 preview v1 serves T2VA only and is fused at startup.", "command": "hf download FastVideo/FastVideo-FastH3-4-step-Preview-v1-LoRA \\\n dense-datafree/adapter_model.safetensors \\\n vsa-datafree/adapter_model.safetensors \\\n --local-dir /path/to/MiniMax-H3/FastH3-LoRA\n", "install_modes": [ "pip", "docker" ], "optional": true }, { "note": "Optional LightX2V Turbo few-step LoRA: download one Diffusers-layout artifact under the already-mounted H3 root. The filename carries the sampling contract, so do not rename it; the _comfyui_ exports are not supported.", "command": "hf download lightx2v/Minimax-h3-Turbo \\\n minimax_h3_fl2v_turbo_4step_v1.2_768p_bf16.safetensors \\\n --local-dir /path/to/MiniMax-H3/Turbo-LoRA\n", "install_modes": [ "pip", "docker" ], "optional": true }, { "note": "Optional CUDA-only FastH3 VSA kernel for the pip path. --no-deps preserves the PyTorch/CUDA stack managed by vLLM. The tested B300/SM103 route uses the Triton fallback with FASTVIDEO_VSA_SM100A=0.", "command": "uv pip install --no-deps fastvideo-kernel==0.3.5", "install_modes": [ "pip" ], "brand": "NVIDIA", "optional": true }, { "note": "Optional pip extra for explicitly comparing FA4 on datacenter Blackwell. The generated B300/GB200 route uses the TRTLLM_ATTN default; RTX PRO 5000 and the two-GPU RTX routes use CUDNN_ATTN.", "command": "cd /path/to/vllm-omni && uv pip install -e '.[fa4]'", "install_modes": [ "pip" ], "brand": "NVIDIA", "optional": true }, { "note": "Docker path only: clone current vLLM-Omni main to the path mounted by the generated command so it overrides the older package in the image.", "command": "git clone --depth 1 https://github.com/vllm-project/vllm-omni.git /path/to/vllm-omni", "install_modes": [ "docker" ] }, { "note": "pip path only: ffmpeg and ffprobe must be on PATH for reference-video preparation and MP4 video+audio muxing. The official Docker images already bundle them.", "command": "sudo apt-get install -y ffmpeg" } ] } }, "omni": { "port": 8000, "task_label": "Request Mode", "task_hint": "Select a ready-to-run MiniMax-H3 request preset. High-memory hardware keeps both DiTs loaded; memory-constrained hardware automatically starts the matching FL2VA-only or Ref2VA-only service.", "tasks": [ { "id": "t2v", "key": "t2va", "label": "T2VA - Text", "model_id": "/path/to/MiniMax-H3", "vram_minimum_gb": 202, "endpoint": "/v1/videos/sync", "description": "Text prompt to joint video and synchronized audio through the FL2VA DiT.", "benchmark": "python3 /path/to/vllm-omni/benchmarks/diffusion/diffusion_benchmark_serving.py \\\n --model /path/to/MiniMax-H3 \\\n --host localhost \\\n --port 8000 \\\n --endpoint /v1/videos \\\n --dataset random \\\n --task t2v \\\n --num-prompts 3 \\\n --max-concurrency 1 \\\n --warmup-requests 1 \\\n --warmup-concurrency 1 \\\n --seed 42 \\\n --random-request-config '[{\"width\":1344,\"height\":768,\"prompt\":\"Cinematic drone shot pushing through misty mountain ridges at sunrise, golden light catching the clouds, slow and smooth.\",\"num_inference_steps\":8,\"num_frames\":209,\"fps\":24,\"weight\":1}]' \\\n --extra-body '{\"flow_shift\":12.0,\"extra_params\":\"{\\\"task\\\":\\\"t2va\\\",\\\"duration\\\":8.7,\\\"aspect_ratio\\\":\\\"16:9\\\",\\\"audio_flow_shift\\\":3.0}\"}'\n", "hardware_overrides": { "rtx_pro_5000_4x": { "vram_minimum_gb": 288, "extra_args": [ "--task-type", "fl2va" ] }, "rtx_pro_6000_2x": { "vram_minimum_gb": 192, "extra_args": [ "--task-type", "fl2va" ] }, "rtx_5090_2x": { "vram_minimum_gb": 64, "extra_args": [ "--task-type", "fl2va" ] }, "rtx_4090_2x": { "vram_minimum_gb": 48, "extra_args": [ "--task-type", "fl2va" ], "curl": "curl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=In a snowy blue-purple forest, Ori carefully walks past a sleeping giant; footsteps crunch in the snow while the creature breathes and softly snorts.' \\\n -F 'width=1024' \\\n -F 'height=576' \\\n -F 'aspect_ratio=16:9' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=1101' \\\n -F 'extra_params={\"task\":\"t2va\",\"duration\":5.0,\"audio_flow_shift\":3.0}' \\\n -o t2va.mp4\n" }, "dgx_spark_gb10": { "vram_minimum_gb": 128, "extra_args": [ "--task-type", "fl2va" ], "curl": "curl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=In a snowy blue-purple forest, Ori carefully walks past a sleeping giant; footsteps crunch in the snow while the creature breathes and softly snorts.' \\\n -F 'width=1024' \\\n -F 'height=576' \\\n -F 'aspect_ratio=16:9' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=1101' \\\n -F 'extra_params={\"task\":\"t2va\",\"duration\":5.0,\"audio_flow_shift\":3.0}' \\\n -o t2va.mp4\n" }, "ascend_950pr": { "vram_minimum_gb": 128, "extra_args": [ "--task-type", "fl2va" ], "curl": "curl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=In a snowy blue-purple forest, Ori carefully walks past a sleeping giant; footsteps crunch in the snow while the creature breathes and softly snorts.' \\\n -F 'width=1024' \\\n -F 'height=576' \\\n -F 'aspect_ratio=16:9' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=60' \\\n -F 'flow_shift=12' \\\n -F 'seed=1101' \\\n -F 'extra_params={\"task\":\"t2va\",\"duration\":5.0,\"audio_flow_shift\":3.0}' \\\n -o t2va.mp4\n" } }, "curl": "curl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=In a snowy blue-purple forest, Ori carefully walks past a sleeping giant; footsteps crunch in the snow while the creature breathes and softly snorts.' \\\n -F 'width=1344' \\\n -F 'height=768' \\\n -F 'aspect_ratio=16:9' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=1101' \\\n -F 'extra_params={\"task\":\"t2va\",\"duration\":8.7,\"audio_flow_shift\":3.0}' \\\n -o t2va.mp4\n" }, { "id": "i2v", "key": "fl2va_first", "label": "FL2VA - First Frame", "model_id": "/path/to/MiniMax-H3", "vram_minimum_gb": 202, "endpoint": "/v1/videos/sync", "description": "First frame and prompt to video and audio. Omitting width and height keeps the input aspect ratio at a 768 px short edge.", "benchmark": "python3 /path/to/vllm-omni/benchmarks/diffusion/diffusion_benchmark_serving.py \\\n --model /path/to/MiniMax-H3 \\\n --host localhost \\\n --port 8000 \\\n --endpoint /v1/videos \\\n --dataset random \\\n --task ti2v \\\n --num-prompts 3 \\\n --max-concurrency 1 \\\n --warmup-requests 1 \\\n --warmup-concurrency 1 \\\n --num-input-images 1 \\\n --seed 42 \\\n --random-request-config '[{\"width\":1344,\"height\":768,\"prompt\":\"Continue the scene: the camera slowly pushes in on the subject as the background city lights drift and blur, with the actor singing softly and emotionally.\",\"num_inference_steps\":8,\"num_frames\":209,\"fps\":24,\"weight\":1}]' \\\n --extra-body '{\"flow_shift\":12.0,\"extra_params\":\"{\\\"task\\\":\\\"fl2va\\\",\\\"duration\\\":8.7,\\\"audio_flow_shift\\\":3.0}\"}'\n", "hardware_overrides": { "rtx_pro_5000_4x": { "vram_minimum_gb": 288, "extra_args": [ "--task-type", "fl2va" ] }, "rtx_pro_6000_2x": { "vram_minimum_gb": 192, "extra_args": [ "--task-type", "fl2va" ] }, "rtx_5090_2x": { "vram_minimum_gb": 64, "extra_args": [ "--task-type", "fl2va" ] }, "rtx_4090_2x": { "vram_minimum_gb": 48, "extra_args": [ "--task-type", "fl2va" ], "curl": "export FIRST_FRAME=/path/to/fl2va_first_frame.png\n\ncurl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=A man stands beside a yellow car at night. The car drives away; he follows it with his eyes and begins singing sadly, with synchronized voice and city ambience.' \\\n -F 'width=1024' \\\n -F 'height=576' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=2101' \\\n -F 'extra_params={\"task\":\"fl2va\",\"duration\":5.0,\"audio_flow_shift\":3.0}' \\\n -F \"input_reference=@${FIRST_FRAME};type=image/png\" \\\n -o fl2va_first.mp4\n" }, "dgx_spark_gb10": { "vram_minimum_gb": 128, "extra_args": [ "--task-type", "fl2va" ], "curl": "export FIRST_FRAME=/path/to/fl2va_first_frame.png\n\ncurl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=A man stands beside a yellow car at night. The car drives away; he follows it with his eyes and begins singing sadly, with synchronized voice and city ambience.' \\\n -F 'width=1024' \\\n -F 'height=576' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=2101' \\\n -F 'extra_params={\"task\":\"fl2va\",\"duration\":5.0,\"audio_flow_shift\":3.0}' \\\n -F \"input_reference=@${FIRST_FRAME};type=image/png\" \\\n -o fl2va_first.mp4\n" } }, "curl": "export FIRST_FRAME=/path/to/fl2va_first_frame.png\n\ncurl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=A man stands beside a yellow car at night. The car drives away; he follows it with his eyes and begins singing sadly, with synchronized voice and city ambience.' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=2101' \\\n -F 'extra_params={\"task\":\"fl2va\",\"duration\":8.7,\"audio_flow_shift\":3.0}' \\\n -F \"input_reference=@${FIRST_FRAME};type=image/png\" \\\n -o fl2va_first.mp4\n" }, { "id": "i2v", "key": "fl2va_first_last", "label": "FL2VA - First + Last", "model_id": "/path/to/MiniMax-H3", "vram_minimum_gb": 202, "endpoint": "/v1/videos/sync", "description": "Ordered first and last keyframes plus prompt to video and audio through the FL2VA DiT.", "benchmark": "python3 /path/to/vllm-omni/benchmarks/diffusion/diffusion_benchmark_serving.py \\\n --model /path/to/MiniMax-H3 \\\n --host localhost \\\n --port 8000 \\\n --endpoint /v1/videos \\\n --dataset random \\\n --task ti2v \\\n --num-prompts 3 \\\n --max-concurrency 1 \\\n --warmup-requests 1 \\\n --warmup-concurrency 1 \\\n --num-input-images 1 \\\n --seed 42 \\\n --random-request-config '[{\"width\":1344,\"height\":768,\"prompt\":\"Continue the scene: the camera slowly pushes in on the subject as the background city lights drift and blur, with the actor singing softly and emotionally.\",\"num_inference_steps\":8,\"num_frames\":209,\"fps\":24,\"weight\":1}]' \\\n --extra-body '{\"flow_shift\":12.0,\"extra_params\":\"{\\\"task\\\":\\\"fl2va\\\",\\\"duration\\\":8.7,\\\"audio_flow_shift\\\":3.0}\"}'\n", "hardware_overrides": { "rtx_pro_5000_4x": { "vram_minimum_gb": 288, "extra_args": [ "--task-type", "fl2va" ] }, "rtx_pro_6000_2x": { "vram_minimum_gb": 192, "extra_args": [ "--task-type", "fl2va" ] }, "rtx_5090_2x": { "vram_minimum_gb": 64, "extra_args": [ "--task-type", "fl2va" ] }, "rtx_4090_2x": { "vram_minimum_gb": 48, "extra_args": [ "--task-type", "fl2va" ], "curl": "export FIRST_FRAME=/path/to/fl2va_first_frame.png\nexport LAST_FRAME=/path/to/fl2va_last_frame.png\n\ncurl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=The subject moves naturally from the first image to the last image, with synchronized ambience and sound.' \\\n -F 'width=1024' \\\n -F 'height=576' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=2102' \\\n -F 'extra_params={\"task\":\"fl2va\",\"duration\":5.0,\"frame_indices\":[0,-1],\"audio_flow_shift\":3.0}' \\\n -F \"input_references=@${FIRST_FRAME};type=image/png\" \\\n -F \"input_references=@${LAST_FRAME};type=image/png\" \\\n -o fl2va_first_last.mp4\n" }, "dgx_spark_gb10": { "vram_minimum_gb": 128, "extra_args": [ "--task-type", "fl2va" ], "curl": "export FIRST_FRAME=/path/to/fl2va_first_frame.png\nexport LAST_FRAME=/path/to/fl2va_last_frame.png\n\ncurl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=The subject moves naturally from the first image to the last image, with synchronized ambience and sound.' \\\n -F 'width=1024' \\\n -F 'height=576' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=2102' \\\n -F 'extra_params={\"task\":\"fl2va\",\"duration\":5.0,\"frame_indices\":[0,-1],\"audio_flow_shift\":3.0}' \\\n -F \"input_references=@${FIRST_FRAME};type=image/png\" \\\n -F \"input_references=@${LAST_FRAME};type=image/png\" \\\n -o fl2va_first_last.mp4\n" } }, "curl": "export FIRST_FRAME=/path/to/fl2va_first_frame.png\nexport LAST_FRAME=/path/to/fl2va_last_frame.png\n\ncurl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=The subject moves naturally from the first image to the last image, with synchronized ambience and sound.' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=2102' \\\n -F 'extra_params={\"task\":\"fl2va\",\"duration\":8.7,\"frame_indices\":[0,-1],\"audio_flow_shift\":3.0}' \\\n -F \"input_references=@${FIRST_FRAME};type=image/png\" \\\n -F \"input_references=@${LAST_FRAME};type=image/png\" \\\n -o fl2va_first_last.mp4\n" }, { "id": "ti2v", "key": "ref_image", "label": "Ref2VA - Image", "model_id": "/path/to/MiniMax-H3", "vram_minimum_gb": 202, "endpoint": "/v1/videos/sync", "description": "Reference image and prompt to video and audio through the Ref2VA DiT.", "benchmark": "python3 /path/to/vllm-omni/benchmarks/diffusion/diffusion_benchmark_serving.py \\\n --model /path/to/MiniMax-H3 \\\n --host localhost \\\n --port 8000 \\\n --endpoint /v1/videos \\\n --dataset random \\\n --task ti2v \\\n --num-prompts 3 \\\n --max-concurrency 1 \\\n --warmup-requests 1 \\\n --warmup-concurrency 1 \\\n --num-input-images 1 \\\n --seed 42 \\\n --random-request-config '[{\"width\":1344,\"height\":768,\"prompt\":\"A white cat sits on a beige couch and slowly looks toward the camera as quiet room ambience continues.\",\"num_inference_steps\":8,\"num_frames\":209,\"fps\":24,\"weight\":1}]' \\\n --extra-body '{\"flow_shift\":12.0,\"extra_params\":\"{\\\"task\\\":\\\"ref2va\\\",\\\"duration\\\":8.7,\\\"audio_flow_shift\\\":3.0}\"}'\n", "hardware_overrides": { "rtx_pro_5000_4x": { "vram_minimum_gb": 288, "extra_args": [ "--task-type", "ref2va" ] }, "rtx_pro_6000_2x": { "vram_minimum_gb": 192, "extra_args": [ "--task-type", "ref2va" ] }, "rtx_5090_2x": { "vram_minimum_gb": 64, "extra_args": [ "--task-type", "ref2va" ] }, "rtx_4090_2x": { "vram_minimum_gb": 48, "extra_args": [ "--task-type", "ref2va" ], "curl": "export REF_IMAGE=/path/to/reference_assets/ref2va_image.png\n\ncurl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=A white cat sits on a beige couch and slowly looks toward the camera as quiet room ambience continues.' \\\n -F 'width=1024' \\\n -F 'height=576' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=3100' \\\n -F 'extra_params={\"task\":\"ref2va\",\"duration\":5.0,\"audio_flow_shift\":3.0}' \\\n -F \"input_reference=@${REF_IMAGE};type=image/png\" \\\n -o ref2va_image.mp4\n" }, "dgx_spark_gb10": { "vram_minimum_gb": 128, "extra_args": [ "--task-type", "ref2va" ], "curl": "export REF_IMAGE=/path/to/reference_assets/ref2va_image.png\n\ncurl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=A white cat sits on a beige couch and slowly looks toward the camera as quiet room ambience continues.' \\\n -F 'width=1024' \\\n -F 'height=576' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=3100' \\\n -F 'extra_params={\"task\":\"ref2va\",\"duration\":5.0,\"audio_flow_shift\":3.0}' \\\n -F \"input_reference=@${REF_IMAGE};type=image/png\" \\\n -o ref2va_image.mp4\n" } }, "curl": "export REF_IMAGE=/path/to/reference_assets/ref2va_image.png\n\ncurl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=A white cat sits on a beige couch and slowly looks toward the camera as quiet room ambience continues.' \\\n -F 'aspect_ratio=adaptive' \\\n -F 'short_edge=768' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=3100' \\\n -F 'extra_params={\"task\":\"ref2va\",\"duration\":8.0,\"audio_flow_shift\":3.0}' \\\n -F \"input_reference=@${REF_IMAGE};type=image/png\" \\\n -o ref2va_image.mp4\n" }, { "id": "ti2v", "key": "ref_image_audio", "label": "Ref2VA - Image + Audio", "model_id": "/path/to/MiniMax-H3", "vram_minimum_gb": 202, "endpoint": "/v1/videos/sync", "description": "Reference image and separate audio plus prompt to video and audio through the Ref2VA DiT.", "benchmark": "# Serve /path/to/reference_assets on port 8092 before running this benchmark.\npython3 /path/to/vllm-omni/benchmarks/diffusion/diffusion_benchmark_serving.py \\\n --model /path/to/MiniMax-H3 \\\n --host localhost \\\n --port 8000 \\\n --endpoint /v1/videos \\\n --dataset random \\\n --task ti2v \\\n --num-prompts 3 \\\n --max-concurrency 1 \\\n --warmup-requests 1 \\\n --warmup-concurrency 1 \\\n --num-input-images 1 \\\n --seed 42 \\\n --random-request-config '[{\"width\":1344,\"height\":768,\"prompt\":\"A white cat with black mustache and eyebrow markings sits on a beige couch, lip-syncing precisely to the complete reference audio.\",\"num_inference_steps\":8,\"num_frames\":209,\"fps\":24,\"weight\":1}]' \\\n --extra-body '{\"flow_shift\":12.0,\"audio_reference\":\"{\\\"audio_url\\\":\\\"http://localhost:8092/ref2va_audio.mp3\\\"}\",\"extra_params\":\"{\\\"task\\\":\\\"ref2va\\\",\\\"duration\\\":8.7,\\\"audio_flow_shift\\\":3.0}\"}'\n", "hardware_overrides": { "rtx_pro_5000_4x": { "vram_minimum_gb": 288, "extra_args": [ "--task-type", "ref2va" ] }, "rtx_pro_6000_2x": { "vram_minimum_gb": 192, "extra_args": [ "--task-type", "ref2va" ] }, "rtx_5090_2x": { "vram_minimum_gb": 64, "extra_args": [ "--task-type", "ref2va" ] }, "rtx_4090_2x": { "vram_minimum_gb": 48, "extra_args": [ "--task-type", "ref2va" ], "curl": "# audio_reference takes an HTTP(S) or data: URL. Serve local assets first:\n# python -m http.server 8092 --bind 127.0.0.1 --directory /path/to/reference_assets\nexport REF_IMAGE=/path/to/reference_assets/ref2va_image.png\nexport AUDIO_URL=http://127.0.0.1:8092/ref2va_audio.mp3\n\ncurl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=A white cat with black mustache and eyebrow markings sits on a beige couch, lip-syncing precisely to the complete reference audio.' \\\n -F 'width=1024' \\\n -F 'height=576' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=3101' \\\n -F 'extra_params={\"task\":\"ref2va\",\"duration\":5.0,\"audio_flow_shift\":3.0}' \\\n -F \"input_reference=@${REF_IMAGE};type=image/png\" \\\n -F \"audio_reference={\\\"audio_url\\\":\\\"${AUDIO_URL}\\\"}\" \\\n -o ref2va_image_audio.mp4\n" }, "dgx_spark_gb10": { "vram_minimum_gb": 128, "extra_args": [ "--task-type", "ref2va" ], "curl": "# audio_reference takes an HTTP(S) or data: URL. Serve local assets first:\n# python -m http.server 8092 --bind 127.0.0.1 --directory /path/to/reference_assets\nexport REF_IMAGE=/path/to/reference_assets/ref2va_image.png\nexport AUDIO_URL=http://127.0.0.1:8092/ref2va_audio.mp3\n\ncurl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=A white cat with black mustache and eyebrow markings sits on a beige couch, lip-syncing precisely to the complete reference audio.' \\\n -F 'width=1024' \\\n -F 'height=576' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=3101' \\\n -F 'extra_params={\"task\":\"ref2va\",\"duration\":5.0,\"audio_flow_shift\":3.0}' \\\n -F \"input_reference=@${REF_IMAGE};type=image/png\" \\\n -F \"audio_reference={\\\"audio_url\\\":\\\"${AUDIO_URL}\\\"}\" \\\n -o ref2va_image_audio.mp4\n" } }, "curl": "# audio_reference takes an HTTP(S) or data: URL. Serve local assets first:\n# python -m http.server 8092 --bind 127.0.0.1 --directory /path/to/reference_assets\nexport REF_IMAGE=/path/to/reference_assets/ref2va_image.png\nexport AUDIO_URL=http://127.0.0.1:8092/ref2va_audio.mp3\n\ncurl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=A white cat with black mustache and eyebrow markings sits on a beige couch, lip-syncing precisely to the complete reference audio before shifting from confusion to deadpan speechlessness.' \\\n -F 'width=1344' \\\n -F 'height=768' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=3101' \\\n -F 'extra_params={\"task\":\"ref2va\",\"duration\":15.0,\"audio_flow_shift\":3.0}' \\\n -F \"input_reference=@${REF_IMAGE};type=image/png\" \\\n -F \"audio_reference={\\\"audio_url\\\":\\\"${AUDIO_URL}\\\"}\" \\\n -o ref2va_image_audio.mp4\n" }, { "id": "ti2v", "key": "ref_video_mixed", "label": "Ref2VA - Video / Mixed", "model_id": "/path/to/MiniMax-H3", "vram_minimum_gb": 202, "endpoint": "/v1/videos/sync", "description": "One or more ordered video or mixed media references plus prompt to video and audio through the Ref2VA DiT.", "benchmark": "python3 /path/to/vllm-omni/benchmarks/diffusion/diffusion_benchmark_serving.py \\\n --model /path/to/MiniMax-H3 \\\n --host localhost \\\n --port 8000 \\\n --endpoint /v1/videos \\\n --dataset random \\\n --task v2v \\\n --num-prompts 3 \\\n --max-concurrency 1 \\\n --warmup-requests 1 \\\n --warmup-concurrency 1 \\\n --seed 42 \\\n --random-request-config '[{\"width\":1344,\"height\":768,\"prompt\":\"Restyle the reference footage into a cinematic night scene with neon reflections, keeping the same camera motion and subject.\",\"num_inference_steps\":8,\"num_frames\":209,\"fps\":24,\"weight\":1}]' \\\n --extra-body '{\"flow_shift\":12.0,\"extra_params\":\"{\\\"task\\\":\\\"ref2va\\\",\\\"duration\\\":8.7,\\\"aspect_ratio\\\":\\\"16:9\\\",\\\"audio_flow_shift\\\":3.0}\"}'\n", "hardware_overrides": { "rtx_pro_5000_4x": { "vram_minimum_gb": 288, "extra_args": [ "--task-type", "ref2va" ] }, "rtx_pro_6000_2x": { "vram_minimum_gb": 192, "extra_args": [ "--task-type", "ref2va" ] }, "rtx_5090_2x": { "vram_minimum_gb": 64, "extra_args": [ "--task-type", "ref2va" ] }, "rtx_4090_2x": { "vram_minimum_gb": 48, "extra_args": [ "--task-type", "ref2va" ], "curl": "export SUBJECT_VIDEO=/path/to/green_screen_subject.mp4\nexport BACKGROUND_VIDEO=/path/to/fairytale_background.mov\n\ncurl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=Remove the green screen background of Video 1 and replace it with the fairytale environment from Video 2. Match motion and relight the character to fit the scene.' \\\n -F 'width=1024' \\\n -F 'height=576' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=3102' \\\n -F 'extra_params={\"task\":\"ref2va\",\"duration\":5.0,\"audio_flow_shift\":3.0}' \\\n -F \"input_references=@${SUBJECT_VIDEO};type=video/mp4\" \\\n -F \"input_references=@${BACKGROUND_VIDEO};type=video/quicktime\" \\\n -o ref2va_video_mixed.mp4\n" }, "dgx_spark_gb10": { "vram_minimum_gb": 128, "extra_args": [ "--task-type", "ref2va" ], "curl": "export SUBJECT_VIDEO=/path/to/green_screen_subject.mp4\nexport BACKGROUND_VIDEO=/path/to/fairytale_background.mov\n\ncurl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=Remove the green screen background of Video 1 and replace it with the fairytale environment from Video 2. Match the background motion to the character actions and relight the character to fit the scene.' \\\n -F 'width=1024' \\\n -F 'height=576' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=3102' \\\n -F 'extra_params={\"task\":\"ref2va\",\"duration\":5.0,\"audio_flow_shift\":3.0}' \\\n -F \"input_references=@${SUBJECT_VIDEO};type=video/mp4\" \\\n -F \"input_references=@${BACKGROUND_VIDEO};type=video/quicktime\" \\\n -o ref2va_video_mixed.mp4\n" } }, "curl": "export SUBJECT_VIDEO=/path/to/green_screen_subject.mp4\nexport BACKGROUND_VIDEO=/path/to/fairytale_background.mov\n\ncurl -sS -X POST http://localhost:8000/v1/videos/sync \\\n -F 'prompt=Remove the green screen background of Video 1 and replace it with the fairytale environment from Video 2. Match the background motion to the character actions and relight the character to fit the scene.' \\\n -F 'width=1344' \\\n -F 'height=768' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=3102' \\\n -F 'extra_params={\"task\":\"ref2va\",\"duration\":15.0,\"audio_flow_shift\":3.0}' \\\n -F \"input_references=@${SUBJECT_VIDEO};type=video/mp4\" \\\n -F \"input_references=@${BACKGROUND_VIDEO};type=video/quicktime\" \\\n -o ref2va_video_mixed.mp4\n" } ] }, "features": {}, "opt_in_features": [], "variants": { "default": { "precision": "bf16", "vram_minimum_gb": 202, "description": "BF16 modular service — two 66.3 GB DiTs share the 51.5 GB Qwen3-VL encoder and ~10.6 GB VAEs. Use --task-type fl2va or ref2va on memory-constrained profiles to load one DiT.", "hardware_overrides": { "dgx_spark_gb10": { "extra_args": [ "--num-gpus", "1", "--usp", "1", "--ring", "1", "--vae-patch-parallel-size", "1", "--quantization", "fp8", "--init-timeout", "3600", "--enforce-eager", "--diffusion-attention-backend", "CUDNN_ATTN" ], "extra_env": { "VLLM_OMNI_VIDEO_SYNC_TIMEOUT": "7200" } }, "ascend_950pr": { "docker_image": "quay.io/ascend/vllm-omni:minimax-h3", "extra_args": [ "--num-gpus", "1", "--tensor-parallel-size", "1", "--usp", "1", "--ring", "1", "--text-encoder-tp-size", "1", "--vae-patch-parallel-size", "1", "--quantization", "int8", "--init-timeout", "14400", "--stage-init-timeout", "14400" ], "extra_env": { "VLLM_OMNI_VIDEO_SYNC_TIMEOUT": "14400" } }, "rtx_pro_5000_4x": { "extra_args": [ "--num-gpus", "4", "--tensor-parallel-size", "2", "--usp", "2", "--ring", "1", "--text-encoder-tp-size", "4", "--vae-patch-parallel-size", "4", "--diffusion-attention-backend", "CUDNN_ATTN" ] }, "rtx_pro_6000_2x": { "extra_args": [ "--num-gpus", "2", "--tensor-parallel-size", "2", "--usp", "1", "--ring", "1", "--text-encoder-tp-size", "2", "--vae-patch-parallel-size", "2" ] }, "rtx_5090_2x": { "extra_args": [ "--num-gpus", "2", "--tensor-parallel-size", "2", "--usp", "1", "--ring", "1", "--text-encoder-tp-size", "2", "--vae-patch-parallel-size", "2", "--diffusion-attention-backend", "CUDNN_ATTN", "--enable-distributed-layerwise-offload", "--dlo-no-use-allgather", "--dlo-resident-layers", "20", "--enforce-eager" ], "extra_env": { "VLLM_OMNI_VIDEO_SYNC_TIMEOUT": "14400" } }, "rtx_4090_2x": { "extra_args": [ "--num-gpus", "2", "--tensor-parallel-size", "2", "--usp", "1", "--ring", "1", "--text-encoder-tp-size", "2", "--vae-patch-parallel-size", "2", "--diffusion-attention-backend", "CUDNN_ATTN", "--enable-distributed-layerwise-offload", "--dlo-no-use-allgather", "--dlo-resident-layers", "12", "--enforce-eager" ], "extra_env": { "VLLM_OMNI_VIDEO_SYNC_TIMEOUT": "14400" } } } } }, "hardware_overrides": { "blackwell": { "extra_env": { "FLASHINFER_DISABLE_VERSION_CHECK": "1" } }, "amd": { "extra_args": [ "--text-encoder-tp-size", "4" ], "extra_env": { "VLLM_ROCM_USE_AITER": "1" } } }, "guide": "## Overview\n\nMiniMax H3 is an **open-weight, general-purpose multimodal generation model**. Rather than\nbeing confined to one specialized task — generate, edit, or reference — H3 reads a\nmultimodal context that mixes text, images, video, and audio together, interprets the\ncreative intent as a whole, and produces coherent audio-visual output end to end.\n\nArchitecturally it is a **CFG-distilled joint video/audio diffusion transformer** served\nthrough vLLM-Omni's OpenAI-compatible `/v1/videos` API. Every request returns a single MP4\ncontaining H.264 video and **native stereo audio** — the audio is generated jointly with\nthe video by the same DiT, not dubbed on afterwards.\n\nThree capability areas the model targets:\n\n- **Commercial-grade generation** — film and entertainment, advertising and branding,\n e-commerce, gaming; dynamic typography, VFX, product showcases, UI/UX motion design.\n- **Native multimodal understanding + generation** — interprets characters, motion, sound,\n emotion, cinematography, and visual style across mixed references, then combines them.\n- **Precise multimodal editing and control** — iterative refinement of characters, objects,\n scenes, sound, and rhythm with strong instruction following.\n\nThe checkpoint contains two DiT backbones that share the encoder and VAEs:\n\n| DiT | Tasks | Conditioning |\n|---|---|---|\n| `FL2VA` | `t2va`, `fl2va` | text only, or text + first/last frame |\n| `Ref2VA` | `ref2va` | text + omni references (images, video clips, audio clips) |\n\nSince vLLM-Omni [#5720](https://github.com/vllm-project/vllm-omni/pull/5720), serving\n`/path/to/MiniMax-H3` initializes both DiTs by default, while the Qwen3-VL encoder and\nvideo/audio VAEs stay shared. One server can therefore handle all three task types.\nAdd `--task-type fl2va` or `--task-type ref2va` only when the hardware profile needs to\nload one DiT to save GPU or host memory.\n\nComponents (BF16): two 52-block joint video/audio DiTs (66.3 GB each), a shared\nQwen3-VL layer-50 text/vision encoder (51.5 GB), a video VAE (~10 GB), and an audio\nVAE (~0.6 GB).\n\n## Model specifications\n\n| | |\n|---|---|\n| Output duration | 4–15 seconds |\n| Frame rate | 24 FPS (fixed) |\n| Audio | Native stereo, on every generation |\n| Resolution — 1440p (2K) | Short edge 1440 px for 16:9 … 9:16; wider formats ≈3.7 MP (e.g. 2976×1248 at 21:9) |\n| Resolution — 768p | Short edge 768 px for 16:9 … 9:16; wider formats ≈1 MP (e.g. 1536×672 at 21:9). Upscalable to 1440p. *(mode coming soon)* |\n| Aspect ratio | First/Last Frame follows the uploaded image. Text-to-Video and Omni Reference select from 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 — Omni Reference also offers Auto |\n| Prompt length | Up to 7,000 characters |\n\n### Input modes and limits\n\n**First/Last Frame** — 0, 1, or 2 images. Edge lengths in `[256, 5760]`, aspect ratio 5:2\nto 2:5. With no image, H3 falls back to Text-to-Video.\n\n**Omni Reference** — up to 9 images; up to 3 video clips (2–15 s each, 15 s total); up to\n3 audio clips (2–15 s each, 15 s total). Edge lengths in `[256, 5760]`, video aspect ratio\n5:2 to 2:5. **Audio must be paired with at least one image or video** — it cannot be the\nsole reference. Mixed inputs cap at 12 files total; with none, H3 falls back to\nText-to-Video.\n\n| | Formats | Per-file size |\n|---|---|---|\n| Video | H.264/AVC, H.265/HEVC (embedded audio AAC or MP3) | 50 MB |\n| Image | JPG, JPEG, PNG, WEBP, HEIC, HEIF | 30 MB |\n| Audio | WAV, MP3 | 15 MB |\n\nLimits are per file, not per combined upload. Keep the whole request body under 64 MB —\nprefer URL-based media over inlined uploads for anything large.\n\n## Prerequisites\n\nH3 can be served directly from the gated HF ID or from a local root directory. The local root contains both DiT\nsubdirectories plus the shared encoder and VAEs. Request access on the gated model card,\nthen download the complete repository:\n\n```bash\nhf download MiniMaxAI/MiniMax-H3 --local-dir /path/to/MiniMax-H3\n```\n\nThat yields `/path/to/MiniMax-H3/FL2VA`, `/path/to/MiniMax-H3/Ref2VA`, and the\nshared component directories. Serve `/path/to/MiniMax-H3` itself and substitute your own\n`--local-dir` throughout the commands below.\n\n`ffmpeg` and `ffprobe` must be on `PATH` — they are used for reference-video preparation\nand MP4 muxing.\n\n## Installation\n\n### Docker (recommended)\n\nThe image bundles H3 handlers and media dependencies. The published tag predates the\nmodular pipeline merged in vLLM-Omni #5720, so clone current `main` before starting:\n\n```bash\ndocker pull vllm/vllm-omni:minimax-h3\ngit clone --depth 1 https://github.com/vllm-project/vllm-omni.git /path/to/vllm-omni\n```\n\nThe command builder's Docker mode binds both the root checkpoint and source checkout,\nthen prepends the checkout to `PYTHONPATH`:\n\n```bash\n-v /path/to/MiniMax-H3:/path/to/MiniMax-H3:ro\n-v /path/to/vllm-omni:/path/to/vllm-omni:ro\n-e PYTHONPATH=/path/to/vllm-omni\n```\n\n### pip\n\nH3 support ships in vLLM-Omni rather than the `vllm` wheel, so the pip path needs a\ncurrent source checkout:\n\n```bash\nuv venv\nsource .venv/bin/activate\nuv pip install vllm==0.26.0\ngit clone --depth 1 https://github.com/vllm-project/vllm-omni.git /path/to/vllm-omni\ncd /path/to/vllm-omni\nuv pip install -e .\n```\n\nThe generated datacenter Blackwell route uses the default `TRTLLM_ATTN`; RTX PRO 5000 and the two-GPU RTX profiles use `CUDNN_ATTN`. These routes need no\nFlashAttention-4 install. Install the optional extra only when explicitly comparing FA4:\n`uv pip install -e '.[fa4]'`.\n\n## Launch — two 24/32 GB GPUs with distributed layerwise offload\n\nvLLM-Omni includes a low-memory TP2 path for H3. Install the current vLLM-Omni\nsource checkout as shown above.\n\nThe two-GPU profile combines TP2 with distributed layerwise offload (DLO). Each rank\nkeeps its rank-local TP shard in pinned host memory; `--dlo-no-use-allgather` streams\nthose shards directly instead of reconstructing full DiT blocks on every rank. A\nconfigurable prefix of DiT blocks stays resident for the complete denoise stage, then\nreleases its HBM before VAE decode.\n\nSelect the profile first. RTX 5090 uses 20 resident DiT layers at the released\n1344×768 shape; RTX 4090 keeps more HBM headroom with 12 resident layers and a\n1024×576 starting shape:\n\n```bash\n# 2× RTX 5090 (32 GB)\nexport DLO_RESIDENT_LAYERS=20 WIDTH=1344 HEIGHT=768\n\n# Or, 2× RTX 4090 (24 GB)\n# export DLO_RESIDENT_LAYERS=12 WIDTH=1024 HEIGHT=576\n```\n\nLoad only the FL2VA DiT on these memory-constrained profiles:\n\n```bash\nCUDA_VISIBLE_DEVICES=0,1 \\\nVLLM_WORKER_MULTIPROC_METHOD=spawn \\\nVLLM_OMNI_VIDEO_SYNC_TIMEOUT=14400 \\\nvllm serve /path/to/MiniMax-H3 \\\n --omni \\\n --task-type fl2va \\\n --host 0.0.0.0 \\\n --port 8000 \\\n --trust-remote-code \\\n --num-gpus 2 \\\n --tensor-parallel-size 2 \\\n --usp 1 \\\n --ring 1 \\\n --text-encoder-tp-size 2 \\\n --vae-patch-parallel-size 2 \\\n --vae-parallel-mode tile \\\n --vae-use-tiling \\\n --enable-distributed-layerwise-offload \\\n --dlo-no-use-allgather \\\n --dlo-resident-layers \"${DLO_RESIDENT_LAYERS}\" \\\n --enforce-eager \\\n --diffusion-attention-backend CUDNN_ATTN\n```\n\nThe resident count changes placement and transfer frequency only; it does not quantize\nor change the BF16/FP32 denoise math. Use a **384 GiB-class host** for the pinned model\nshards and offload buffers.\n\nWait for `Application startup complete`, then verify health and run one full 50-step\nT2VA request:\n\n```bash\ncurl --fail http://127.0.0.1:8000/health\n\ncurl --fail-with-body -sS \\\n -X POST http://127.0.0.1:8000/v1/videos/sync \\\n -F 'prompt=At night, three cats march into a bedroom playing tiny brass instruments, then abruptly file out, with synchronized room ambience.' \\\n -F \"width=${WIDTH}\" \\\n -F \"height=${HEIGHT}\" \\\n -F 'fps=24' \\\n -F 'num_inference_steps=50' \\\n -F 'flow_shift=12' \\\n -F 'seed=1101' \\\n -F 'extra_params={\"task\":\"t2va\",\"duration\":5.0,\"audio_flow_shift\":3.0}' \\\n -o minimax-h3-t2va.mp4\n\nffprobe -v error -show_entries \\\n stream=index,codec_name,width,height,r_frame_rate,sample_rate,channels \\\n -of json minimax-h3-t2va.mp4\nffmpeg -v error -i minimax-h3-t2va.mp4 \\\n -map 0:v:0 -map 0:a:0 -f null -\n```\n**Note:** If using 2× RTX 4090, the curl request must include -F 'aspect_ratio=16:9' to succeed.\n\nA successful output has H.264 video at 24 FPS and stereo AAC audio at 32 kHz, and the\nfinal `ffmpeg` command exits with status 0. This capacity profile intentionally loads one\nDiT. Restart the same root-model command with `--task-type ref2va` for Ref2VA; remove\n`--task-type` only after confirming that the combined modular service fits the target.\n\nThe same root path is used for both task families; only `--task-type` changes on these\ncapacity profiles.\n\n## Launch — four GPUs (validated best practice)\n\nOn B300/GB200, the no-offload root service uses Ulysses SP4, tiled VAE patch\nparallelism 4, regional `torch.compile`, dense BF16 `TRTLLM_ATTN`, and Ring/TP1. Both DiTs load\nonce while the encoder and VAEs remain shared.\n\n```bash\nCUDA_VISIBLE_DEVICES=0,1,2,3 \\\nFLASHINFER_DISABLE_VERSION_CHECK=1 \\\nVLLM_WORKER_MULTIPROC_METHOD=spawn \\\nVLLM_OMNI_VIDEO_SYNC_TIMEOUT=1800 \\\nvllm serve /path/to/MiniMax-H3 \\\n --omni \\\n --host 0.0.0.0 \\\n --port 8000 \\\n --trust-remote-code \\\n --num-gpus 4 \\\n --usp 4 \\\n --ring 1 \\\n --vae-patch-parallel-size 4 \\\n --vae-parallel-mode tile \\\n --vae-use-tiling\n```\n\nOmitting the attention flag is intentional: current datacenter Blackwell builds default to\ndense BF16 `TRTLLM_ATTN`. Install `[fa4]` and add `--diffusion-attention-backend FLASH_ATTN`\nonly for an explicit FA4 comparison.\n\n### Optional lossy attention: SAGE + Skip-Softmax\n\n`TRTLLM_ATTN` offers two **lossy** optimizations for the long main DiT attention sequence.\nBoth work under the pure Ulysses parallelism of the four-GPU profile (`--usp 4 --ring 1`) and\nare datacenter-Blackwell only. Append the following to the four-GPU command above to enable\nboth:\n\n```bash\n--diffusion-attention-config '{\n \"default\": {\n \"backend\": \"TRTLLM_ATTN\",\n \"quant\": {\"dtype_qk\": \"fp8_e4m3\", \"q_block_size\": 1, \"k_block_size\": 16},\n \"skip_softmax\": {\"threshold\": 0.05, \"disabled_until_timestep\": 0.97}\n },\n \"per_role\": {\n \"minimax_h3.token_refiner\": {\"backend\": \"TRTLLM_ATTN\"}\n }\n}'\n```\n\n- **SAGE** quantizes Q/K to `fp8_e4m3` for `QK^T`; P and V are always FP8 in this kernel.\n B200 additionally supports `int8` Q/K, which preserves accuracy better than FP8.\n- **Skip-Softmax** skips the Softmax and `PV` work of KV tiles whose scores fall far below\n the running row maximum. `threshold=0.05` with `disabled_until_timestep=0.97` is a\n **conservative** setting: a low threshold skips only clearly negligible tiles, and the\n cutoff keeps the early high-noise steps dense — H3's default video flow shift of 12 keeps\n the normalized timestep above `0.97` for the first 14 of 49 denoiser forwards at 50 steps.\n Raise `threshold` or lower `disabled_until_timestep` for more speedup once quality is\n verified.\n- The `per_role` entry keeps the short token-refiner attention dense; a per-role spec does\n not inherit `quant` or `skip_softmax` from `default`.\n\nBoth optimizations trade fidelity for speed, and their effects compound. The measured B300\nspeedup and LPIPS for each mode and for the combination are in the vLLM blog's\n[Quantized and Sparse Attention](https://vllm.ai/blog/2026-09-01-minimax-h3-production-serving#quantized-and-sparse-attention-in-trtllm_attn)\nsection as a reference; tune the settings according to the accuracy and speed required. See\nthe\n[TRTLLM attention guide](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/diffusion/attention_backends/trtllm/)\nfor the full configuration reference.\n\nNo restart is required: `extra_params.task` routes T2VA/FL2VA requests to the FL2VA\nDiT and Ref2VA requests to the Ref2VA DiT.\n\n### FastH3 model family\n\nFastH3 is a family of post-trained models based on MiniMax-H3. It generates\nvideo with stereo audio in four or eight steps. Choose a\nstarting point for your input and hardware:\n\n| Input | Hardware | Model |\n|---|---|---|\n| Prompt and reference image | RTX 5090, DGX Spark, RTX PRO 6000 Blackwell | [Omni NVFP4 QAD](https://huggingface.co/FastVideo/FastH3-Omni-NVFP4-QAD), single-card guide below |\n| Prompt and reference image | RTX 4090 | [Omni BF16](https://huggingface.co/FastVideo/FastVideo-FastH3-Omni-8-Step-V1) with FP8 enabled, single-card guide below |\n| Prompt and reference image | Eight GPUs | Omni BF16, eight-GPU guide below |\n| Prompt only | Eight GPUs | [V2](https://huggingface.co/FastVideo/FastVideo-FastH3-8-Step-V2) (experimental) or [four-step adapter](https://huggingface.co/FastVideo/FastVideo-FastH3-4-step-Preview-v1-LoRA) |\n\nThe command builder above serves native MiniMax-H3. Use the FastH3 setup\nand commands below for these models. Select one model when starting the server.\nThe single-card profiles are configuration guidance; this documentation change\ndoes not independently qualify them with GPU inference.\n\n#### Install FastH3\n\nUse Linux, Python 3.12, a CUDA 13-compatible NVIDIA driver, and\n[uv](https://docs.astral.sh/uv/getting-started/installation/). The eight-step\nmodels currently need the source branch from\n[vLLM-Omni #9167](https://github.com/vllm-project/vllm-omni/pull/9167):\n\n```bash\nsudo apt-get update\nsudo apt-get install -y git ffmpeg\n\ngit clone --branch pr/fasth3-omni-upstream https://github.com/lishunyang12/vllm-omni.git vllm-omni-fasth3\ncd vllm-omni-fasth3\nuv venv --python 3.12\nsource .venv/bin/activate\nuv pip install vllm==0.32.0 --torch-backend=cu130\nuv pip install -e .\n```\n\nOn DGX Spark, run in the native `aarch64` environment. If Hugging Face\nrequests access, accept the model's access terms and run `hf auth login`.\nRun the following server commands from the `vllm-omni-fasth3` directory.\n\n#### FastH3 RefOmni Single Card\n\n**RTX 5090 (32 GB), DGX Spark (128 GB), or RTX PRO 6000 Blackwell (96 GB):**\n\n```bash\nCUDA_VISIBLE_DEVICES=0 VLLM_WORKER_MULTIPROC_METHOD=spawn \\\nVLLM_OMNI_VIDEO_SYNC_TIMEOUT=7200 \\\nvllm serve FastVideo/FastH3-Omni-NVFP4-QAD --omni \\\n --config recipes/FastVideo/fasth3-omni-quantized.yaml\n```\n\nThis uses the smaller NVFP4 model and fast 8-layer video decoder. Layer\noffload reduces GPU memory use.\n\n**RTX 4090 (24 GB):**\n\n```bash\nuv pip install -e '.[vsa]'\n\nCUDA_VISIBLE_DEVICES=0 VLLM_WORKER_MULTIPROC_METHOD=spawn \\\nVLLM_OMNI_VIDEO_SYNC_TIMEOUT=7200 \\\nvllm serve FastVideo/FastVideo-FastH3-Omni-8-Step-V1 --omni \\\n --config recipes/FastVideo/fasth3-omni-rtx4090.yaml\n```\n\nThe first start downloads the model; the 4090 also converts eligible\nweights to FP8 while loading. Later starts reuse the download cache.\nKeep the terminal open and wait for `Application startup complete`.\n\n**Generate.** Save your image as `reference.png`. In a second terminal:\n\n```bash\ncurl --fail-with-body -sS http://localhost:8000/v1/videos/sync \\\n -F 'prompt=The person in the reference image smiles and waves at the camera. Birds chirp as the person says, \"Welcome to the garden!\"' \\\n -F 'input_reference=@reference.png' \\\n -F 'size=832x480' -F 'seconds=5' -F 'seed=1234' \\\n -o output.mp4\n```\n\nOpen `output.mp4` to play the video with stereo audio. For 768P, change\n`size=832x480` to `size=1344x768`. If memory is tight, start at 480P and close\nother GPU workloads. For multiple images, video, or audio references, see\nthe [H3 reference API](https://github.com/lishunyang12/vllm-omni/blob/pr/fasth3-omni-upstream/recipes/MiniMaxAI/MiniMax-H3.md).\n\n**Optional settings:**\n\n- **FP8 model:** if you have access to [FastH3-Omni-FP8](https://huggingface.co/FastVideo/FastH3-Omni-FP8),\n replace the model ID in the Blackwell command with `FastVideo/FastH3-Omni-FP8`.\n A local model directory also works. This release also requires Blackwell\n because its text encoder uses NVFP4.\n- **36-layer decoder:** in `recipes/FastVideo/fasth3-omni-quantized.yaml`, change\n `additional-config.video_vae_decoder.subfolder` from `fast-8L` to\n `quality-36L`, then restart. Both decoders come from\n [FastH3-NVFP4-VAE-Decoder](https://huggingface.co/FastVideo/FastH3-NVFP4-VAE-Decoder).\n- **DGX Spark:** remove `diffusion-offload-config` from the Blackwell YAML to\n keep the model resident in unified memory and avoid offload transfers.\n\n#### FastH3 Omni on eight GPUs\n\nInstall the attention kernels, then start the server:\n\n```bash\nuv pip install -e '.[cudnn-bsa]'\n\nVLLM_WORKER_MULTIPROC_METHOD=spawn VLLM_OMNI_VIDEO_SYNC_TIMEOUT=7200 \\\nvllm serve FastVideo/FastVideo-FastH3-Omni-8-Step-V1 --omni \\\n --config recipes/FastVideo/fasth3-8step-8gpu.yaml\n```\n\nWait for `Application startup complete`, then use the image-and-prompt request\nabove. The configuration sets eight inference steps and handles GPU placement.\n\nFor an NVFP4 video decoder on Blackwell, add this to the deployment YAML:\n\n```yaml\nadditional-config:\n video_vae_decoder:\n model: FastVideo/FastH3-NVFP4-VAE-Decoder\n subfolder: fast-8L\n```\n\nUse `quality-36L` for the deeper decoder, then restart the server.\n\n**Performance reference: eight RTX PRO 5000 Blackwell 72 GB GPUs.**\nBF16, 1344×768, one request at a time; timing includes MP4 encoding and\nexcludes model loading:\n\n| Output | Generation time | Reported allocator peak |\n|---|---:|---:|\n| 124 frames, about 5 seconds | 41.04 s, median of 3 runs | 35.15 GiB |\n| 345 frames, about 14 seconds | 95.93 s, 1 run | 38.94 GiB |\n\nThese are offline measurements. See the\n[benchmark details](https://github.com/lishunyang12/vllm-omni/pull/63)\nfor the measured environment and configuration.\n\n#### FastH3 V2: text to video and audio\n\nThis eight-GPU deployment is experimental. Install the `cudnn-bsa` extra\nabove, then start V2 in place of the Omni server:\n\n```bash\nVLLM_WORKER_MULTIPROC_METHOD=spawn VLLM_OMNI_VIDEO_SYNC_TIMEOUT=7200 \\\nvllm serve FastVideo/FastVideo-FastH3-8-Step-V2 --omni \\\n --config recipes/FastVideo/fasth3-8step-8gpu.yaml\n```\n\nWait for startup, then send a text-only request in a second terminal:\n\n```bash\ncurl --fail-with-body -sS http://localhost:8000/v1/videos/sync \\\n -F 'prompt=A train crosses a stone bridge at sunrise, with rhythmic wheels and distant birdsong.' \\\n -F 'size=1344x768' -F 'seconds=5' \\\n -o fasth3-v2.mp4\n```\n\nKeep the model's default eight steps and sampling settings.\n\n### FastH3 four-step Dense and VSA adapters\n\nUse the four-step adapter for text-to-video generation on eight GPUs.\nChoose the adapter at startup; per-request switching and CPU/layer offload\nare unsupported. Download the Dense and VSA adapters:\n\n```bash\nhf download FastVideo/FastVideo-FastH3-4-step-Preview-v1-LoRA \\\n dense-datafree/adapter_model.safetensors \\\n vsa-datafree/adapter_model.safetensors \\\n --local-dir ./FastH3-LoRA\n```\n\nStart with the Dense adapter:\n\n```bash\nCUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 \\\nVLLM_WORKER_MULTIPROC_METHOD=spawn VLLM_OMNI_VIDEO_SYNC_TIMEOUT=1800 \\\nvllm serve MiniMaxAI/MiniMax-H3 --omni \\\n --host 127.0.0.1 --port 8095 --trust-remote-code \\\n --task-type fl2va --served-model-name FastH3 \\\n --num-gpus 8 --tensor-parallel-size 1 --usp 8 --ring 1 \\\n --vae-patch-parallel-size 8 --vae-parallel-mode tile --vae-use-tiling \\\n --diffusion-attention-config.default.backend FLASH_ATTN \\\n --lora-path ./FastH3-LoRA/dense-datafree/adapter_model.safetensors\n```\n\nFor the VSA adapter, install `uv pip install -e '.[vsa]'`, change `--lora-path`\nto `./FastH3-LoRA/vsa-datafree/adapter_model.safetensors`, and replace the\nattention option with:\n\n```bash\n--diffusion-attention-config.default.backend FASTVIDEO_VSA \\\n--diffusion-attention-config.default.fastvideo_vsa_topk 64\n```\n\nKeep pure Ulysses parallelism (`--usp 8 --ring 1`) for VSA. See\n[backend selection](https://github.com/lishunyang12/vllm-omni/blob/pr/fasth3-omni-upstream/recipes/FastVideo/FastH3.md#hardware-and-backend-selection)\nfor hardware requirements.\n\nAfter the server starts, generate a video in a second terminal:\n\n```bash\ncurl --fail-with-body -sS http://127.0.0.1:8095/v1/videos/sync \\\n -F 'model=FastH3' \\\n -F 'prompt=A cinematic starship glides through a luminous nebula while its engines hum and distant radio chatter fills the cabin.' \\\n -F 'width=1344' -F 'height=768' -F 'aspect_ratio=16:9' -F 'fps=24' \\\n -F 'num_inference_steps=4' -F 'guidance_scale=1' -F 'seed=1101' \\\n -F 'extra_params={\"task\":\"t2va\",\"duration\":10.0}' \\\n -o fasth3.mp4\n```\n\nUse four steps and `task=t2va`; keep the default sampling settings.\n\n**Performance reference: eight B300 GPUs.** At 1344×768 and 24 FPS,\nserver generation time including MP4 encoding was:\n\n| Output duration | Dense (TRTLLM) | VSA |\n|---|---:|---:|\n| 10 seconds | 9.84 s | 7.28 s |\n| 15 seconds | 14.20 s | 10.80 s |\n\nSee [benchmark details](https://github.com/vllm-project/vllm-omni/pull/6909)\nfor the measured environment and configuration.\n\n### LightX2V Turbo few-step LoRA\n\n[LightX2V Turbo](https://huggingface.co/lightx2v/Minimax-h3-Turbo) is a family of\nfew-step LoRA artifacts for H3. It reaches the same goal as FastH3 by the opposite\nroute: instead of fusing full-rank deltas at startup, Turbo stays a standard LoRA that\neach request activates by name. One server can therefore hold several artifacts and let\nrequests choose between them, at the cost of the LoRA matmuls on every denoise step.\n\nEight Diffusers-layout artifacts are supported. The filename is the contract — the server\nparses the task family, step count and resolution out of it, so a renamed file is rejected\nrather than served on a guess. `audio_flow_shift` is `3.0` across the family.\n\n| Artifact | Tasks | `num_inference_steps` | `flow_shift` | alpha |\n|---|---|---:|---:|---:|\n| `minimax_h3_fl2v_turbo_4step_v0.1.safetensors` | T2VA / FL2VA | 5 | 12 | none → 8 |\n| `minimax_h3_fl2v_turbo_4step_v1.0_768p_bf16.safetensors` | T2VA / FL2VA | 5 | 6 | 128 |\n| `minimax_h3_fl2v_turbo_4step_v1.1_768p_bf16.safetensors` | T2VA / FL2VA | 5 | 6 | 128 |\n| `minimax_h3_fl2v_turbo_4step_v1.2_768p_bf16.safetensors` | T2VA / FL2VA | 5 | 6 | 8 |\n| `minimax_h3_fl2v_turbo_8step_v1.0_bf16.safetensors` | T2VA / FL2VA | 9 | 12 | 8 |\n| `minimax_h3_fl2v_turbo_8step_v1.0_768p_bf16.safetensors` | T2VA / FL2VA | 9 | 6 | 8 |\n| `minimax_h3_ref2v_turbo_4step_v0.1_bf16.safetensors` | Ref2VA | 5 | 12 | 8 |\n| `minimax_h3_ref2v_turbo_8step_v1.0_768p_bf16.safetensors` | Ref2VA | 9 | 6 | 8 |\n\nRequested sigma points are always one more than the artifact's forwards, which is why a\nfour-step Turbo artifact takes `num_inference_steps=5` where FastH3 takes `4`.\n\nEvery artifact is rank 128 and the delta is applied at `scale * alpha / 128`, with alpha\nread from the artifact's metadata — only `4step_v0.1` declares none and falls back to 8\nwith a warning.\n\nDownload one artifact under the H3 root so the existing bind mount includes it. Each\nartifact except `4step_v0.1` also ships a `_comfyui_` export that fuses Q/K/V into a single\nprojection; those are **not** supported and are refused by name.\n\n```bash\nhf download lightx2v/Minimax-h3-Turbo \\\n minimax_h3_fl2v_turbo_4step_v1.2_768p_bf16.safetensors \\\n --local-dir /path/to/MiniMax-H3/Turbo-LoRA\n```\n\nServe it on the same eight-GPU pure-Ulysses topology. `--lora-path` preloads the adapter;\nit accepts one artifact, or a directory holding exactly one — a directory with several\nrecognized artifacts is rejected as ambiguous.\n\n```bash\nCUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 \\\nVLLM_WORKER_MULTIPROC_METHOD=spawn \\\nVLLM_OMNI_VIDEO_SYNC_TIMEOUT=1800 \\\nvllm serve /path/to/MiniMax-H3 \\\n --omni \\\n --host 127.0.0.1 \\\n --port 8095 \\\n --trust-remote-code \\\n --task-type fl2va \\\n --served-model-name MiniMaxAI/MiniMax-H3 \\\n --num-gpus 8 \\\n --usp 8 \\\n --ring 1 \\\n --vae-patch-parallel-size 8 \\\n --vae-parallel-mode tile \\\n --vae-use-tiling \\\n --diffusion-attention-backend TRTLLM_ATTN \\\n --lora-backend peft \\\n --lora-path /path/to/MiniMax-H3/Turbo-LoRA/minimax_h3_fl2v_turbo_4step_v1.2_768p_bf16.safetensors\n```\n\nUnlike FastH3, the request must activate the adapter and carry that row's sampling\ncontract. A request whose steps or shift do not match the loaded artifact is rejected, so\na mismatch cannot silently sample the distilled model at noise levels it never saw.\n\n```bash\ncurl --fail-with-body -sS -X POST http://127.0.0.1:8095/v1/videos/sync \\\n -F 'prompt=A cinematic starship glides through a luminous nebula while its engines hum and distant radio chatter fills the cabin.' \\\n -F 'width=1344' \\\n -F 'height=768' \\\n -F 'aspect_ratio=16:9' \\\n -F 'fps=24' \\\n -F 'num_inference_steps=5' \\\n -F 'flow_shift=6' \\\n -F 'seed=1101' \\\n -F 'extra_params={\"task\":\"t2va\",\"duration\":10.0,\"audio_flow_shift\":3.0}' \\\n -F 'lora={\"name\":\"h3-turbo-v1.2\",\"path\":\"/path/to/MiniMax-H3/Turbo-LoRA/minimax_h3_fl2v_turbo_4step_v1.2_768p_bf16.safetensors\",\"scale\":1.0}' \\\n -o turbo.mp4\n```\n\nFL2VA artifacts serve `t2va` and `fl2va` on an FL2VA or combined server. The two `ref2v`\nrows need `--task-type ref2va`: a combined server answers `ref2va` from a second DiT the\nadapter cannot bind to, so loading one there is refused rather than running an undistilled\nmodel on a few-step ladder. The integration is dynamic-only — no prefusion, no LoRA\ncomposition. DLO works by keeping the request-switchable LoRA A/B buffers resident on the\naccelerator while DLO streams the base blocks; model-level and standard layerwise offload\nremain unsupported.\n\nMeasured on 8×B300 with the command above, at 1344×768, 24 FPS, a 15 s FL2VA request with\nfirst and last keyframes (362 frames), fixed seed, one discarded warmup and three recorded\nruns. The baseline is the same server without an adapter at `num_inference_steps=50` and\n`flow_shift=12`:\n\n| Metric | Base H3, 49 forwards | Turbo v1.2, 4 forwards | Speedup |\n|---|---:|---:|---:|\n| Denoise loop | ~105 s | ~9 s | 11.7× |\n| Per denoise step | 2.14–2.16 s/it | 2.20–2.42 s/it | — |\n| Diffusion engine | 111.1–111.3 s | 15.0–15.1 s | 7.4× |\n| Server E2E incl. MP4 | 112.5–112.9 s | ~16.5 s | 6.8× |\n\nThe ~10% higher per-step cost is the LoRA matmul the fused FastH3 route does not pay —\nirrelevant against a 12× cut in forwards, but the reason a single-artifact deployment can\nstill prefer a fused student.\n\nThese figures are for a server serving Turbo requests back to back. Alternating between\nTurbo and adapter-free requests on one server additionally pays a LoRA rebind on each\nswitch — measured at about 24 s per switch in the same run (39.2 s diffusion engine against\n15.1 s steady state), because every one of H3's 208 LoRA layers is torn down and re-uploaded.\nGive Turbo its own process if the workload mixes, or track vLLM-Omni #7195, which removes\nthat rebind.\n\n### RTX PRO 5000 Blackwell — four PCIe GPUs\n\nSelect the `RTX PRO 5000 Blackwell 4x` hardware profile for the validated BF16,\nno-offload topology: TP2 × Ulysses2, Ring1, text-encoder TP4, VAE patch parallel 4\nin tile mode, and `CUDNN_ATTN`. On the measured dual-socket host,\n`CUDA_VISIBLE_DEVICES=0,2,1,3` kept the TP pairs on local PXB paths; check\n`nvidia-smi topo -m` and adapt the order on other systems.\n\nThis 72 GiB/GPU profile serves the root path but selects one DiT with `--task-type`.\nThe task picker adds `fl2va` for T2VA/FL2VA and `ref2va` for Ref2VA; loading both DiTs\ntogether is not qualified on this memory-constrained profile.\n\nA five-step topology screen after warmup produced decodable H.264 video with stereo AAC:\n\n| Workload | Client E2E | Encode | Denoise | VAE decode | Peak/GPU |\n|---|---:|---:|---:|---:|---:|\n| T2VA, 124 frames, 1344×768 | 32.993 s | 0.034 s | 27.915 s | 4.307 s | 67.6 GiB |\n| FL2VA first frame, same output shape | 30.130 s | 0.276 s | 24.396 s | 4.339 s | 67.6 GiB |\n\nThese are topology-screening results, not 50-step throughput claims. Nsight Systems\naggregation for the same run was:\n\n| Workload | AllGather | Send/Recv | NCCL other | NCCL total | Dense FMHA | max-min/mean |\n|---|---:|---:|---:|---:|---:|---:|\n| T2VA | 0.93% | 8.53% | 14.63% | 24.09% | 31.15% | 1.11% |\n| FL2VA | 0.89% | 7.26% | 15.76% | 23.91% | 32.53% | 0.13% |\n\n`NCCL other` covers NCCL kernels outside recognized AllGather and point-to-point\nSend/Recv, including AllReduce, ReduceScatter, or Broadcast when present.\n\n### AMD ROCm — four MI300X GPUs\n\nVerified on 4× AMD Instinct MI300X (gfx942) with the ROCm H3 image, AITER packed\nvariable-length attention, Ulysses 4, text-encoder TP4, and native tiled VAE patch\nparallelism 4:\n\n```bash\ndocker pull vllm/vllm-omni-rocm:minimax-h3\n\nHIP_VISIBLE_DEVICES=0,1,2,3 \\\nVLLM_ROCM_USE_AITER=1 \\\nVLLM_WORKER_MULTIPROC_METHOD=spawn \\\nVLLM_OMNI_VIDEO_SYNC_TIMEOUT=1800 \\\nvllm serve /path/to/MiniMax-H3 \\\n --omni \\\n --host 0.0.0.0 \\\n --port 8000 \\\n --trust-remote-code \\\n --num-gpus 4 \\\n --usp 4 \\\n --ring 1 \\\n --text-encoder-tp-size 4 \\\n --vae-patch-parallel-size 4 \\\n --vae-parallel-mode tile \\\n --vae-use-tiling \\\n --diffusion-attention-backend FLASH_ATTN\n```\n\nOn ROCm, `FLASH_ATTN` resolves to AITER on supported Instinct architectures. Do not\ninstall the CUDA-only `[fa4]` extra or set `FLASHINFER_DISABLE_VERSION_CHECK`.\n\nThe refreshed `vllm/vllm-omni-rocm:minimax-h3` tag includes the Ref2VA soundfile\nfallback, TorchCodec, and FFmpeg, so T2VA, FL2VA, and the complete Ref2VA path use the\nsame official image.\n\n### AMD ROCm — four MI355X GPUs\n\nVerified on 4× AMD Instinct MI355X. The official ROCm image includes the\nMiniMax H3 Ref2VA fixes, TorchCodec, and FFmpeg. We tested both Ulysses 4 with Ring 1\nand Ulysses 1 with Ring 4. The command below shows the Ulysses 4 / Ring 1 configuration\nwith tiled VAE patch parallelism degree 4, AITER, and CPU offload:\n```bash\ndocker pull vllm/vllm-omni-rocm:minimax-h3\n\nHIP_VISIBLE_DEVICES=0,1,2,3 \\\nVLLM_ROCM_USE_AITER=1 \\\nVLLM_WORKER_MULTIPROC_METHOD=spawn \\\nVLLM_OMNI_VIDEO_SYNC_TIMEOUT=1800 \\\nvllm serve /path/to/MiniMax-H3 \\\n --omni \\\n --host 0.0.0.0 \\\n --port 8000 \\\n --trust-remote-code \\\n --num-gpus 4 \\\n --usp 4 \\\n --ring 1 \\\n --vae-patch-parallel-size 4 \\\n --vae-parallel-mode tile \\\n --vae-use-tiling \\\n --enable-cpu-offload \\\n --text-encoder-tp-size 4\n```\n\nThis root-model command accepts T2VA, FL2VA, and Ref2VA requests without restarting.\n\nThree constraints on this configuration:\n\n- **Do not add `--enforce-eager`.** Regional compile is the default\n (`--diffusion-compile-granularity regional`) and is worth ~9.5%. The first request\n includes compilation — warm the server once before measuring steady state.\n- **`--cfg-parallel-size` must stay 1.** H3 is CFG-distilled and has no negative branch;\n anything greater is rejected with an explicit error rather than silently duplicating a\n branch that does not exist.\n- **The VAE supports its native `tile` mode only** — not `spatial_shard_width` or\n `spatial_shard_height` (those belong to the distributed Wan autoencoder). Patch\n parallel size must be 1 or the full DiT group size.\n\n## Launch — single GPU (accuracy and memory first)\n\nModel-level CPU offload keeps the Qwen3-VL encoder and the DiT from being resident\nsimultaneously. This is the accuracy-qualified reference path; it trades PCIe/NVLink\ntransfer latency for a much smaller GPU footprint, and needs enough system RAM for the\noffloaded components.\n\n```bash\nCUDA_VISIBLE_DEVICES=0 \\\nVLLM_WORKER_MULTIPROC_METHOD=spawn \\\nVLLM_OMNI_VIDEO_SYNC_TIMEOUT=1800 \\\nvllm serve /path/to/MiniMax-H3 \\\n --omni \\\n --task-type fl2va \\\n --host 0.0.0.0 \\\n --port 8000 \\\n --trust-remote-code \\\n --num-gpus 1 \\\n --enable-cpu-offload \\\n --diffusion-attention-backend FLASH_ATTN\n```\n\n## Launch — DGX Spark (GB10, 128 GB unified memory)\n\nGB10 is a **unified-memory** platform: the 128 GB LPDDR5X (≈121 GiB usable) is shared by\nCPU and GPU, so both offload strategies used elsewhere in this recipe stop being capacity\nlevers. `--enable-cpu-offload` and distributed layerwise offload move weights from \"VRAM\"\nto \"host RAM\", which is the same physical pool here — nothing is freed. DLO is actively\nharmful: staging rank-local shards into pinned host memory creates a second copy\nalongside the resident one, and the process is killed by the OOM killer (`Exit code: -9`)\nright after `Enabling offloader backend`.\n\nOne partition on disk is 135 GiB in BF16:\n\n| Component | Size | Quantized by `--quantization fp8` |\n|---|---:|---|\n| `text_encoder` (Qwen3-VL) | 63 GiB | no |\n| `transformer` (DiT) | 62 GiB | yes |\n| `video_vae` | 9.8 GiB | no |\n| `audio_vae` | 0.6 GiB | no |\n\n135 GiB does not fit in 121 GiB, so **FP8 is mandatory** and only one DiT can be\nresident — always pass `--task-type fl2va` or `--task-type ref2va`. Online FP8 touches\nthe DiT only, bringing the partition to roughly 104 GiB before activations.\n\nWeight quantization runs at load time and is slow on this platform; `--init-timeout 3600`\nkeeps startup from being cut short.\n\n```bash\nCUDA_VISIBLE_DEVICES=0 \\\nFLASHINFER_DISABLE_VERSION_CHECK=1 \\\nVLLM_WORKER_MULTIPROC_METHOD=spawn \\\nVLLM_OMNI_VIDEO_SYNC_TIMEOUT=7200 \\\nvllm serve /path/to/MiniMax-H3 \\\n --omni \\\n --task-type fl2va \\\n --host 0.0.0.0 \\\n --port 8000 \\\n --trust-remote-code \\\n --init-timeout 3600 \\\n --num-gpus 1 \\\n --usp 1 \\\n --ring 1 \\\n --quantization fp8 \\\n --vae-patch-parallel-size 1 \\\n --vae-parallel-mode tile \\\n --vae-use-tiling \\\n --enforce-eager \\\n --diffusion-attention-backend CUDNN_ATTN\n```\n\nRestart with `--task-type ref2va` to serve the Ref2VA family. Keep requests at a 576 px\nshort edge (1024×576) and 5 s duration as the starting shape; GB10 has one GPU and no\nparallelism headroom, so wall-clock per request is far higher than the multi-GPU profiles\nabove.\n\n## Launch — single Ascend 950PR NPU (INT8)\n\nvLLM-Omni serves H3 on Ascend through the `vllm-ascend` platform plugin, on a\nCPU-only aarch64 PyTorch build with `torch_npu` — no CUDA runtime is present.\nOne 950PR holds a single DiT partition, so this profile serves the `FL2VA`\ndirectory and uses online INT8 in place of the sharding levers the multi-GPU\nprofiles rely on.\n\nThree Ascend-specific constraints come before the command:\n\n- **Attention backend.** `CUDNN_ATTN`, `FLASHINFER_ATTN`, `TRTLLM_ATTN`, and the\nSageAttention backends are CUDA-only; selecting one on NPU fails with a\n`NotImplementedError` out of `forward_npu`. The NPU platform default resolves\nto `FLASH_ATTN` when MindIE-SD is installed and `TORCH_SDPA` otherwise, and\n`FLASH_ATTN` is where H3's NPU memory work lives: a mask-free packed varlen\npath that never materializes the quadratic padding mask, plus K/V prefix\nslicing. Install MindIE-SD *before* passing\n`--diffusion-attention-backend FLASH_ATTN` — the backend imports `mindiesd`\nlazily and otherwise raises `ImportError` at the first denoise step. Once\ninstalled the platform default picks it up on its own.\n- **Shared memory.** Decoded video crosses the diffusion-worker process boundary\nthrough POSIX shared memory — roughly 0.9 GiB for a 5 s 1024×576 clip. The\n64 MiB Docker default is large enough for the control-plane queues, so the\nserver starts and the denoise loop reaches 100% before the write into\n`/dev/shm` raises SIGBUS and kills the worker with `Bus error (core dumped)`.\nCheck `df -h /dev/shm` and start the container with `--shm-size=8g` or\n`--ipc=host`. It cannot be changed on a running container, and an in-container\n`mount -o remount` needs `CAP_SYS_ADMIN`.\n- **No `--enforce-eager`.** It disables regional compilation and only slows the\nsteady state; the first request is a warmup either way. `--cfg-parallel-size`\nmust stay 1, as everywhere else in this recipe.\n\n```bash\nASCEND_RT_VISIBLE_DEVICES=0 \\\nVLLM_WORKER_MULTIPROC_METHOD=spawn \\\nVLLM_OMNI_VIDEO_SYNC_TIMEOUT=14400 \\\nvllm serve /path/to/MiniMax-H3/FL2VA \\\n --omni \\\n --host 0.0.0.0 \\\n --port 8000 \\\n --trust-remote-code \\\n --num-gpus 1 \\\n --tensor-parallel-size 1 \\\n --usp 1 \\\n --ring 1 \\\n --text-encoder-tp-size 1 \\\n --vae-patch-parallel-size 1 \\\n --vae-parallel-mode tile \\\n --vae-use-tiling \\\n --init-timeout 14400 \\\n --stage-init-timeout 14400 \\\n --quantization int8\n```\n\n## Text-encoder tensor parallelism\n\nBy default the whole Qwen3-VL encoder is resident on the DiT main rank, making it the\npeak-memory hotspot on multi-GPU no-offload runs. `--text-encoder-tp-size N` shards it\nacross the first `N` DiT ranks using vLLM-style tensor-parallel layers on a dedicated\nencoder process group:\n\n```bash\nvllm serve /path/to/MiniMax-H3 \\\n --omni --trust-remote-code \\\n --task-type fl2va \\\n --num-gpus 4 --usp 4 --ring 1 \\\n --text-encoder-tp-size 4 \\\n --vae-patch-parallel-size 4 --vae-parallel-mode tile --vae-use-tiling\n```\n\n- `N` must divide the Qwen3-VL head counts (64 attention heads / 8 KV heads) → 1, 2, 4 on\n a 4-GPU server; 1, 2, 4, 8 on 8 GPUs.\n- On 4 GPUs, `N=4` drops the per-rank engine peak from **133 GB to 103 GB** (~35.7 GB) at\n no measurable throughput cost, while each non-main rank gains ~51.5/N GB.\n- Numerically: `N=1` reproduces the HF reference path bit-exactly (`max_abs = 0`); `N=4`\n introduces bounded BF16 rounding only (row-parallel all-reduce in FP32), giving\n 31.11 dB PSNR / 0.9566 SSIM end-to-end against `N=1` with identical structure.\n- Combining `N>1` with regional compile used to produce a `ValueError: v must be finite`\n on the *second* request. That is fixed — the token refiner's attention runs on\n replicated rows before `sp_prepare` and was wrongly getting a Ulysses SP all-to-all.\n\n## Key request parameters\n\n| Parameter | Recommended | Notes |\n|---|---|---|\n| `task` | `t2va`, `fl2va`, `ref2va` | Passed inside `extra_params`; must be compatible with `--task-type` when one is set |\n| `duration` | 4–15 s | Decimal seconds in `extra_params`; snapped to H3's legal `17n+5` frame count (15 s → 362 frames / 15.083 s) |\n| `fps` | `24` | Output FPS is fixed |\n| `num_inference_steps` | `50` | Matches the reference accuracy workloads |\n| `flow_shift` | `12` | Video sigma shift |\n| `audio_flow_shift` | `3` | Audio sigma shift, in `extra_params` |\n| `width`, `height` | see below | Server-side validation: multiples of 32, aspect ratio 1:4 to 4:1 |\n| `seed` | fixed value | Output is deterministic per request at a fixed seed |\n\nOn `width`/`height`, the serving-side check is broader than the documented product modes —\npick a **short edge of 768 or 1440** in one of the supported ratios (21:9, 16:9, 4:3, 1:1,\n3:4, 9:16) to stay on shapes the model was trained and validated for. FL2VA can omit both\nand inherit the first frame's aspect ratio at a 768 px short edge. Prompts cap at 7,000\ncharacters.\n\nUse `POST /v1/videos/sync` when you want the MP4 in the response body; `POST /v1/videos`\nis the async job-polling variant.\n\n## Validated performance (4×B300)\n\nThese measurements used task-specific single-DiT processes before the modular\ncombined-service merge; they remain the validated per-task operating points.\n\n| Workload | Config | Result |\n|---|---|---|\n| FL2VA, 209 frames, 1248×768 (8.7 s) | no offload, U4, VPP4 tile, regional compile | **86.96 s** client E2E (±0.23 s) |\n| Two-video Ref2VA, 362 frames, 1344×768 (15 s) | same | **784.4 s** accounted model-stage mean |\n\nStage split for the FL2VA case: text encoder 0.21 s, visual encoder 0.20 s, DiT 79.1 s\n(**88%** of the request), video+audio VAE decode 2.40 s. VAE patch parallelism is the\ncheapest win available — it cuts decode 3.4–3.5× (8.24 s → 2.40 s).\n\n### Validated performance (4×MI300X)\n\nMeasured with `vllm/vllm-omni-rocm:minimax-h3`\n(`sha256:29d1946af9c69e3e0a7128c247bdc8c82437ead43fbc366fed443533cf6ce9e8`),\nBF16, AITER, U4, text-encoder TP4, VPP4 tile, regional compile, one warmup, and\nthe synchronous Video API:\n\n| Workload | Model stages | Client E2E |\n|---|---:|---:|\n| T2VA, 209 frames, 1344×768 (8.7 s) | encode 0.09 s, denoise 244.04 s, decode 4.15 s | **267.42 s** |\n| FL2VA, 209 frames, 1344×768 (8.7 s) | encode 13.98 s, denoise 257.58 s, decode 4.11 s | **287.07 s** |\n\nBoth outputs were validated as 209-frame H.264 at 24 FPS with 32 kHz stereo AAC.\nA v0.26.0 source build additionally completed image+audio and video-reference Ref2VA,\nplus a 2048×1088 T2VA run. These measurements describe tested shapes, not a general\nlatency guarantee.\n\nA `with_stack` profile of the two-video Ref2VA case shows the pipeline is\n**GPU-attention-bound, not host-starved**: FlashAttention-4 is ~76% of `diffuse` device\ntime, Ulysses send/recv is secondary, GPU utilization is 92.8–94.3% and the CPU-idle\nunion inside the transformer forwards is 3.15%. Reducing DiT time further needs a change\nin attention cost, which is not lossless;\n[SAGE + Skip-Softmax](#optional-lossy-attention-sage--skip-softmax) above is the supported\nway to trade attention precision and sparsity for speed on datacenter Blackwell.\n\nAgainst the checkpoint's own reference implementation, the accuracy-qualified path scores\nSSIM 0.9873–0.9896, PSNR 39–42 dB, pixel cosine 0.9996+, and audio log-mel cosine\n0.977–0.996 on T2VA/FL2VA. The two-video Ref2VA composite scores lower on raw pixels\n(SSIM 0.628) largely because of H.264 bitrate differences, while CLIP cosine is 0.9816 and\naudio log-mel cosine 0.9869 — content and motion stay aligned.\n\n### Cache-DiT\n\nOpt-in only. A 50-step T2VA probe cut denoise time **30.2%** (121.01 s → 84.47 s) but\ndropped SSIM to **0.831** against the uncached output. H3's video trajectory is sensitive\nto cached denoise steps — choose the cache budget against your own quality target.\n\n### Offload and accuracy\n\nOn a **single GPU**, model-level CPU offload is the accuracy-qualified path. On four GPUs,\nno-offload is both faster and accuracy-clean once the encoder stays resident: an earlier\nno-offload build performed a ~63 GiB DiT GPU→CPU→GPU round trip inside `encode_prompt`,\nwhich was pure overhead (encoder 30.38 s → 0.207 s once removed, ~146×).\n\n## Known limitations\n\n- The modular root service loads both DiTs by default. Capacity profiles use\n `--task-type fl2va` or `--task-type ref2va` and expose only that task family.\n- H3 executes **one generation request per diffusion batch** today.\n- The first request is a compile warmup only on the resident regional-compile profiles.\n The two-GPU DLO recipes use `--enforce-eager` and do not compile the DiT.\n- **The serving path accepts fewer references than the model supports.** H3 documents up\n to 9 images, 3 video clips, and 3 audio clips (12 files) per Omni Reference request;\n the current vLLM-Omni path takes exactly one image plus one audio reference, **or** one\n or more videos with **no** separate `audio_reference` (it uses the source soundtracks).\n- The 768 px short-edge mode is available for T2VA and FL2VA; 1344×768 is the documented\n 16:9 request shape. The 24 GB DLO recipe uses 1024×576 as its lower-memory starting\n point.\n- `--cfg-parallel-size > 1` is rejected by design (CFG-distilled, no negative branch).\n- The VAE supports the native `tile` parallel mode only.\n- A `U2 × Ring2` hybrid currently fails with an attention-mask length mismatch; use pure\n Ulysses.\n- FastH3 preview v1 serves T2VA only, is fused at startup, and cannot use model-level,\n layerwise, or distributed layerwise offload. Its VSA variants additionally require CUDA,\n `fastvideo-kernel`, `FASTVIDEO_VSA`, and pure local/Ulysses attention; Ring and AllGather\n sequence parallelism are rejected.\n- Online FP8 quantizes the DiT only — the Qwen3-VL text encoder and both VAEs stay\n BF16. It is incompatible with layerwise offload, whose weight stride is rejected by\n the Cutlass FP8 kernel.\n- On unified-memory platforms (DGX Spark / GB10) CPU offload and DLO give no capacity\n benefit, because host RAM and VRAM are one pool; DLO additionally doubles peak usage\n while staging. Use resident FP8 with a single `--task-type` partition instead.\n- Pure Ulysses still replicates the 66.3 GB DiT on every rank, so 64 GB GPUs cannot use\n `--usp N --tp 1` as a resident capacity path. Use DiT TP plus DLO (the two-GPU recipes\n above), or model-level CPU offload; text-encoder TP alone is not sufficient.\n- DLO is a capacity path, not a free speedup: it needs substantial host RAM and streams\n weights over PCIe on every denoise step. Increase `--dlo-resident-layers` only after\n checking peak HBM on the exact request shape.\n\n## References\n\n- [Model card](https://huggingface.co/MiniMaxAI/MiniMax-H3)\n- [Modular FL2VA/Ref2VA pipeline (vLLM-Omni #5720)](https://github.com/vllm-project/vllm-omni/pull/5720)\n- [vLLM-Omni Video API](https://docs.vllm.ai/projects/vllm-omni/en/latest/serving/videos_api/)\n- [vLLM-Omni diffusion parallelism](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/diffusion/parallelism/overview/)\n- [vLLM-Omni diffusion attention backends](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/diffusion/attention_backends/)\n- [FastVideo VSA attention guide](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/diffusion/attention_backends/fastvideo_vsa/)\n- [FastH3 preview adapters](https://huggingface.co/FastVideo/FastVideo-FastH3-4-step-Preview-v1-LoRA)\n- [FastH3 family and deployment guides](https://github.com/lishunyang12/vllm-omni/blob/pr/fasth3-omni-upstream/recipes/FastVideo/README.md)\n- [FastH3 Omni and V2 integration (vLLM-Omni #9167)](https://github.com/vllm-project/vllm-omni/pull/9167)\n- [MiniMax-H3 VSA and Ulysses support (vLLM-Omni #6909)](https://github.com/vllm-project/vllm-omni/pull/6909)\n- [vLLM-Omni TRTLLM attention guide (SAGE, Skip-Softmax)](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/diffusion/attention_backends/trtllm/)\n- [MiniMax-H3 production serving on vLLM-Omni (blog)](https://vllm.ai/blog/2026-09-01-minimax-h3-production-serving)\n- [vLLM-Omni supported models](https://docs.vllm.ai/projects/vllm-omni/en/latest/models/supported_models/)\n- [vLLM-Omni GPU installation](https://docs.vllm.ai/projects/vllm-omni/en/latest/getting_started/installation/gpu/)\n- [ROCm H3 tracking issue](https://github.com/vllm-project/vllm-omni/issues/5697)\n", "source": { "source": "vllm-omni", "repo": "vllm-project/vllm-omni", "ref": "main", "sha": "cda4a1ef83b295ba332146a7709e6277725edc9f", "path": "recipes/models/MiniMaxAI/MiniMax-H3.yaml", "edit_url": "https://github.com/vllm-project/vllm-omni/edit/main/recipes/models/MiniMaxAI/MiniMax-H3.yaml", "overlays": [] } }