NS WaveSpeed VEO 3.1 Reference to Video

The standard Veo image-to-video node animates from a single starting frame - great for a shot, but useless for the thing character work actually needs: a subject who looks the same from every angle across a whole sequence. NSWaveSpeedVeo31ReferenceToVideo from symbiotica-ai/comfyui-nodes is the node built for that. Up to three reference images, and Veo 3.1 treats them as a subject spec - a character sheet the model keeps referring back to, not just a first frame. It's the difference between "animate this picture" and "make a video starring this character."

How it works

You wire 1–3 reference images in as URL strings (Upload Image node → image_1 … image_3). The node calls WaveSpeed's Veo 3.1 reference endpoint, which holds onto the subject's appearance - face, clothing, palette - while generating. image_1 is required; two or three refs help when the subject has a design that needs disambiguation (front and back views, or a full-body plus a face close-up). The prompt describes the action while implying subject consistency: the tooltip's framing - "text description for video generation with subject consistency" - is the whole game.

There's no aspect_ratio or duration on this node; the API fixes those. You get resolution (720p/1080p), generate_audio (Veo's native synchronized sound - a character clip with dialogue can be a character clip with dialogue), and optional negative_prompt / seed (default -1 = random). enable_sync_mode defaults off - submit, poll every second, block until done, Cancel works.

The inputs that matter

• image_1 (required) - the primary subject reference. PNG/JPEG/WebP, min 128x128, max 50MB per the tooltip.
• image_2 / image_3 (optional) - additional views to lock the subject down.
• prompt - the action, with consistency implied.
• generate_audio - native audio; toggle off if you're adding sound later.
• client - the WAVESPEED_AI_API_CLIENT socket from the NS WaveSpeed Client node.

Output: video_url (STRING) - browser-preview or feed a download-from-URL node.

Install and keys

# ComfyUI Manager: search "Symbiotica", or:
cd ComfyUI/custom_nodes
git clone https://github.com/symbiotica-ai/comfyui-nodes.git symbiotica
pip install -r symbiotica/requirements.txt

Restart, add the NS WaveSpeed Client node with your wavespeed.ai key (widget, Settings → Symbiotica, or WAVESPEED_API_KEY), wire client in. No model downloads.

Common issues

More refs isn't automatically better. Three references that disagree with each other (different lighting, different outfit states) confuse the model. Curate refs that look like the same person in the same wardrobe, and the consistency follows (character-consistency.md).

Expect minutes and a bill. Reference-based renders are slower and pricier than plain i2v - that's the cost of holding a character identity across frames. And remember the refs themselves leave your machine; what you feed the model is subject to the provider's moderation (external-api-nodes.md).

"API_KEY is empty." The NS WaveSpeed Client node isn't wired in - the key lives there.