WaveSpeedAI Google VEO 3.1 Reference-to-Video

Here's the difference between image-to-video and reference-to-video: I2V animates the whole picture, while reference-to-video keeps the subject and puts them somewhere new. This node from razvanmatei-sf/razv-wavespeed feeds one to three reference images of a person or object into Google's Veo 3.1 via the WaveSpeed AI API, and the prompt tells it what new scene to drop them into. The subject stays recognizable - that's the whole promise.

This is the "put my character in a music video" node. You've got a consistent character, a client who wants the same person in five different settings, a storyboard that reuses a hero - this is the tool. Character consistency across video is genuinely hard, and Veo 3.1's reference mode is one of the better hosted answers to it. It's not magic; it's not guaranteed-identity-grade, but it holds far better than "describe them in the prompt" ever does.

How it works

WaveSpeedAI Client → prompt + image_1 (required reference) → POST to the reference-to-video endpoint → poll → video_url out. The first reference image is mandatory; image_2 and image_3 are optional additions for a more complete subject description (front and side views of a character, say, or a product from two angles).

The tooltip is unusually concrete about the input requirements: PNG/JPEG/JPG/WebP, min 128×128px, max 50MB. If your reference is smaller than 128px, you'll get a bad or failed result - upscale it first.

The dials are trimmed compared to the other Veo nodes: resolution (720p/1080p) and generate_audio are there, but there's no duration and no aspect ratio on this one - the API decides those, presumably from your reference images. negative_prompt, seed, and enable_sync_mode round it out.

The inputs that matter

• image_1 - the required reference. Public URL, at least 128×128, under 50MB. Get this right; it's the whole node.
• prompt - the new scene and action. "The woman from the reference walks through a neon Tokyo street at night" - the subject comes from the image, the world from the prompt.
• image_2 / image_3 - optional extra references for better subject lock.
• generate_audio - synced sound if you want it.

Install

Shared pack:

cd ComfyUI/custom_nodes
git clone https://github.com/razvanmatei-sf/razv-wavespeed
# restart ComfyUI

Or ComfyUI Manager → search "razv-wavespeed" → Install. Add a WaveSpeed AI key via the WaveSpeedAI Client node, config.ini (copy from config.ini.tmp, [API]), or a WAVESPEED_API_KEY env var.

Common issues

• Reference quality is everything. Blurry, low-res, or cluttered references produce a subject that drifts. Use a clean, well-lit, front-facing reference.
• No upload node in this build - the tooltips' "Upload Image node" doesn't exist. Paste public URLs.
• No duration/aspect controls. If the API's default framing doesn't suit you, crop your references to steer it.
• Paid video. Reference mode is a heavier job than plain I2V, and character work usually means several takes. That's several bills.