Alibaba Wan 3.0 Prime Video Edit API Documentation

Alibaba Wan 3.0 Prime Video Edit API Documentation

Playground

Wan 3.0 Prime 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 Prime Video-Edit edits an existing video with natural-language instructions. Upload a source video, describe the changes you want, and optionally provide reference images or audio for additional guidance.

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

Why Choose This?

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

• Multimodal reference guidance
  Add reference images and audio clips to guide visual appearance, characters, objects, or sound-related context.

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

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

• Audio control
  Generate audio for the edited video or preserve the original source audio when available.

• Prompt expansion
  Enable automatic prompt expansion when you want the editing instruction optimized before generation.

Parameters

How to Use

1. Upload a source video — Provide the video you want to edit.
2. Write an editing prompt — Clearly describe what should change and what should remain unchanged.
3. Add reference images optional — Provide up to 10 images for additional visual guidance.
4. Add reference audio optional — Provide up to 5 audio clips when audio reference guidance is useful.
5. Set output duration optional — Choose 2–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 source audio 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 results, 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 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.

Example Costs

Best Use Cases

• Prompt-based video editing — Modify existing footage using natural-language instructions.
• Appearance changes — Change clothing, objects, colors, materials, or visual styling.
• Scene transformation — Replace or modify backgrounds, environments, lighting, and atmosphere.
• Reference-guided editing — Use images or audio to guide characters, objects, appearance, or creative direction.
• Creative video workflows — Transform existing footage into new visual concepts.
• Marketing and social content — Produce edited short-form clips for ads, campaigns, and social media.

Pro Tips

• Clearly describe both what should change and what should remain unchanged.
• Refer to uploaded assets consistently as Video 1, Image 1, or Audio 1.
• Use reference images when character, object, appearance, or style consistency matters.
• Keep reference audio focused on the sound or performance you want to guide.
• Use 480p for lower-cost iteration before generating higher-resolution results.
• Remember that both processed input duration and output duration contribute to the final price.
• Set a fixed seed when comparing 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 automatically selected 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 Prime Image-to-Video — Generate Prime video from a first-frame image with optional last-frame guidance.
• 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-prime/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