Seedance 2.5 Reference-to-Video API

bytedance/seedance-2.5/reference-to-video

Seedance 2.5 (Reference-to-Video) generates audio-synchronized videos up to 30 seconds long from text prompts and a mix of image, video, and optional audio references. Assign each reference a clear role to carry subjects, composition, visual style, action, camera movement, pacing, or sound into a new scene, with support for up to 50 references in one generation.

Input

Prompt

932/20000

Total references0/50 · remaining 50

Reference images

0/30 · remaining 30

Add image

Reference videos

0/10 · remaining 10

Add video

Reference audios

0/10 · remaining 10

Add at least one reference image or video. Audio cannot be submitted alone.

Resolution

Duration

Aspect ratio

Generate audio

Output

Idle

Your generated video will appear here

Configure the required inputs, resolution, and duration, then run the task.

Continue with

Seedance 2.5 Text-to-Video Seedance 2.5 Image-to-Video

Examples

Use Reference Image 1 only for the fictional man's face, short wavy dark hair, navy wool coat, gray scarf, and body proportions. Use Reference Video 1 only for the single turn-and-catch motion, natural weight shift, cloth timing, and slow waist-height camera movement; do not copy the woman, her clothing, or the train platform. Use Reference Audio 1 only for rain intensity and action timing. Create one continuous five-second shot in a quiet covered ferry walkway at night. The man stands alone holding one plain cream envelope in his right hand. A brief gust loosens the envelope; he turns once, catches it against his chest, then becomes still. Preserve his referenced identity and outfit throughout. Synchronized audio: soft rain on the roof, one paper flutter, and distant water ambience. No cuts, no extra people, no dialogue, no writing on the envelope, no readable text, no logos, no products, no advertising, no watermark.

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: POSThttps://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.

Submit request

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 '{
  "model": "seedance-2.5/reference-to-video",
  "input": {
    "prompt": "Use the image for the character and the video for camera motion.",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "auto",
    "generate_audio": true,
    "reference_image_urls": [
      "https://example.com/character.jpg"
    ],
    "reference_video_urls": [
      "https://example.com/motion.mp4"
    ],
    "reference_audio_urls": [
      "https://example.com/music.mp3"
    ]
  }
}')

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

Submit response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "running",
    "created_time": "2026-08-22T10:00:00Z"
  }
}

Finished response

{
  "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.

Complete runnable example

set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "seedance-2.5/reference-to-video",
  "input": {
    "prompt": "Use the image for the character and the video for camera motion.",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "auto",
    "generate_audio": true,
    "reference_image_urls": [
      "https://example.com/character.jpg"
    ],
    "reference_video_urls": [
      "https://example.com/motion.mp4"
    ],
    "reference_audio_urls": [
      "https://example.com/music.mp3"
    ]
  }
}
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
done

Input 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	—	1–20,000 characters after trimming.
duration	integer	Yes	—	An integer from 4 through 30, inclusive.
resolution	string	Yes	—	Send 480p or 720p explicitly.
aspect_ratio	string	No	—	auto, 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16.
generate_audio	boolean	No	—	Whether to request an audio track; the playground always sends true or false.
reference_image_urls	string[]	Conditional	—	Up to 30. Images or videos must be non-empty.
reference_video_urls	string[]	Conditional	—	Up to 10; floor each video duration separately for billing.
reference_audio_urls	string[]	No	—	Up to 10. Use with at least one reference image or video; all three reference arrays may contain at most 50 items in total.

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_started
The task was accepted and is waiting to begin.
running
Generation is in progress. Continue polling the same task_id.
finished
Generation succeeded. Read every video URL from data.files[].file_url.
failed
Generation 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	Multimodal references	Images define appearance, videos guide motion, and audio can guide sound or rhythm.
Reference limits	30 / 10 / 10	Up to 30 images, 10 videos, 10 audio files, and 50 total.
Required media	Image or video	Audio cannot satisfy the visual-reference requirement.
Output	Video task	The endpoint returns an asynchronous task ID.
Resolution and duration	480p/720p · 4–30 sec	resolution and integer duration are required.
Billing basis	Output + reference seconds	With video, each reference duration is floored separately and all billing seconds use 17 or 38 credits/s.

View Seedance 2.5 Reference-to-Video API documentation

Seedance 2.5 Reference-to-Video

Seedance 2.5 Reference-to-Video combines a text prompt with image, video, and optional audio references to generate a new scene with synchronized sound. Use the prompt to assign each asset a specific role while the model carries subjects, composition, visual style, action, camera movement, pacing, and sound from those references into the generated video.

Why Choose This?

Establish appearance with imagesUse image references to guide a character, product, environment, composition, or broader art direction.
Communicate motion with videoUse reference video when action, camera movement, blocking, pace, or shot rhythm is easier to show than describe.
Guide rhythm and sound with audioUse optional audio to indicate ambience, rhythm, voice character, or the sonic mood you want the scene to follow.
Assign every reference a clear roleState which asset controls identity, style, action, camera, or sound instead of asking the model to infer every relationship.
Scale complex reference setsCombine up to 30 images, 10 videos, and 10 audio files when one scene needs several distinct sources of direction.

Parameters

Parameter	Requirement	Description
prompt	Required	String. Defines how each reference contributes to the new scene; 1–20,000 characters after trimming.
reference_image_urls	Conditional	String array of up to 30 public image URLs. Uses images to guide identity, appearance, composition, environment, or style.
reference_video_urls	Conditional	String array of up to 10 public video URLs. Uses videos to guide action, camera movement, blocking, pace, or shot rhythm.
reference_audio_urls	Optional	String array of up to 10 public audio URLs. Uses audio to guide ambience, rhythm, voice character, or sound direction.
duration	Required	Integer. Sets output length from 4 through 30 seconds, inclusive; the Playground preselects 5 seconds.
resolution	Required	String. Sets output resolution and must be sent explicitly; the Playground preselects 720p. `720p480p`
aspect_ratio	Optional	String. Controls output framing; the Playground preselects and explicitly sends auto. `auto16:99:161:121:94:33:4`
generate_audio	Optional	Boolean. Requests a generated audio track; the Playground preselects true and explicitly sends either value. `truefalse`

How to Use

Decide what each asset contributesLabel the creative job first: character identity, product appearance, environment, motion, camera path, or sound direction.
Establish the visual anchorStart with at least one image or video that defines the visible world; add audio when it should guide rhythm or sound.
Add a motion reference when neededUse a video reference for the dancer's movement and camera timing, not as an undefined instruction for the entire result.
Connect every role in the promptWrite the relationship plainly: use the first image for the performer, the video for choreography, and the audio for tempo.
Resolve conflicts before generationRemove references that disagree on identity, camera direction, lighting, or timing before configuring the output.
Configure the outputSet duration, resolution, aspect ratio, and generated audio after the reference relationships are clear.
Generate and reviewRun the request, inspect which reference roles carried into the result, then simplify or relabel competing inputs for the next pass.

Pricing

Without reference video, bill output seconds. With any reference video, output seconds plus every separately floored video duration all use the with-video rate.

Usage	Rate	Details
480p, no reference video	28 credits/output sec ($0.140/output sec)	A 5 second image-only task costs 140 credits ($0.700).
720p, no reference video	63 credits/output sec ($0.315/output sec)	A 5 second image-only task costs 315 credits ($1.58).
480p, with reference video	17 credits/billing sec ($0.085/billing sec)	A 5 second output plus 2.9 and 3.8 second videos bills 5 + 2 + 3 = 10 seconds, or 170 credits ($0.850).
720p, with reference video	38 credits/billing sec ($0.190/billing sec)	The same 10 billing seconds cost 380 credits ($1.90); unknown video duration produces only a defensible minimum.

Best Use Cases

Recurring character campaign clipsCombine character sheets, wardrobe images, and a scene prompt to create new performance clips for a recurring campaign subject.
Choreography and camera studiesPair a character image with a movement video to create a shot study for performance, blocking, camera path, or rhythm.
Product campaign variationsCombine product, environment, and style images with new action direction to create campaign video variations.
Performance and music conceptsPair performer imagery, choreography video, and an audio reference to create a music or stage-performance concept clip.

Pro Tips

Write the role beside each asset in your working prompt: character, wardrobe, product, environment, motion, camera, voice, or rhythm.
Replace 'use all references' with a relationship: keep the subject from image one, follow the motion in video one, and use audio one only for tempo.
Remove references that compete on identity, lighting, camera direction, or timing before you add more detail to the prompt.

Notes

At least one reference image or video establishes the visual input; reference audio can support that visual set.
The three reference arrays accept no more than 50 items in total across their individual limits.
After upload, every media value must resolve to a public, directly downloadable HTTP(S) URL.

Seedance 2Use the earlier Seedance family for text, frames, and multimodal references.

Kling 2.6Create video with text or image guidance and optional generated audio.

Wan 2.6Generate 1080p video through text, image, or video-guided workflows.

Seedance 2.5 Reference To Video API — Frequently asked questions

What is the Seedance 2.5 Reference-to-Video API?

Seedance 2.5 is developed by ByteDance Seed. The Reference-to-Video API combines a text prompt with at least one image or video reference to asynchronously generate a new video. You can add more image, video, or audio references, up to 50 files in total, and request synchronized audio.

How do I call the Seedance 2.5 Reference-to-Video API?

Send POST /api/generate/submit with a Bearer API key, set model to seedance-2.5/reference-to-video, and place every generation field inside input. A successful submission returns task_id immediately; the API tab and linked documentation include runnable examples.

Open the complete API documentation

How much does the Seedance 2.5 Reference-to-Video API cost?

Without reference video, 480p costs 28 credits/output second and 720p costs 63 credits/output second. With video, output seconds plus each separately floored reference duration use 17 or 38 credits/billing second. For example, a 5-second 480p output with 2.9- and 3.8-second references uses 10 billing seconds and costs 170 credits ($0.850).

What inputs does the Seedance 2.5 Reference-to-Video API accept?

The input object accepts up to 30 images, 10 videos, and 10 audio files, with no more than 50 references in total. Use at least one image or video; audio may accompany those visual references.

How do I get the generated video?

Poll GET /api/generate/status/{task_id} with task_id. On finished, read data.files[].file_url; on failed, stop and read the error. You can also provide callback_url for the terminal result.

Which Seedance 2.5 endpoint should I choose?

Choose Reference-to-Video when different assets need explicit appearance, motion, camera, or sound roles. Use Text-to-Video for language-only creation, or Image-to-Video for a required start frame and optional end frame.