seedinteger
Random seed for reproducible results. Omit or use -1 for a random seed.
Minimum: -1
Maximum: 4294967295
Seedance 2.5 Reference to Video
20% OFF
bytedance/seedance/2.5/reference-to-videoByteDance's next-generation reference-to-video model, generating video from multimodal references (images, videos, audio) and locking a character, set, and palette across a full take up to 30 seconds for production-grade consistency.
Try the model
Playground
Input
The text prompt to generate a video from.
Additional Settings More
Customize your input with more control.
PNG, JPEG, WebP, or GIF · 20 MiB maximum each
The URLs of reference images to guide video generation. Refer to them in the prompt as @Image1, @Image2, etc.
The URLs of reference videos to guide video generation. Up to 10 MP4 or MOV files; combined duration must not exceed 30 seconds.
The URLs of reference audio files to guide video generation.
`reference` generates a new video from the references, `edit` edits a reference video (replace subjects, add or remove objects, repaint), `extend` extends a reference video forward or backward, `auto` (or omitted) lets the model infer it from the prompt. `edit` and `extend` require at least one video; `edit` forces `adaptive` aspect ratio and `auto` duration, `extend` forces `adaptive` aspect ratio. Write the prompt to match, otherwise the task can fail with a task-type mismatch. Allowed values: auto, reference, edit, extend.
Output duration in seconds (4-30), or `auto` to let the model pick a length from the prompt and inputs. `auto` is pre-authorized at 30 seconds and billed on the actual output length. When a reference video is edited or extended, use `auto` with `adaptive` aspect ratio so the output follows the source clip. Allowed values: auto, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30.
Output aspect ratio. Omit to let the model choose from the prompt and reference inputs. Allowed values: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, adaptive.
The resolution of the video to generate. Allowed values: 480p, 720p, 1080p.
Whether to generate synchronized audio (voice, SFX, BGM) for the video.
Random seed for reproducible results. Omit or use -1 for a random seed. Range: -1 to 4294967295.
Draft mode step 1: render a fast, low-cost 480p draft (overrides `resolution`, billed at the 480p rate). Pass the result's `outputs[0].draft_id` back as `draft_id` within 7 days to render the same shot at 1080p.
Draft mode step 2: the `outputs[0].draft_id` of a succeeded draft from this same model (created with `draft: true` in the last 7 days). Renders the same shot at 1080p, billed at the 1080p rate for the actual output length. The prompt, media, duration, aspect ratio, seed, audio setting and task type are reused from the draft; any such fields sent with `draft_id` are ignored.
ResultExample
What would you like to do next?
Examples
Select an example to load its inputs and result into the playground.
- Open result ↗
Input
{ "prompt": "Use Image1 as the visual reference and Video1 as the motion reference. Create a peaceful cinematic shoreline scene with rolling ocean waves at golden hour, soft foam, natural water movement, and no people." }
Seedance 2.5 Reference to Video
Seedance 2.5 reference-to-video: combine reference images, up to 10 reference videos, and reference audio to lock a character, set, motion, or voice in a new clip.
Fields
| Field | Type | Default | Notes |
|---|---|---|---|
prompt | string, required | — | Up to 50,000 characters. |
images | image URL[] | — | Reference images, Image 1, Image 2, … |
videos | video URL[] (≤10) | — | Reference clips (up to 10), Video 1, Video 2, … |
audios | audio URL[] | — | Reference audio, Audio 1, Audio 2, … |
duration | auto / 4 / 5 / 6 / 7 / 8 / 9 / 10 / 11 / 12 / 13 / 14 / 15 / 16 / 17 / 18 / 19 / 20 / 21 / 22 / 23 / 24 / 25 / 26 / 27 / 28 / 29 / 30 | 5 | Output length in seconds (4–30), or auto to let the model choose. |
aspect_ratio | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 | — | Output frame shape. |
resolution | 480p / 720p / 1080p | 720p | Sets the per-second rate. |
generate_audio | boolean | true | Native dialogue, music, and effects. Same price on or off. |
seed | integer -1–4294967295 | random | Fix it to compare prompt changes; -1 is random. |
Billing
Without reference videos you pay for output seconds: $0.18 at 480p, $0.36 at 720p, $0.90 at 1080p. With reference videos, the input video seconds (at least 2) are added to the output length and billed at a lower rate: $0.11 at 480p, $0.22 at 720p, $0.55 at 1080p. With duration: "auto" the quote assumes 30 seconds and the final charge uses the generated length.
| Output | 480p | 720p | 1080p |
|---|---|---|---|
| 5s, images only | $0.90 | $1.80 | $4.50 |
| 10s, images only | $1.80 | $3.60 | $9.00 |
| 5s + 5s reference video | $1.10 | $2.20 | $5.50 |
| 10s + 10s reference video | $2.20 | $4.40 | $11.00 |
Failed runs are not charged.
Prompting
- Give each reference a role: “Image 1 is the dancer, Video 1 sets the choreography, Audio 1 is the music”.
- Numbering follows array order within each type.
Limits
- Reference video seconds count toward billing (minimum 2, up to 30).
Task types
task_type selects the reference sub-task: reference (new video guided by the references), edit (edit a reference video), extend (extend a reference video forward or backward), or auto (default, inferred from the prompt). edit and extend need at least one video and use the source clip's aspect ratio; edit also follows the source clip's length and is billed on the actual output length. If the prompt contradicts an explicit task_type, the task fails.
{"prompt": "Replace the man in @Video1 with the character in @Image1.", "images": ["https://example.com/character.png"], "videos": ["https://example.com/source.mp4"], "task_type": "edit"}
Draft mode
Draft mode is two calls to this same model:
- Draft: add
"draft": true. The output is a 480p preview billed at the 480p rate, andoutputs[0].draft_ididentifies it. - Final: send
{"draft_id": "<outputs[0].draft_id>"}(optionallywatermark). The same shot is rendered at 1080p and billed at the 1080p output rate for the actual output length.
The final reuses the draft's prompt, media, duration, aspect ratio, seed and audio setting; those fields are ignored when draft_id is set. A draft can be finalized within 7 days, only with the model that created it.
{"prompt": "@Image1 walks along the shoreline in the style of @Video1.", "images": ["https://example.com/character.png"], "videos": ["https://example.com/style.mp4"], "draft": true}
{"draft_id": "<outputs[0].draft_id from the draft>"}
Also on SandBase
Other Seedance 2.5 endpoints and tiers: bytedance/seedance/2.5/text-to-video, bytedance/seedance/2.5/image-to-video, bytedance/seedance/2.0/reference-to-video, bytedance/seedance/2.0/fast/reference-to-video, bytedance/seedance/2.0/mini/reference-to-video.
Start building
Send your first request
Submit this model through the SandBase Unified Run API.
# The quoted heredoc keeps Unicode and shell metacharacters unchanged.
result=$(curl --fail-with-body --silent \
-X POST "https://api.sandbase.ai/v1/run" \
-H "Authorization: Bearer $SANDBASE_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @- <<'SANDBASE_JSON'
{
"model": "bytedance/seedance/2.5/reference-to-video",
"draft": false,
"images": [
"https://static.sandbase.ai/examples/bytedance/seedance/2.0/reference-to-video/input_image_safe_ocean_0.jpg"
],
"prompt": "Use Image1 as the visual reference and Video1 as the motion reference. Create a peaceful cinematic shoreline scene with rolling ocean waves at golden hour, soft foam, natural water movement, and no people.",
"videos": [
"https://static.sandbase.ai/examples/pixverse/sound-effects/input_video_0.mp4"
],
"duration": 5,
"resolution": "720p",
"generate_audio": true
}
SANDBASE_JSON
)
run_id=$(printf '%s' "$result" | jq -r .id)
for attempt in $(seq 1 120); do
status=$(printf '%s' "$result" | jq -r .status)
case "$status" in completed|failed|timeout) break ;; esac
sleep 2
result=$(curl --fail-with-body --silent \
-H "Authorization: Bearer $SANDBASE_API_KEY" \
"https://api.sandbase.ai/v1/run/$run_id")
done
status=$(printf '%s' "$result" | jq -r .status)
[ "$status" = completed ] || { echo "Generation ended: $status" >&2; exit 1; }
printf '%s\n' "$result"2. Authentication
Create a SandBase API key and set it in your server environment. All requests use Bearer authentication.
export SANDBASE_API_KEY="YOUR_API_KEY"Keep the key on your server. Do not expose it in browser code or commit it to a repository.
3. Queue
Submit a request
POST to /v1/run with this model ID and its inputs. The request example above includes submission and polling.
Fetch request status and result
Use the returned run ID to poll until the status is completed, failed or timeout. Read output only after completed.
curl "https://api.sandbase.ai/v1/run/$RUN_ID" \
-H "Authorization: Bearer $SANDBASE_API_KEY"4. Files
Hosted files
Pass a publicly accessible file URL in the model’s image, video or audio field. Supported formats and limits are shown beside each Playground input.
Uploading images
Use the upload or replace control on supported image fields in the Playground. Video URL fields accept a hosted driving video; they do not imply video-upload support.
5. Schema
Input
draftboolean
Draft mode step 1: render a fast, low-cost 480p draft (overrides `resolution`, billed at the 480p rate). Pass the result's `outputs[0].draft_id` back as `draft_id` within 7 days to render the same shot at 1080p.
Default: false
audiosarray
The URLs of reference audio files to guide video generation.
imagesarray
The URLs of reference images to guide video generation. Refer to them in the prompt as @Image1, @Image2, etc.
promptstring
The text prompt to generate a video from.
Default: "Use Image1 as the visual reference and Video1 as the motion reference. Create a peaceful cinematic shoreline scene with rolling ocean waves at golden hour, soft foam, natural water movement, and no people."
videosarray
The URLs of reference videos to guide video generation. Up to 10 MP4 or MOV files; combined duration must not exceed 30 seconds.
draft_idstring
Draft mode step 2: the `outputs[0].draft_id` of a succeeded draft from this same model (created with `draft: true` in the last 7 days). Renders the same shot at 1080p, billed at the 1080p rate for the actual output length. The prompt, media, duration, aspect ratio, seed, audio setting and task type are reused from the draft; any such fields sent with `draft_id` are ignored.
durationvalue
Output duration in seconds (4-30), or `auto` to let the model pick a length from the prompt and inputs. `auto` is pre-authorized at 30 seconds and billed on the actual output length. When a reference video is edited or extended, use `auto` with `adaptive` aspect ratio so the output follows the source clip.
Default: 5
Possible values: "auto", 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30
task_typestring
`reference` generates a new video from the references, `edit` edits a reference video (replace subjects, add or remove objects, repaint), `extend` extends a reference video forward or backward, `auto` (or omitted) lets the model infer it from the prompt. `edit` and `extend` require at least one video; `edit` forces `adaptive` aspect ratio and `auto` duration, `extend` forces `adaptive` aspect ratio. Write the prompt to match, otherwise the task can fail with a task-type mismatch.
Possible values: "auto", "reference", "edit", "extend"
resolutionstring
The resolution of the video to generate.
Default: "720p"
Possible values: "480p", "720p", "1080p"
aspect_ratiostring
Output aspect ratio. Omit to let the model choose from the prompt and reference inputs.
Possible values: "16:9", "9:16", "1:1", "4:3", "3:4", "21:9", "adaptive"
generate_audioboolean
Whether to generate synchronized audio (voice, SFX, BGM) for the video.
Default: true
{
"model": "bytedance/seedance/2.5/reference-to-video",
"draft": false,
"images": [
"https://static.sandbase.ai/examples/bytedance/seedance/2.0/reference-to-video/input_image_safe_ocean_0.jpg"
],
"prompt": "Use Image1 as the visual reference and Video1 as the motion reference. Create a peaceful cinematic shoreline scene with rolling ocean waves at golden hour, soft foam, natural water movement, and no people.",
"videos": [
"https://static.sandbase.ai/examples/pixverse/sound-effects/input_video_0.mp4"
],
"duration": 5,
"resolution": "720p",
"generate_audio": true
}Output
A completed run exposes its result in output. The following is the model’s saved example, not a new generation.
[
{
"poster": "https://static.sandbase.ai/examples/posters/e57c708511358a3eebeb.jpg",
"source": "ByteDance/Volcengine schema mirror",
"source_url": "https://docs.volcengine.com/docs/ark/seedance-2-0",
"url": "https://static.sandbase.ai/examples/aecae0d1-8a1a-4404-9b0f-dd68f644baa9/output/cb792559-4c7b-451f-a6b9-08617381cffc.mp4"
}
]