Bytedance Seedance 2.5 Flash Reference To Video API Documentation

Bytedance Seedance 2.5 Flash Reference To Video API Documentation

Playground

Seedance 2.5 Flash Reference to Video creates cinematic videos with native audio from your own reference images, videos, and audio, keeping characters, products, motion, and sound consistent while a prompt directs the new shot. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Seedance 2.5 Flash Reference-to-Video guides generation with your own reference images, videos and audio, so characters, products, scenes, motion and soundtrack stay consistent. Clips of 4 to 30 seconds come with native, synchronized audio, at 480p or 720p.

Why Choose This?

• Native audio
  Dialogue, sound effects and ambience are generated together with the picture.

• Director-style prompt control
  Direct camera movement, lighting, performance, atmosphere and pacing through the prompt.

• Up to 30 seconds
  Generate clips from 4 to 30 seconds in one request.

• 480p and 720p output
  Choose the resolution that fits the job.

Parameters

How to Use

1. Write your prompt: describe the subject, action, camera movement, lighting and mood.
2. Set duration and resolution: 4–30 seconds, 480p or 720p.
3. Add references (optional): use reference images, videos and audio, and bind each one in the prompt by upload order.
4. Submit and retrieve the output URL.

Pricing

Output only

Prices scale linearly with output duration from 4 to 30 seconds.

With reference videos

Reference-video duration and output duration use the same per-second rate:

Each reference video is counted as at least 2 seconds, each clip and the combined input are capped at 30 seconds, and the combined input duration is rounded up to a whole second.

Example: 5 seconds of reference input plus 5 seconds of output costs $0.75 at 480p or $1.50 at 720p.

Best Use Cases

• Ad and social creative: test concepts and produce short clips in volume.
• Concept visualization: turn ideas into motion previews for pitching and storyboarding.
• Audio-driven scenes: clips with synchronized sound for ambience, music or narrative moments.

Pro Tips

• Write prompts like a shot list: subject, action, camera, lighting, mood.
• Use 16:9 for widescreen and 9:16 for vertical social content.
• Start with a short duration while testing a prompt, then lengthen once the direction works.
• Bind reference media explicitly in the prompt, for example @Image 1, @Video 1, @Audio 1.

Related Models

• Seedance 2.5 Text-to-Video: 480p to 4K output.
• Seedance 2.5 Image-to-Video: generate video from a start image.
• Seedance 2.5 Video Edit: edit an existing video with a prompt.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "generate_audio": true
}
JSON
)

# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 60 \
  -X POST "https://api.wavespeed.ai/api/v3/bytedance/seedance-2.5-flash/reference-to-video" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"); then
  printf 'Submit failed. %s\n' "${CHECK}" >&2
  exit 1
fi

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id. %s\n' "${CHECK}" >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
  # Transient errors (429, 5xx) are retried, honoring Retry-After.
  HTTP_CODE=$(curl --silent --show-error --fail-with-body \
    --connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
    --output "${BODY_FILE}" --write-out '%{http_code}' \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
  case "${HTTP_CODE}" in
    2??) ;;
    000|429|5??)  # dropped connection or temporary error: keep polling
      printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      sleep 10; continue ;;
    *) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      cat "${BODY_FILE}" >&2; exit 1 ;;
  esac
  RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted)
      printf 'Task %s ended with status %s\n' "${PREDICTION_ID}" "${STATUS}" >&2
      printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.

Response Parameters

Result Request Parameters

Result Response Parameters