Alibaba Wan 3.0 Video Edit API Documentation

Alibaba Wan 3.0 Video Edit API Documentation

Playground

Wan 3.0 Video Edit edits existing videos with text prompts and optional reference images or audio, supporting prompt-guided scene changes, visual refinements, and multimodal video editing. Inputs longer than 15 seconds are trimmed to the first 15 seconds, with output aspect ratio automatically matched to the input video. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Wan 3.0 Video Edit edits an existing video with natural-language instructions. Provide a source video, describe the changes you want, and optionally add reference images or audio to guide the result.

The source video is processed as video reference input, while the prompt controls the requested edit, motion, appearance, scene changes, and other transformations.

Why Choose This?

• Prompt-based video editing
  Edit an existing video using natural-language instructions.

• Multimodal reference guidance
  Add reference images and audio to provide additional visual or audio context.

• Flexible output duration
  Generate an edited result from 2 to 15 seconds.

• 480p, 720p, and 1080p output
  Choose the resolution that fits your quality and cost requirements.

• Audio control
  Generate audio with the edited video or preserve the source audio track when available.

• Prompt expansion
  Enable prompt expansion when you want the input instruction optimized automatically.

Parameters

How to Use

1. Upload a source video — Provide the video you want to edit.
2. Write an editing prompt — Describe the requested changes clearly.
3. Add reference images optional — Provide up to 10 images when additional visual guidance is useful.
4. Add reference audio optional — Provide up to 5 audio clips when audio reference guidance is needed.
5. Set output duration optional — Choose a duration from 2 to 15 seconds, or omit it to follow the processed source duration.
6. Choose resolution — Select 480p, 720p, or 1080p.
7. Configure audio — Keep generate_audio=true for generated audio, or disable it to preserve the source audio track when available.
8. Configure prompt expansion optional — Enable enable_prompt_expansion when you want the instruction expanded automatically.
9. Set seed optional — Use a fixed seed for reproducible generation, or -1 for random generation.
10. Submit — Generate the edited video and retrieve the output.

Pricing

Pricing is based on the normalized input video duration plus the output video duration.

The input video duration is rounded up to the next whole second and limited to 1–15 seconds.

If duration is omitted, the output duration follows the normalized input duration, with a minimum of 2 seconds and a maximum of 15 seconds.

Billing Examples

Best Use Cases

• Prompt-based video editing — Modify an existing video using natural-language instructions.
• Appearance changes — Adjust clothing, objects, environments, colors, or visual styling.
• Scene transformation — Change backgrounds, environments, lighting, or atmosphere.
• Reference-guided editing — Use images or audio to guide the desired result.
• Creative video workflows — Transform existing footage into new visual concepts.
• Short-form content editing — Create edited clips for social media, advertising, and creative production.

Pro Tips

• Describe exactly what should change and what should remain unchanged.
• Refer to supplied assets clearly as Video 1, Image 1, or Audio 1.
• Use reference images when appearance, character, object, or style consistency matters.
• Keep reference audio focused on the sound or performance you want to guide.
• Use 480p for lower-cost testing before moving to higher resolutions.
• Remember that both the processed input duration and output duration contribute to the final price.
• Set a fixed seed when comparing different prompts or parameter changes.

Notes

• prompt and video are required.
• Source videos longer than 15 seconds are trimmed to the first 15 seconds.
• Source videos shorter than 1 second are normalized to at least 1 second.
• Output duration supports 2–15 seconds.
• If duration is omitted, it follows the normalized source duration with a minimum of 2 seconds.
• Up to 10 reference images are supported.
• Up to 5 reference audio clips are supported, with a combined normalized maximum of 15 seconds.
• Output aspect ratio is selected automatically from the input video’s display dimensions.
• Nonstandard source aspect ratios are mapped to the nearest supported ratio and may change framing.
• generate_audio=false preserves the source audio track when one is available.

Related Models

• Wan 3.0 Reference-to-Video — Generate video using multimodal reference guidance.
• Wan 3.0 Image-to-Video — Generate video from a first-frame image.
• Wan 3.0 Text-to-Video — Generate video directly from a text 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",
  "video": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
  "resolution": "720p",
  "generate_audio": true,
  "enable_prompt_expansion": false
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/alibaba/wan-3.0/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