Bytedance Seedance 2.5 Video Edit API Documentation

Bytedance Seedance 2.5 Video Edit API Documentation

Playground

Seedance 2.5 (Video-Edit) edits an input video from a natural-language prompt. The reference video drives subject identity, composition, and motion while the model rewrites lighting, style, weather, environment, or specific elements as instructed. Built on ByteDance Seed’s unified multimodal architecture for cinematic, motion-stable output. Ready-to-use REST API, best performance, no coldstarts, affordable pricing.

Features

Seedance 2.5 Video Edit transforms an input video with natural-language instructions. Change lighting, weather, style, environment, or specific visual elements while preserving the subject identity, composition, and motion of the original clip.

Why Choose This?

• Conversational video editing
  Describe the change in plain language, and the model applies the edit while keeping the original motion structure.

• Subject and motion preservation
  Preserve faces, objects, camera movement, and scene composition from the input video.

• Multi-reference support
  Optionally guide style, character identity, or audio direction with reference images and audio clips.

• Native audio synchronization
  Generate synchronized audio together with the edited video output.

• Cinematic output quality
  Create polished edits with strong lighting, framing, and motion stability.

Parameters

The output duration and aspect ratio follow the input video automatically.

How to Use

1. Upload the input video — Provide the source video to edit. Videos longer than 30 seconds are trimmed automatically.
2. Write the edit prompt — Describe the change you want to apply to the input video.
3. Add references optional — Use reference images for style or identity guidance, and reference audio for soundtrack direction.
4. Choose resolution — Select 480p, 720p, 1080p, or 4k.
5. Submit — Generate the edited video with synchronized audio.

Writing Effective Prompts

Editing keeps your source video and changes only what you name. Be precise about the scope, and describe the change as from A to B.

State the change plainly

Name exactly what to add, remove, or modify — and use an editing trigger word (add, remove, replace, change to, modify) so the intent is unambiguous.

• “Replace the man’s coffee cup with a book, keep everything else unchanged.”
• “Remove the subtitles.”
• “Change the background from a city street to a snowy forest.”

Use timestamps for partial edits

Confine a change to a time range so the rest of the clip is untouched.

• “From 4-6s, change the man’s action from drinking coffee to waving; leave the rest unchanged.”

Reference images for edits

Attach images to specify a replacement, and bind each explicitly (see below).

• “Replace the woman on the right with the person in @image1.”

Referencing uploaded assets

When you attach images, videos, or audio, bind each one explicitly in the prompt by its upload order — @image1, @video1, @audio1 — and say what it’s for. Don’t rely on labels drawn inside the image itself.

• “The knight in @image1 walks through the castle in @image2.”
• “Refer to @video1 for the camera movement only; keep its shot order.”
• “@image1 and @image2 are Character 1, voiced by @audio1.”

When a reference is already accurate, just point to it — no need to re-describe it in detail.

Audio edits

You can add, remove, or modify audio too.

• “Translate the dialogue to Spanish, keep lip movements matched, no subtitles.”
• “Remove the background music; keep only ambient and action sounds.”

Negative control

Positive descriptions work best, but you can suppress subtitles and audio:

• “No subtitles.”
• “No BGM — ambient and action sounds only.”
• “No audio.”

Weak vs. strong

Pricing

Pricing is based on the combined duration of input duration + output duration. Input duration is handled within the 4–30s range before pricing.

Example Costs: 5s Input + 5s Output

Example Costs: 12s Input + 12s Output

Best Use Cases

• Style and look transfer — Re-grade footage into a cinematic, vintage, animated, or stylized look.
• Lighting and weather edits — Change time of day, add rain or snow, or shift the atmosphere of a scene.
• Object or background changes — Replace clothing, props, or environments while keeping the original motion intact.
• Marketing variants — Generate fast variations of an existing ad clip without reshooting.
• Reference-guided editing — Use reference images or audio to guide style, identity, or soundtrack direction.

Pro Tips

• Be specific about what should change and what should stay the same.
• Mention lighting, mood, color palette, environment, and camera intent for stronger output.
• Use reference images when you need to preserve a character, product, outfit, or visual style.
• Use reference audio when soundtrack or voice style matters.
• Trim your source video to the most relevant 4–30 seconds before uploading.
• Use asset tags such as @image1, @image2, and @audio1 to reference uploaded assets in the prompt.

Related Models

• Seedance 2.5 Image-to-Video — Generate video from a start image and prompt.
• Seedance 2.5 Video Extend — Extend an existing video with a new generated segment.
• Seedance 2.0 Video Edit — Previous-generation Seedance video editing model.

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",
  "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/video-edit" \
  -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