Bytedance Seedance 2.0 Fast Reference To Video API Documentation

Bytedance Seedance 2.0 Fast Reference To Video API Documentation

Playground

Seedance 2.0 Fast 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.0 Fast Reference-to-Video guides generation with your own reference images, videos, and audio. Keep characters, products, scenes, motion, and soundtrack consistent while a prompt directs the new shot, with native synchronized audio and director-style control over camera, lighting, and pacing. The same reference inputs are also accepted by Seedance 2.0 Fast Text-to-Video.

Key Features

• Speed-optimized generation Faster processing for quick turnaround on video projects, perfect for iteration and prototyping.

• 33% lower cost $0.80 per 5 seconds vs $1.20 for the standard version — ideal for high-volume production.

• Unified multimodal architecture Same Seedance 2.0 foundation handling text, image, audio, and video inputs.

• Native audio-visual synchronization Generates video with synchronized audio in a single pass.

• Director-level control Camera movement, lighting, shadows, and character performance controlled through prompts.

• Strong motion stability Coherent motion with stable subjects and fluid transitions.

Parameters

How to Use

1. Write your prompt — describe the scene with cinematic detail.
2. Select aspect ratio — 16:9 for widescreen, 9:16 for vertical, 4:3 or 3:4 for classic formats.
3. Set duration — choose any duration from 4 to 15 seconds.
4. Optionally add references — provide reference images, videos, or audios for style guidance.
5. Run — submit and download your video.

Pricing

Pricing is calculated upfront using your selected duration, plus reference-video charges when applicable.

Without reference videos

Output-only pricing:

Prices scale linearly with requested generation duration from 4 to 15 seconds.

With reference videos

Normalized reference-video duration and requested generation duration use the same per-second rate:

Each reference video is normalized to at least 2 seconds, each clip and the combined input are capped at 15 seconds, and the normalized combined input duration is rounded up to a whole second for billing.

Example: 5 seconds of normalized reference input plus 5 seconds of output costs $0.65 at 480p, $1.30 at 720p, $3.25 at 1080p, or $6.50 at 4k.

Best Use Cases

• Rapid Prototyping — Quickly iterate on concepts before committing to the standard version.
• High-Volume Production — Cost-effective generation for large content libraries.
• Social Media Content — Fast turnaround for short-form video needs.
• A/B Testing — Generate multiple variations efficiently to find the best creative direction.

Pro Tips

• Use Fast for iteration and testing, switch to standard Seedance 2.0 for final quality.
• Write prompts like a film director — include lighting, camera angles, and mood.
• Start with 5s to iterate, then extend once the look is right.

Notes

• Native audio generation included.
• Duration range: 4–15 seconds, in whole seconds.
• For highest quality output, consider the standard Seedance 2.0.

Related Models

• Seedance 2.0 Reference-to-Video — Standard version with highest quality.
• Seedance 2.0 Fast Image-to-Video — Fast image-guided video generation.
• Seedance 2.0 Image-to-Video — Standard image-guided video generation.

Notice: Use @Image 1, @Image 2, @Audio 1, etc. to reference your uploaded assets. Number each type separately, in upload order.

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,
  "enable_web_search": false,
  "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.0-fast/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