Bytedance Seedance 2.0 Video Edit API Documentation

Bytedance Seedance 2.0 Video Edit API Documentation

Playground

Seedance 2.0 (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.0 Video-Edit transforms an input video from a natural-language prompt — change lighting, weather, style, environment, or specific elements while preserving the subject identity, composition, and motion of the original. Built on ByteDance Seed’s unified multimodal architecture for cinematic, motion-stable output.

Key Features

• Conversational video editing — Describe the change in plain language; the model rewrites the scene while keeping the original motion intact.
• Subject and motion preservation — Faces, objects, and camera movement from the input video stay consistent through the edit.
• Multi-reference support — Optionally guide style, character identity, or audio with reference images and audio clips.
• Native audio synchronization — Generates synchronized audio in a single pass.
• Cinematic output quality — Director-level lighting, framing, and motion stability inherited from Seedance 2.0.

Parameters

How to Use

1. Upload the input video. Anything longer than 15 s is trimmed to the first 15 s automatically.
2. Write the edit prompt. Describe the change you want — the prefix Edit the input video. is added for you.
3. (Optional) Add references. Reference images can constrain style or identity; reference audio can constrain the soundtrack.
4. (Optional) Set a duration. Auto-detected from the input video length if not provided.
5. Run. Receive 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 @Image 1.”

Referencing uploaded assets

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

• “The knight in @Image 1 walks through the castle in @Image 2.”
• “Refer to @Video 1 for the camera movement only; keep its shot order.”
• “@Image 1 and @Image 2 are Character 1, voiced by @Audio 1.”

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

Billed per second across input duration + output duration. Input duration is clamped to the 2-15 s range (sources shorter than 2 s are padded with the last frame).

Examples (input 5 s, output 5 s = 10 billed seconds):

Examples (input 12 s, output 12 s = 24 billed seconds):

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, swap golden hour for blue hour.
• Object or background swaps — Replace clothing, props, or environments while keeping motion intact.
• Marketing variants — Generate quick variations of an existing ad clip without reshooting.

Pro Tips

• Be specific about what should change and what should stay the same.
• Mention lighting, mood, color palette, and camera intent for stronger output.
• Use reference images when you need to lock in a particular character or style.
• Trim your source video to the most relevant 4-15 s before uploading for the strongest edits.

Notes

• Inputs longer than 15 s are trimmed to 15 s and inputs shorter than 2 s are padded with the last frame to 2 s before editing — billing reflects the conformed length.
• Auto-detected duration matches the input length (rounded up), clamped to the 4-15 s range.
• Native audio generation is included.

Related Models

• Seedance 2.0 Image-to-Video — Generate video from a reference image and prompt.
• Seedance 2.0 Text-to-Video — Generate video from a text prompt.
• Seedance 2.0 Fast Video-Edit — Faster, cheaper variant of this model.

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",
  "video": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "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/video-edit" \
  -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

Response Parameters

Result Request Parameters

Result Response Parameters