happyhorse/reference-to-video

Nine reference images, max. That's the pitch: feed it a cast, describe the shot, and let the model place them. Multi-character video is the part of consistency work nobody has actually solved, so a node that lets you address characters by index is worth understanding properly - including where it breaks.

The mechanism is simpler than it looks. Your reference_image list is ordered, and that order is the character numbering: first URL is character1, second is character2, third is character3. The tooltip says this explicitly. Then you write the prompt using those names, and the model is supposed to keep them apart.

Inputs

prompt (required) is where the real work happens. Use character1, character2, etc. to refer to your references, and describe camera and action around them. The default value in the node is a good template - it's a multi-angle Eastern-elegance shot described in beats ("the shot opens with… then cuts to… finally the camera pushes into…"). That structure is the technique: shots and camera moves, not adjectives. Cap is 5000 non-Chinese characters or 2500 Chinese.

reference_image (required) is a URL list as JSON text, not an IMAGE socket:

[
  "https://example.com/character-a.png",
  "https://example.com/character-b.png"
]

Provide 1–9. KIE's limits: JPEG/JPG/PNG/WEBP, shortest side at least 400px, 720P or higher recommended, 10MB max each. Blurry or heavily compressed references measurably degrade output. Since it's a string field, you either paste URLs or wire a STRING from the pack's upload utility - there's no drag-a-Load-Image convenience here.

resolution is 1080p (default) or 720p. aspect_ratio is five options: 16:9, 9:16, 1:1, 4:3, 3:4. duration is an integer 3–15 seconds, default 5. seed gives you a reproducibility knob (0–2147483647), which "if supported" - always the caveat with hosted seed parameters.

timeout_seconds defaults to 1200; callback_url stays empty for normal ComfyUI work, because these nodes poll synchronously.

Outputs

video is the primary output, a native VIDEO for downstream nodes. url is the top result URL, all_urls_json is everything returned, task_id is your reference for KIE support, raw_json is the unfiltered response, and credits_consumed plus credits_left are floats. Clips land in ComfyUI/output/KIE-Results/videos/.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/felipederosilva/ComfyUI-KIE-Nodes-Next
cd ComfyUI-KIE-Nodes-Next
pip install -r requirements.txt

Restart after cloning. Dependencies: requests, Pillow, numpy, PyYAML. No weights to download - HappyHorse has never published any, which is worth repeating given how many fake repos traded on the name. There's a Windows one-click installer in dist/.

API key once, in Settings → KIE.ai Nodes Next → Connection. It's validated before it overwrites a working key, only a masked fingerprint comes back, and nothing is written into your workflow. KIE_API_KEY covers headless installs and takes priority over the saved key.

Where this actually goes wrong

References past the first two or three get muddled. Nine is the documented ceiling, not a guarantee, and the community's honest position on multi-character consistency is that it's still the unsolved case. If characters are swapping faces or merging, you're hitting the known wall, not a bug - reduce the cast, or split into separate passes and cut them together.

Order is the API. If your prompt says character1 is the woman in the red dress, and URL number one is a man in a suit, you've told the model nothing useful. Keep the list order stable, and keep it in sync when you edit the prompt.

Unreferenced images do nothing. An image not named in the prompt is the model's to use or ignore. If it matters, name it.

Timeout means you still paid. The render continues on KIE's side after the node gives up; use the task_id in the error with the Task Status node to see whether it finished.

Rerunning the identical graph returns the cached video rather than generating a new one. Change the seed or prompt to spend credits again.