Seedance 2.5 Flash Reference to Video API
seedance-2.5-flash/reference-to-videoSeedance 2.5 Flash Reference to Video turns up to 10 images, 5 videos, and 5 audio clips into 4–30 second videos with synchronized audio at 480p or 720p. Give each reference a role, such as identity, motion, or sound, to carry characters into new scenes.
Input
Drag and drop files, paste from clipboard, or provide a URL. JPEG, PNG, or WebP, up to 30 MB
1/10 files added
Drag and drop files, paste from clipboard, or provide a URL. MP4 or MOV, 2–30 seconds, up to 50 MB
1/5 files added
Drag and drop files, paste from clipboard, or provide a URL. MP3 or WAV, 2–30 seconds, up to 15 MB
1/5 files added
Output
ReadyContinue with
REST API
Quick Start
Authenticate, submit a valid input object, then use task_id to retrieve the video.
Connect to the Vidgo API
Create an API key, keep it only on your server, and send Authorization: Bearer VIDGO_API_KEY.
- Endpoint
- POST
https://api.vidgo.ai/api/generate/submit - Authentication
- Authorization: Bearer VIDGO_API_KEY
Submit one generation task
Run the smallest valid payload for this workflow. A successful submission immediately returns task_id without waiting for the video.
REQUEST_BODY=$(cat <<'JSON'
{
"model": "seedance-2.5-flash/reference-to-video",
"input": {
"prompt": "Use @Image1 for the character's look and @Video1 for the walking motion. The character crosses a sunlit plaza.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "auto",
"reference_image_urls": [
"https://example.com/character.png"
],
"reference_video_urls": [
"https://example.com/walk-motion.mp4"
],
"generate_audio": true
}
}
JSON
)
RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
printf 'API error: %s
' "$RESPONSE" >&2
exit 1
fi
printf '%s
' "$RESPONSE"Wait for the result
Query with task_id, continue for not_started/running, and stop for finished/failed. On success, read data.files[].file_url.
Track status
GET https://api.vidgo.ai/api/generate/status/{task_id}Poll about every 2 seconds, then back off gradually. Continue only for not_started or running and stop on finished or failed. You can instead add callback_url to the same top-level request contract.
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "running",
"created_time": "2026-08-22T10:00:00Z"
}
}{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "finished",
"files": [
{
"file_url": "https://storage.vidgo.ai/generated/video.mp4",
"file_type": "video"
}
],
"created_time": "2026-08-22T10:00:00Z",
"progress": 100,
"error_message": null
}
}Complete runnable example
Expand for a complete script with HTTP and business-code checks, task_id validation, polling, terminal-state handling, and a timeout boundary.
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "seedance-2.5-flash/reference-to-video",
"input": {
"prompt": "Use @Image1 for the character's look and @Video1 for the walking motion. The character crosses a sunlit plaza.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "auto",
"reference_image_urls": [
"https://example.com/character.png"
],
"reference_video_urls": [
"https://example.com/walk-motion.mp4"
],
"generate_audio": true
}
}
JSON
)
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
printf 'Timed out after 600 seconds
' >&2
exit 1
fi
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
exit 1
fi
case "$STATUS" in
finished)
printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
break
;;
failed)
printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
exit 1
;;
not_started|running)
sleep "$POLL_DELAY"
if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
doneInput parameters
These are the fields accepted inside input. The request example shows the required top-level model field.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| prompt | string | Yes | — | Text prompt describing the video. |
| duration | integer | Yes | — | An integer from 4 through 30, inclusive. |
| reference_image_urls | string[] | No | — | Up to 10; send reference images, reference videos, or both. |
| reference_video_urls | string[] | No | — | Up to 5 MP4 or MOV files, each 2–30 seconds, up to 30 seconds in total; each video's whole seconds are added to billing. |
| reference_audio_urls | string[] | No | — | Up to 5 MP3 or WAV files, each 2–30 seconds, up to 30 seconds in total, paired with reference images or videos. |
| resolution | string | No | 720p | 480p or 720p. |
| aspect_ratio | string | No | — | auto, 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16. |
| generate_audio | boolean | No | — | Whether to generate synchronized audio; the rate is the same either way. |
Response Fields
Submission returns task identity immediately. Status responses add progress, every output file, or a failure message.
| Field | Type | Description |
|---|---|---|
| code | integer | Application result code; successful responses use 0 or 200. |
| message | string | Human-readable message or error detail when present. |
| data.task_id | string | Task ID used in the status endpoint path. |
| data.status | string | not_started, running, finished, or failed. |
| data.created_time | string | Task creation time in date-time format. |
| data.progress | integer | 0–100 progress when reported by the provider. |
| data.files[] | array | All output files from a successful task, in response order. |
| data.files[].file_url | string | Public URL for a generated video. |
| data.files[].file_type | string | File type, such as video. |
| data.error_message | string | null | Failure detail when status is failed. |
Task Lifecycle
Treat not_started and running as non-terminal states. finished and failed are terminal alternatives; stop polling when either is returned.
not_startedThe task was accepted and is waiting to begin.
runningGeneration is in progress. Continue polling the same task_id.
finishedGeneration succeeded. Read every video URL from data.files[].file_url.
failedGeneration stopped with an error. Read data.error_message and stop polling.
Polling and Errors
- AuthenticationA 401 response means the Bearer API key is missing or invalid. Correct it before retrying.
- ValidationA 400 response identifies an invalid field, unsupported media key, or insufficient credit balance. Correct the request before resubmitting.
- Network and timeoutA transport failure is different from a failed task. Retry status checks with a bounded timeout before deciding that the task failed.
- Polling intervalStart around every 2 seconds and increase the interval gradually for a long-running task.
- Terminal statesContinue only for not_started or running. Stop immediately on finished or failed.
- Callback optionProvide callback_url at the request top level to receive the final flat task object; polling remains available if delivery fails.
Endpoint limits
| Specification | Value | Details |
|---|---|---|
| Input mode | Reference images / videos / audio | Up to 10 images, 5 videos, and 5 audio clips; at least one image or video. |
| Output | Video task | The endpoint returns an asynchronous task ID; the video can include synchronized audio. |
| Resolution | 480p / 720p | Defaults to 720p. |
| Duration | 4–30 seconds | Every whole-second value in the inclusive range. |
| Aspect ratio | Auto + 6 fixed | auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16. |
| Billing basis | Output + reference-video seconds | Standard 18.5 / 41 credits/s; with reference video 11.5 / 25.5 credits per billing second (480p / 720p). |
Related Models
Seedance 2.5 Flash Reference to Video API frequently asked questions
What is the Seedance 2.5 Flash Reference to Video API?
Seedance 2.5 Flash Reference to Video is a ByteDance Seed model for generating video from reference images, videos, and audio. It combines up to 10 images, 5 videos, and 5 audio clips into 4–30 second clips at 480p or 720p with optional synchronized audio. Built on the Seedance 2.5 multimodal reference workflow, it carries identity, motion, camera behavior, and sound from the references you assign into a new scene. You can call it programmatically or try it from the playground above.
How many references does Seedance 2.5 Flash Reference to Video accept?
Each request accepts up to 10 reference images, 5 reference videos, and 5 reference audio clips. Include at least one image or video; reference audio is used together with them. For more references, Seedance 2.5 Reference to Video accepts up to 50 files.
How are reference videos billed in Seedance 2.5 Flash Reference to Video?
When a request includes reference videos, billing seconds equal the output duration plus each reference video's whole seconds, at 11.5 credits per second for 480p or 25.5 for 720p. A 10-second 720p output with a 10-second reference video bills 20 seconds: 510 credits ($2.55). Requests guided by images or audio use the standard 18.5 and 41 credits per output second.
How long can reference videos be in Seedance 2.5 Flash Reference to Video?
Each reference video or audio clip runs 2–30 seconds, and reference videos can add up to 30 seconds in total, as can reference audios. Trim each clip to the motion or sound you need; shorter reference videos also lower the billed seconds.
Can Seedance 2.5 Flash Reference to Video use audio as a reference?
Yes. Add up to 5 reference audio clips together with at least one reference image or video. Describe in the prompt what the audio should guide, such as the music, ambience, or the timing of an action.
How do I assign roles to references in Seedance 2.5 Flash Reference to Video?
Refer to each asset in upload order with @Image1, @Video1, and @Audio1, numbered separately for each type. State what each one contributes, for example take the walking motion from Reference Video 1 and describe the new background in the prompt.
When should I choose Seedance 2.5 Reference to Video over the Flash version?
Choose Seedance 2.5 Reference to Video when a shot needs 1080p output or more than 10 images, 5 videos, or 5 audio clips; it accepts up to 30, 10, and 10. Flash uses the same fields at lower rates for 480p and 720p work.
Which aspect ratios does Seedance 2.5 Flash Reference to Video support?
Choose auto or one of six fixed ratios: 21:9, 16:9, 4:3, 1:1, 3:4, and 9:16. Set a fixed ratio when the output format differs from your references, such as a 9:16 social cut built from landscape footage.















