ComfyUI-Happyhorse-Wrapper Reference To Video

This is the node that keeps the same face on screen for the whole clip. Where Image To Video gives HappyHorse one frame to start from, Reference To Video hands it a stack of reference images and lets the model bind them to specific characters in your prompt. If you've been burning hours training LoRAs or fighting with IPAdapter to keep an actor consistent, this is the shortcut: no training run, no adapter, just a character sheet uploaded to the cloud.

It's the same paid-API pattern as the rest of the pack - you supply references, HappyHorse 1.0 does the heavy lifting on Alibaba's side, and your GPU stays idle. Community testing of HappyHorse has been genuinely mixed-to-positive on exactly this: it's strong on faces and lip-sync (one of the few models that approaches Veo 3.1 on dialogue scenes), and it carries native multi-language audio. That's why the reference workflow is the one worth paying for.

The inputs that matter

• reference_images - a ComfyUI IMAGE batch, 1 to 9 images. This is the heart of the node.
• prompt - multiline, required. This is where the binding happens, and it's the part people get wrong.
• resolution - 720P or 1080P.
• ratio - 16:9, 9:16, 1:1, 4:3, 3:4.
• duration - 3 to 15 seconds.
• watermark - on by default.
• seed - -1 or a pinned integer.

The order thing - read this twice

The model maps reference images to characters by batch order, not by name. Your first image in the batch becomes character1, the second character2, and so on, and you refer to them that way in the prompt: "character1 walks into the room, character2 follows." Wire your images into the node in the exact order you'll reference them - if you batch them out of sequence, the wrong face gets the lines. With a single reference image it's trivial; with several, build the batch deliberately.

How it works

Each image in the batch gets converted to a PNG and uploaded (OSS if configured, tmpfiles.org as fallback), then the node sends a payload to the happyhorse-1.0-r2v model with the media list typed as reference_image. It creates the async task, polls until the clip renders, and returns video_url and task_id. The URL expires, so connect the output to the pack's Preview Video node to save the MP4 locally before it lapses.

Install and setup

Same as every node in this pack - one install, five nodes. ComfyUI Manager → search "ComfyUI-Happyhorse-Wrapper", or:

cd ComfyUI/custom_nodes
git clone https://github.com/magicwang1111/ComfyUI-Happyhorse-Wrapper
python -m pip install -r requirements.txt

Then config.local.json in the pack folder with api_key and endpoint (or the DASHSCOPE_API_KEY env var). No model files, no LoRA downloads - this is a cloud API wrapper, and the only heavy dependency is oss2 for the recommended OSS media uploads.

Where it bites

• Wrong character, right everything else - batch order. Re-check the order you fed the images.
• Upload failures or tasks that hang in PENDING - the tmpfiles.org fallback can be unreachable from Alibaba's side. Configure OSS (.env in the pack folder with OSS_ENDPOINT, OSS_ACCESS_KEY_ID, OSS_ACCESS_KEY_SECRET, OSS_BUCKET) and the flakiness mostly vanishes.
• Blank reference images count - the node enforces 1 to 9, and each one is a real upload, so don't pad the batch with dummies expecting them to be ignored.