Reference-to-Video: Image Limits for Seedance 2.5, Wan 3.0 and More

Reference-to-video (mode r2v) lets you send a set of reference images with your prompt, so a clip can reuse subjects, outfits or settings you already have. On MakerNice, eight video models support it: Seedance 2.5 from ByteDance takes up to 16 images, Wan 3.0 from Alibaba up to 10 and MiniMax H3 Max as few as 4. Kling 3.0 does not support it.

What is reference-to-video, and how is it different from image-to-video?

In image-to-video and first and last frame, your picture becomes an actual frame of the clip, the first or the last one. In reference-to-video, the pictures are references for subjects or style, and the clip does not have to show any of them as a frame. Pick r2v when you want a recurring character or product to appear in a new scene.

How many reference images can each video model take?

Sending more references than the model allows is rejected with 400 invalid_request, so check the limit before you build a request. When you switch models, read the mode list from GET /v1/models, which needs no API key and is the source of truth for what each model accepts today.

How do you build a reference-to-video API request?

Set mode to r2v and fill reference_images with public https URLs. Because unused fields are rejected, do not send image_url or last_image_url in this mode. Duration and resolution follow the model's own rules; this Seedance 2.5 example asks for 6 seconds at 720p.

{
  "model": "seedance-2.5",
  "mode": "r2v",
  "prompt": "The two characters from the references walk through a night market, handheld camera following from behind",
  "reference_images": [
    "https://example.com/character-a.jpg",
    "https://example.com/character-b.jpg"
  ],
  "duration": 6,
  "resolution": "720p"
}

Send this input to POST /v1/generations/quote first, then create the generation with the quote id and an Idempotency-Key, exactly as in a text-to-video request. Keep the reference URLs reachable until the generation has finished.

Why does an r2v request return 400 invalid_request?

The most common cause is aspect_ratio. Whether it is allowed in r2v mode differs per model, and a field the model does not list is rejected. Seedance 2.5, Wan 3.0 and Happy Horse 1.1 list no ratios for r2v, while Seedance 2.0 and MiniMax H3 do. A request copied from one model to another is the usual source of an unexpected 400; the second most common is one reference too many.

How do you choose good reference images?

• Fewer, clearer references usually beat the maximum number. Add more only when each one contributes something different.
• Keep the references consistent in style and lighting if you want the clip to feel cohesive.
• Name what each reference is for in the prompt, such as the two characters from the references.
• Store references on stable public URLs until the generation has finished.

If you want your picture to be the opening or closing shot instead, read the image-to-video and first and last frame guide. To check what an r2v clip will cost before you commit, request a quote with the exact input or see the Pricing page.