bytedance/seedance-2.5/reference-to-video

Run Seedance 2.5 AI Reference To Video API on fal

Combine up to 50 multimodal references — images, video, audio, and style — into a single generation of up to 30 seconds with native audio, real-world physics, and director-level camera control.

bytedance/seedance-2.5/reference-to-video

Overview

Seedance 2.5 is the next generation of the world's top-ranked video model, and reference to video is its most controllable endpoint. Supply references for subject appearance, motion style, composition, and rhythm, then describe in the prompt how to combine them. Reference inputs are addressed positionally in the prompt as [Image1], [Video1], [Audio1], etc.

The same endpoint covers video editing and video extension: give it a reference video and describe what to change, or describe what should happen next.

API Endpoints

Pricing

Billing is token-based, and on this endpoint input video duration is billed alongside output:

tokens = (output_height * output_width * (input_video_duration + output_duration) * 24) / 1024

You are charged $0.0214 per 1000 tokens at both 480p and 720p. If any video references are provided, the price is multiplied by 0.6. Image and audio references are not billed.

Per-second figures are approximations for the common 16:9 case, and in the video-reference column they apply to input and output seconds alike. The token formula is authoritative.

Worked examples

Trim reference videos to the segment that actually matters. Every second of input video you send is a billed second.

What's new in 2.5

Up to 50 multimodal reference inputs. Images, video, audio, and style references in one pass, up from 12 in the previous generation, for far more granular control over subject, motion, and composition.

Native 30-second generation. A full 30 seconds in a single pass — no stitching, no scene-cut splicing, no visible seams. Roughly double the native ceiling of Seedance 2.0, and a duration no other commercial video model has matched.

Audio in the same latent space. Sound and visuals are generated jointly rather than sequentially, which is what makes reference audio usable as an actual timing signal for on-screen action.

Better prompt adherence. Roughly 20% better, per ByteDance, meaning fewer generations before a usable result. This compounds on this endpoint, where prompts carry the most instruction.

Intelligent duration. Set duration to "auto" and the model picks the optimal length for the content.

Adaptive aspect ratio. Set aspect_ratio to "auto" and the model chooses the best fit based on your inputs.

Usage

Install the client:

bash
npm install --save @fal-ai/client

Note: @fal-ai/serverless-client is deprecated. Use @fal-ai/client instead.

Python

python
import fal_client

result = fal_client.subscribe(
    "bytedance/seedance-2.5/reference-to-video",
    arguments={
        "prompt": (
            "The woman from [Image1], wearing the jacket from [Image2], "
            "performs the dance from [Video1] on the rooftop from [Image3], "
            "hitting the beats of [Audio1]. Keep her face and the jacket exact."
        ),
        "image_urls": [
            "https://example.com/subject.jpg",
            "https://example.com/jacket.jpg",
            "https://example.com/rooftop.jpg",
        ],
        "video_urls": ["https://example.com/dance.mp4"],
        "audio_urls": ["https://example.com/track.mp3"],
        "duration": "10",
        "resolution": "720p",
        "aspect_ratio": "16:9",
    }
)

print(result["video"]["url"])

JavaScript

javascript
import { fal } from "@fal-ai/client";

const result = await fal.subscribe("bytedance/seedance-2.5/reference-to-video", {
  input: {
    prompt:
      "The woman from [Image1], wearing the jacket from [Image2], performs the dance from [Video1]. Keep her face and the jacket exact.",
    image_urls: [
      "https://example.com/subject.jpg",
      "https://example.com/jacket.jpg",
    ],
    video_urls: ["https://example.com/dance.mp4"],
    duration: "10",
    resolution: "720p",
    aspect_ratio: "16:9",
  },
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS") {
      update.logs.map((log) => log.message).forEach(console.log);
    }
  },
});

console.log(result.data);

REST

bash
curl -X POST https://fal.run/bytedance/seedance-2.5/reference-to-video \
  -H "Authorization: Key $FAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Replace the perfume in [Video1] with the face cream from [Image1], keeping all original motion.",
    "video_urls": ["https://example.com/original.mp4"],
    "image_urls": ["https://example.com/facecream.jpg"],
    "duration": "10",
    "resolution": "720p"
  }'

Note: Use the queue API rather than a synchronous call — reference generations with video inputs are the slowest of the three endpoints.

Input schema

Reference to Video (bytedance/seedance-2.5/reference-to-video)

Up to 50 reference inputs total across images, videos, and audio. Ordering within each list determines the index used in the prompt: the second entry of image_urls is [Image2].

Output schema

json
{
  "video": {
    "url": "https://v3b.fal.media/files/...",
    "content_type": "video/mp4",
    "file_name": "video.mp4",
    "file_size": 18240512
  },
  "seed": 1094575694
}

Access the video URL at result["video"]["url"] (Python) or result.data.video.url (JavaScript).

Supported resolutions

Capabilities

Multimodal composition. Reference video for motion style, images for character appearance and wardrobe, audio for rhythm — then describe how to combine them. Powerful for outfit-change videos, product showcases, character-consistent series, and music-synced content.

Video editing. Provide a reference video and describe changes — replace an object, change a background, alter the style. The model preserves original motion and camera work while applying your edits.

Video extension. Provide a reference video and describe what should happen next. The model continues the scene with consistent characters, environment, and style. With a 30-second native ceiling, extension is for narrative continuation rather than for working around a short duration limit.

Tips

• Label references explicitly. "The character from [Image1] performs the dance from [Video1]" beats leaving the model to guess which reference does what.
• Say what to preserve. On edits, name both sides: "Replace the perfume in [Video1] with the face cream from [Image1], keeping all original motion."
• More references is not automatically better. Each one competes for influence. Start with the two or three that carry the concept, then add.
• Trim input video. Input video seconds are billed. Cut references to the segment you actually need.
• Iterate at 480p. Composition and reference weighting read fine at 480p and cost under half as much. Lock the arrangement there, then re-run the winning seed at 720p.
• Prefer clean reference images. Well-lit, single-subject images give the most reliable identity transfer.