LongCat Video Avatar 1.5 Setup: Commands & VRAM

A LongCat video avatar is an audio-driven talking head. You supply a still portrait and a voice clip, and the model renders that face speaking the audio with matching lip movement — useful for faceless creators, virtual presenters and anyone who wants a recurring on-screen persona without a camera.

This page is about the local, self-managed Avatar workflow. The hosted generator on this site takes a still image plus a motion prompt and returns a clip: it does not accept audio and does not do speech-driven lip sync. If that is what you need, run Avatar-1.5 yourself with the steps below.

What "avatar" means in the LongCat ecosystem

The avatar model is a distinct inference path, not a prompt trick on top of the base video model:

• Audio-driven generation — a portrait plus a WAV file in, a speaking head out, with lip movement produced by the audio encoder rather than a retiming pass after generation
• A separate checkpoint — LongCat-Video-Avatar-1.5 — whose audio encoder differs from the standard LongCat Video model
• Single- and multi-speaker input — v1.5 accepts one audio stream or two
• Continuation — the same model extends a shot, so long clips are repeated generations stitched in place

The practical rule: treat the avatar model and the base video model as two different tools that share a lineage. Swapping their checkpoints "because they are both LongCat" is the fastest way to a run that will not load.

Avatar 1.0 vs Avatar 1.5

Avatar 1.5 requires distillation sampling: if you run it without --use_distill, the run fails rather than silently falling back.

How to run it: the official path

Upstream publishes the code, weights and commands; these are the steps from that repository, not a paraphrase of a video description.

1. Install the environment

git clone --single-branch --branch main https://github.com/meituan-longcat/LongCat-Video
cd LongCat-Video

conda create -n longcat-video python=3.10
conda activate longcat-video

# Install the PyTorch/CUDA combination for your machine, then:
pip install ninja psutil packaging
pip install flash_attn==2.7.4.post1
pip install -r requirements.txt
conda install -c conda-forge librosa ffmpeg
pip install -r requirements_avatar.txt

2. Download the Avatar 1.5 weights

pip install "huggingface_hub[cli]"
huggingface-cli download meituan-longcat/LongCat-Video-Avatar-1.5 \
  --local-dir ./weights/LongCat-Video-Avatar-1.5

Do not silently substitute the original Avatar checkpoint: the audio encoder and inference path differ between versions, and mixing files produces a checkpoint that will not load.

3. Run an audio image-to-video job

torchrun --nproc_per_node=2 run_demo_avatar_single_audio_to_video.py \
  --context_parallel_size=2 \
  --checkpoint_dir=./weights/LongCat-Video-Avatar-1.5 \
  --stage_1=ai2v \
  --input_json=assets/avatar/single_example_1.json \
  --use_distill --model_type avatar-v1.5 --use_int8

For two speakers, swap in run_demo_avatar_multi_audio_to_video.py with a multi-speaker JSON. For a longer clip, add the continuation flags:

  --num_segments=5 --ref_img_index=10 --mask_frame_range=3

4. Settings that change the output

These are the upstream tips, with the flags they map to:

The ComfyUI route

For a visual workflow, the community wrapper keeps LongCat nodes on its main branch:

cd ComfyUI/custom_nodes
git clone https://github.com/kijai/ComfyUI-WanVideoWrapper.git
cd ComfyUI-WanVideoWrapper
pip install -r requirements.txt
git rev-parse HEAD

Record the commit printed by that last command with every saved workflow, then start from the repository's LongCatAvatar_audio_image_to_video_example_01.json example instead of an untraceable JSON from a video description. The wrapper is a personal, perpetually work-in-progress sandbox — update it in a separate copy, run one known input, and keep the last working commit so a node rename cannot break all jobs at once. There is no official Meituan ComfyUI node: the meituan-longcat organisation publishes the model, not a ComfyUI extension.

Inputs that prevent wasted runs

Bad inputs cause more avatar failures than weak hardware. Before you generate anything, satisfy this checklist:

1. Use a sharp portrait with the full head visible and no object covering the face
2. Start with one speaker and a short, clean WAV file before attempting multi-person audio
3. Keep the audio sample rate and channel layout consistent across every test
4. Write a prompt that describes identity, framing, clothing, background, and restrained motion
5. Record the model filename, wrapper commit, workflow JSON, seed, dimensions, duration, and audio filename with every saved result
6. Confirm the audio has no loud background music or overlapping voices on the first pass
7. Avoid extreme close-ups that crop the jaw or forehead, which the lip-sync motion relies on
8. Reuse the same portrait across comparisons so you can isolate audio and prompt changes

VRAM and duration: measure, do not guess

The official Avatar 1.5 pages do not publish a universal "works on 8GB / 12GB" minimum. Community FP8, GGUF, CPU offload, block-swap and INT8 (the --use_int8 flag above) workflows can reduce peak VRAM, but the real number depends on checkpoint format, resolution, frame count, attention backend, system RAM, and wrapper version. Use a bounded test ladder:

1. Run the repository's known example at its documented settings first
2. Run 3-5 seconds with your own portrait and audio
3. Record peak VRAM, system RAM, wall time, and output dimensions
4. Change only one variable at a time between runs
5. Increase duration only after lip sync and identity remain stable

"Supports long video" does not mean an infinite clip has zero drift. Continuation is a repeated generation operation — inspect every join for face changes, color shifts, hand artifacts, background jumps, and audio offset.

Failure triage

Production checklist before you publish

• Watch the complete result with sound and verify lip timing, identity, hands, teeth, and eye motion
• Check scene continuity at every continuation join
• Confirm you have the rights to the portrait and the audio you used
• Review the model license separately from "open source" — the weights are MIT licensed, but your own inputs have their own rights
• Apply any disclosure or consent requirements your platform imposes on synthetic media
• Keep the wrapper commit and model filename beside the final file for future reproducibility

What you can and cannot do on this site

The hosted generator on longcat-video.org is an image-to-video tool: a still image plus a motion prompt, priced at 150-300 credits per run depending on model and resolution, with the exact cost quoted before submission and purchased credits required from the first hosted run. It has no audio input, so it cannot produce a talking avatar.

• No audio, no lip sync — the hosted workflow cannot do it at any price tier; it is not a feature you unlock later
• Motion from a still image — use the hosted image-to-video workflow for silent clips
• Speech-driven video — run Avatar 1.5 locally using the steps above, or follow the ComfyUI avatar tutorial for the wrapper-based route
• Pricing for the hosted runs — every credit pack is listed on /pricing

Related use cases

• Consistent character AI video — keep the same face across long scenes
• Image to long video AI — animate a still image into minutes of motion
• LongCat AI video — the text-to-video and continuation engine underneath
• LongCat Video guide 2026 — prompt structure, parameters and real credit costs
• Faceless AI video generator — the narration-over-footage format this avatar replaces or complements