Bytedance Seedance 2.5 Motion Control API Documentation

Bytedance Seedance 2.5 Motion Control API Documentation

Playground

Transfer the motion of a reference video onto a character image with Seedance 2.5. The character from your image performs the same movements, gestures and camera motion as the video, in 480p, 720p or 1080p for up to 30 seconds. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Seedance 2.5 Motion Control transfers the motion of a reference video onto a character image. The character in your image performs the same movements, gestures, timing and camera motion as the person in the video, while the background, framing and pacing of the video are kept.

Why Choose This?

• Faithful motion transfer - Dance, gestures, walking, turning and full-body action carry over from the reference video to your character.

• Character identity from one image - Face, hairstyle and clothing come from the image you provide.

• Video-driven timing and camera - Duration, framing and camera movement follow the reference video, so the result drops straight into your cut.

• Native audio - Generate synchronized audio, or keep the original soundtrack of the reference video.

• Up to 1080p, up to 30 seconds - Choose 480p for fast previews or 1080p for final delivery.

Parameters

The output duration and aspect ratio follow the reference video.

How to Use

1. Upload the character image — Choose the person or character that should perform the motion.
2. Upload the motion video — Provide a clip of the movement you want to copy, 4 to 30 seconds.
3. Add direction if needed — Leave prompt empty, or add a short instruction.
4. Choose resolution — Select 480p, 720p, or 1080p.
5. Submit — Generate the video. API requests are asynchronous; poll the result endpoint until the video URL is available.

Tips for Better Results

• Use a motion video with one clearly visible performer and a stable camera.
• Pick a character image whose pose and framing are close to the first frame of the video (full body for full-body motion).
• Keep the character’s face and clothing clearly visible in the image.
• Avoid heavily occluded limbs in the reference video; fast, complex motion is easier to follow when the performer stays in frame.

Pricing

Charges are based on the duration of the reference video, rounded up to whole seconds, with a 4-second minimum and a 30-second maximum.

For example, a 3.2-second clip is billed as 4 seconds, and a 8.04-second clip is billed as 9 seconds.

Related Models

• Seedance 2.5 Talking Avatar - animate a portrait from an audio recording.
• 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'
{
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "video": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
  "resolution": "720p",
  "generate_audio": true
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/bytedance/seedance-2.5/motion-control" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

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
' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

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

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters