Using Seedance reference-to-video over API

Updated 2026-10-02

Image-to-video animates one frame you supply. Reference-to-video is different: you hand the model a pile of reference material (a character sheet, a motion clip, an audio bed) and ask for a new clip guided by it. The references are never edited or returned. This matters for anyone who needs the same character, product or voice across many shots.

The three reference fields

On POST /videos, references go in three optional arrays that share one shape: {"type": "<kind>_url", "<kind>_url": {"url": ...}}.

The Fal-hosted Seedance 2.0 reference endpoint (and the Fast and Mini variants built on the same schema) caps the combined total at 12 references. At least one reference across the three arrays is required; a reference-mode call with none is rejected with a 400. Exceeding any per-kind cap or the combined cap is also a 400, not a silent truncation.

A request that uses all three

The mode is chosen by which fields you send; there is no separate "-reference" model id to look up. Pinning a host with the /fal suffix keeps the call on a host with documented reference support:

curl https://videorouter.sh/api/v1/videos \
  -H "Authorization: Bearer llmr_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0/fal",
    "prompt": "the cat from the reference image walks across the scene, camera follows",
    "input_references": [
      {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}}
    ],
    "input_video_references": [
      {"type": "video_url", "video_url": {"url": "https://example.com/motion-ref.mp4"}}
    ],
    "input_audio_references": [
      {"type": "audio_url", "audio_url": {"url": "https://example.com/ambience.mp3"}}
    ],
    "duration_secs": 5
  }'

The response is an async job. Poll GET /videos/{id} until completed or failed; polling is free, and the job is billed once at creation by the requested duration.

A consistent-character workflow

1. Build the reference set once. Two to four images of the same character from different angles (front, three-quarter, full body) usually give the model more to hold onto than nine near-duplicates. Host them at stable public URLs, or send data: URIs.
2. Refer to references in the prompt by role. "The woman from the reference images" beats a name the model has never seen. If you attach a video reference, say what it is for: motion, camera move or framing.
3. Keep the reference set identical across shots and vary only the prompt and duration. That is the single biggest lever for continuity across a sequence.
4. Draft cheap, finish expensive. The same reference arrays work on the Mini and Fast variants, so you can test shot compositions there and re-run the approved ones on a full model. See the variant guide.

Pitfalls worth knowing before you ship

• Reference mode is mutually exclusive with editing. input_video_url (modify one existing clip) cannot be combined with any of the reference arrays or with start_image_url. Pick the intent first.
• Not every host or variant supports every array. VideoRouter's documentation shows the full image/video/audio set on specific Fal-hosted Seedance 2.0 endpoints. Some other hosts accept images only. If a call fails validation, check the model pages for the host you landed on rather than assuming the model is at fault.
• Floating requests can land on a host with narrower support. If your workflow depends on video or audio references, pin the host. Unpinned requests route to the cheapest healthy host and fail over on outages, which is what you want for plain text-to-video but not for a reference set that only some hosts understand.
• URLs must be fetchable. Private or signed-and-expired URLs fail on the host side. Presigned links need a lifetime longer than your queue time.
• Total upload size matters. The documented Fal endpoint limits combined input to 50 MB, so re-encode large reference videos before sending.
• A failed upstream job is not billed, but a successful one you dislike is. Iterate on the prompt with a cheap variant before committing references to a full-price render.

Reference vs start image: which to use

If you have exactly one frame and want it to be the literal opening of the clip, use start_image_url (covered in the image-to-video guide). If you want the character or style to appear in a scene the model composes itself, or you need motion and audio guidance, use references. Many pipelines use both in different stages: references to establish the look, start-frame animation for shots that need an exact composition.

Writing prompts that use the references

Reference calls fail quietly more often than they fail loudly: the job completes, but the character drifted because the prompt never told the model which reference mattered. A few habits help. Name each role once and keep the wording stable across shots, for example "the courier from the reference images" every time. If the video reference supplies a camera move, say "follow the camera movement of the reference clip" rather than re-describing it. If the audio reference is ambience, say that, so the model does not treat it as dialogue to lip-sync. Keep the prompt short and concrete; ten sentences of scene description compete with the references instead of supporting them.

When a result is wrong, change one thing per run: the prompt, the order of reference images, or the number of images. Changing all three at once leaves you unable to tell what helped. Log the full request body next to each job id so you can reproduce a shot that worked.

Comparing hosts for reference calls

Seedance is sold by many providers at very different per-second rates, and reference-capable hosts are a subset. The live table below covers every Seedance row in the catalog; confirm reference support on the specific model page before pinning.

Per second, before VideoRouter's 2% platform fee. For tiered models each row compares the resolution tier with the widest host-to-host gap. Built 2026-10-02 from the live catalog.

Ready to try it? Create a key and start from the quickstart.

Frequently asked questions

Keep reading

• Seedance 2.5 vs 2.0 vs Fast vs Mini — Choosing a Variant for API Use
• Seedance Image-to-Video API: start_image_url Prompts & Setup
• Seedance vs Kling vs Veo API: How to Choose by Workload
• How to Call the Seedance 2.5 API: curl and Python Examples