PixVerse V6 Fusion / Reference-to-Video

What it is

PixVerse V6's Fusion mode: you supply a list of reference images, each tagged as a subject or a background and each given a name, then mention @name in your prompt. The subject from the first image gets placed into the scene from the second, and you keep some control over which is which.

This is character-and-scene compositing as a generation instruction rather than a post-process. The local equivalent is a pile of adapter work - IP-Adapter, face adapters, masked inpainting - or a full instruction editor like Qwen-Image-Edit, which is where most of that workflow went (docs/knowledge/character-consistency.md tracks that migration). Fusion is the hosted-video version of the same idea, and the @ref_name syntax is what makes it feel less like handing the model a bag of images and hoping.

It's also the one node in this folder where you do not get the pack's usual URL-hiding. More on that below, because it's the thing that will trip you up.

How it works

The node is generated from KIE's schema for the Fusion endpoint, and here the schema is a JSON array of objects - each with an image URL, a type (subject or background) and a ref_name. The pack turns IMAGE-shaped URL fields into IMAGE sockets automatically, but this field isn't a URL field: it's a structured list, so it stays a JSON text widget with the example array pre-filled. You supply the URLs yourself.

Everything else behaves like its siblings: the job is submitted as a task, the node polls until it finishes or timeout_seconds (1200 by default) expires, and the finished clip returns as a ComfyUI VIDEO.

Inputs and outputs

Required:

• prompt (STRING) - 3 to 5000 characters, can't be empty. Reference your images by name: @dog, @room.
• image_references (STRING, JSON) - the Fusion list. The author's default shows the shape:

  [
    {"image_url": "https://your-domain.com/images/dog.png", "type": "subject", "ref_name": "dog"},
    {"image_url": "https://your-domain.com/images/room.png", "type": "background", "ref_name": "room"}
  ]

  ref_name must be unique within the list and is capped at 30 characters. Image URLs must be publicly reachable by KIE.
• aspect_ratio - 16:9 default, plus 4:3, 1:1, 3:4, 9:16, 2:3, 3:2, 21:9.
• quality - 720p default, plus 360p, 540p, 1080p.
• duration (INT, 1–15, default 5).

Optional:

• generate_audio_switch - off by default.
• seed - default 123456789, range 0–2147483647.
• timeout_seconds, callback_url.

Outputs: video, url, all_urls_json, task_id, raw_json, credits_consumed, credits_left.

Install

Manager: search KIE-Nodes-Next (felipederosilva), install, restart. Manual:

cd ComfyUI/custom_nodes
git clone https://github.com/felipederosilva/ComfyUI-KIE-Nodes-Next

Then Settings → KIE.ai Nodes Next → Connection → Paste / replace KIE.ai API key - validated on save, shown masked, with ✅ CONNECTED and your balance. KIE_API_KEY also works and takes priority for server installs. Requirements are requests, Pillow, numpy, PyYAML.

Where people get burned

You have to host the images. This is the big one. Unlike every other media input in this pack, image_references stays a JSON string, so your references need public URLs - an IMAGE socket won't do. The pack ships upload utility nodes under KIE Next / Utility / Media that take a ComfyUI IMAGE and hand you back a URL, which is the practical way to bridge that gap. Alternatively use images you already serve somewhere.

JSON errors are your errors. A trailing comma or a missing quote and the request is rejected. Paste it into a validator if you're hand-editing.

Duplicate or missing ref_name. Names must be unique, max 30 characters, and a name used in the prompt must exist in the list. @dog with no dog entry does nothing useful.

Subject/background is a hint, not a mask. Tagging an image background doesn't cut the subject out of it. Give the model clean, single-purpose references.

Cross-reference this against the local route before committing. If your job is "hold this character's face across a shot", the open editors - Qwen-Image-Edit 2511 above all - plus a mask are still the cheaper, more controllable path for stills, and local video models can carry it into motion. Fusion is for when you want a hosted model to do the compositing reasoning in one pass.