Skip to content

About

Wan 3.0 API — Python wrapper for Wan 3.0 and Wan 3.0 Prime on WaveSpeedAI: text-to-video, image-to-video, reference-to-video, video editing, video extension.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Wan 3.0 API — Python wrapper

Call Wan 3.0 and Wan 3.0 Prime from Python with one function per endpoint: text-to-video, image-to-video, reference-to-video, video editing, video extension. Built on the official wavespeed SDK and the WaveSpeedAI hosted API — no GPU, pay per generation.

Wan 3.0 API Try in browser

Quick start

pip install git+https://github.com/WaveSpeedAI/wan-3.0-api.git
export WAVESPEED_API_KEY="your-api-key"   # https://wavespeed.ai/accesskey
import wan_api

urls = wan_api.text_to_video(
    prompt="A slow cinematic dolly shot through a rain-soaked neon night market, reflections on the pavement",
)
print(urls[0])

Every function waits for the generation to finish and returns a list of output URLs. Optional arguments you leave out are not sent, so the API defaults apply. Inputs such as images, videos and audio are passed as URLs; use wan_api.upload("local-file") to get a URL for a local file.

Endpoints

Function Model Type
text_to_video() alibaba/wan-3.0/text-to-video text-to-video
image_to_video() alibaba/wan-3.0/image-to-video image-to-video
reference_to_video() alibaba/wan-3.0/reference-to-video reference-to-video
video_edit() alibaba/wan-3.0/video-edit video-to-video
video_extend() alibaba/wan-3.0/video-extend video-extend
prime_text_to_video() alibaba/wan-3.0-prime/text-to-video text-to-video
prime_image_to_video() alibaba/wan-3.0-prime/image-to-video image-to-video
prime_reference_to_video() alibaba/wan-3.0-prime/reference-to-video reference-to-video
prime_video_edit() alibaba/wan-3.0-prime/video-edit video-to-video
prime_video_extend() alibaba/wan-3.0-prime/video-extend video-extend

Each model page has a playground, live pricing and copy-paste API snippets. Prices are per generation and depend on the settings you choose; check a request before running it with wavespeed price <model> from the CLI.

Parameters

text_to_video

alibaba/wan-3.0/text-to-video — Alibaba WAN 3.0 Text-to-Video generates videos from text prompts with flexible 2-30 second duration, resolution, aspect ratio, audio, and deep-thinking controls.

Parameter Type Required Default Allowed Description
prompt str yes The positive prompt for the generation.
resolution str "720p" 480p, 720p, 1080p The resolution of the generated video.
aspect_ratio str "16:9" 16:9, 9:16, 1:1, 4:3, 3:4 The aspect ratio of the generated video.
duration int 5 2–30 The duration of the generated media in seconds (2-30s).
enable_prompt_expansion bool false If set to true, the prompt optimizer will be enabled.
generate_audio bool true Whether to include audio in the generated video.
seed int The random seed to use for the generation. -1 means a random seed will be used.

image_to_video

alibaba/wan-3.0/image-to-video — Alibaba WAN 3.0 Image-to-Video converts a first-frame image into a video with optional last-frame guidance, flexible 2-30 second duration, resolution, aspect ratio, audio, and deep-thinking controls.

Parameter Type Required Default Allowed Description
prompt str yes The positive prompt for the generation.
image str yes The first frame image for generating the video. Supports URL or Base64-encoded data.
last_image str The last frame image for generating the video (optional). Supports URL or Base64-encoded data.
resolution str "720p" 480p, 720p, 1080p The resolution of the generated video.
aspect_ratio str 16:9, 9:16, 1:1, 4:3, 3:4 The aspect ratio of the generated video. If not specified, it is adapted to the input image.
duration int 5 2–30 The duration of the generated media in seconds (2-30s).
enable_prompt_expansion bool false If set to true, the prompt optimizer will be enabled.
generate_audio bool true Whether to include audio in the generated video.
seed int The random seed to use for the generation. -1 means a random seed will be used.

reference_to_video

alibaba/wan-3.0/reference-to-video — Alibaba WAN 3.0 Reference-to-Video combines reference images, videos, and audio with prompts to create coherent videos with flexible 2-30 second duration, resolution, aspect ratio, audio, and deep-thinking controls.

Parameter Type Required Default Allowed Description
prompt str yes The positive prompt for the generation. Refer to reference media as Image 1, Video 1, Audio 1, ..., numbered per type in array order.
reference_images List[str] up to 10 items Array of reference image URLs (up to 10). At least one reference image, video, or audio is required.
reference_videos List[str] up to 5 items Array of reference video URLs (up to 5). Each video must be MP4 or MOV, 1-15 seconds, 240-4096 pixels on each side, no more than 8:1 aspect ratio, and no more than 100 MB. Total input video duration must not exceed 15 seconds. Supports HTTP/HTTPS URLs and temporary OSS URLs.
reference_audios List[str] up to 5 items Array of reference audio URLs (up to 5). Total input audio duration must not exceed 15 seconds.
resolution str "720p" 480p, 720p, 1080p The resolution of the generated video.
aspect_ratio str "16:9" 16:9, 9:16, 1:1, 4:3, 3:4 The aspect ratio of the generated video.
duration int 5 2–30 The duration of the generated video in seconds. Default: 5. Without video input, use an integer from 2 to 30. When reference videos are provided, the total input video duration plus the generated output duration must not exceed 30 seconds.
enable_prompt_expansion bool false If set to true, the prompt optimizer will be enabled.
generate_audio bool true Whether to include audio in the generated video.
seed int The random seed to use for the generation. -1 means a random seed will be used.

video_edit

alibaba/wan-3.0/video-edit — Wan 3.0 Video-Edit edits an input video using a text prompt and optional reference images and audio. Inputs longer than 15 seconds are trimmed to the first 15 seconds. Output aspect ratio is explicitly selected from the input display dimensions automatically.

Parameter Type Required Default Allowed Description
prompt str yes Describe the edit you want applied to the input video.
video str yes URL of the input video to edit. Videos longer than 15s are trimmed to 15s.
reference_images List[str] up to 10 items Optional reference images to guide the edit (up to 10).
reference_audios List[str] up to 5 items Array of reference audio URLs (up to 5). Total input audio duration must not exceed 15 seconds.
resolution str "720p" 480p, 720p, 1080p Output video resolution.
duration int 2–15 Output duration (2-15 seconds). When omitted, follows the input duration rounded up and clamped to 2-15 seconds.
generate_audio bool true Whether to generate native audio for the edited output. Defaults to true. When set to false, the input video's audio track is preserved on the output instead.
enable_prompt_expansion bool false If set to true, the prompt optimizer will be enabled.
seed int The random seed to use for the generation. -1 means a random seed will be used.

video_extend

alibaba/wan-3.0/video-extend — Wan 3.0 Video Extend continues a video from its final frame and appends a newly generated 2-30 second segment. Inputs longer than 120 seconds retain their last 120 seconds. Supports 480p, 720p, and 1080p output.

Parameter Type Required Default Allowed Description
prompt str yes The positive prompt for the generation.
video str yes Source video URL. Inputs longer than 120 seconds are automatically trimmed to their last 120 seconds before extension.
last_image str The last frame image for generating the video (optional). Supports URL or Base64-encoded data.
resolution str "720p" 480p, 720p, 1080p The resolution of the generated video.
duration int 5 2–30 Length in seconds of the NEW segment to append (2-30). Final output duration is the retained source duration plus this value.
enable_prompt_expansion bool false If set to true, the prompt optimizer will be enabled.
generate_audio bool true Generate audio for the new segment. Existing source audio is preserved.
seed int The random seed to use for the generation. -1 means a random seed will be used.

prime_text_to_video

alibaba/wan-3.0-prime/text-to-video — Alibaba WAN 3.0 Prime Text-to-Video generates videos from text prompts with flexible 2-30 second duration, resolution, aspect ratio, audio, and deep-thinking controls.

Parameter Type Required Default Allowed Description
prompt str yes The positive prompt for the generation.
resolution str "720p" 480p, 720p, 1080p The resolution of the generated video.
aspect_ratio str "16:9" 16:9, 9:16, 1:1, 4:3, 3:4 The aspect ratio of the generated video.
duration int 5 2–30 The duration of the generated media in seconds (2-30s).
enable_prompt_expansion bool false If set to true, the prompt optimizer will be enabled.
generate_audio bool true Whether to include audio in the generated video.
seed int The random seed to use for the generation. -1 means a random seed will be used.

prime_image_to_video

alibaba/wan-3.0-prime/image-to-video — Alibaba WAN 3.0 Prime Image-to-Video converts a first-frame image into a video with optional last-frame guidance, flexible 2-30 second duration, resolution, aspect ratio, audio, and deep-thinking controls.

Parameter Type Required Default Allowed Description
prompt str yes The positive prompt for the generation.
image str yes The first frame image for generating the video. Supports URL or Base64-encoded data.
last_image str The last frame image for generating the video (optional). Supports URL or Base64-encoded data.
resolution str "720p" 480p, 720p, 1080p The resolution of the generated video.
aspect_ratio str 16:9, 9:16, 1:1, 4:3, 3:4 The aspect ratio of the generated video. If not specified, it is adapted to the input image.
duration int 5 2–30 The duration of the generated media in seconds (2-30s).
enable_prompt_expansion bool false If set to true, the prompt optimizer will be enabled.
generate_audio bool true Whether to include audio in the generated video.
seed int The random seed to use for the generation. -1 means a random seed will be used.

prime_reference_to_video

alibaba/wan-3.0-prime/reference-to-video — Alibaba WAN 3.0 Prime Reference-to-Video combines reference images, videos, and audio with prompts to create coherent videos with flexible 2-30 second duration, resolution, aspect ratio, audio, and deep-thinking controls.

Parameter Type Required Default Allowed Description
prompt str yes The positive prompt for the generation. Refer to reference media as Image 1, Video 1, Audio 1, ..., numbered per type in array order.
reference_images List[str] up to 10 items Array of reference image URLs (up to 10). At least one reference image, video, or audio is required.
reference_videos List[str] up to 5 items Array of reference video URLs (up to 5). Each video must be MP4 or MOV, 1-15 seconds, 240-4096 pixels on each side, no more than 8:1 aspect ratio, and no more than 100 MB. Total input video duration must not exceed 15 seconds. Supports HTTP/HTTPS URLs and temporary OSS URLs.
reference_audios List[str] up to 5 items Array of reference audio URLs (up to 5). Total input audio duration must not exceed 15 seconds.
resolution str "720p" 480p, 720p, 1080p The resolution of the generated video.
aspect_ratio str "16:9" 16:9, 9:16, 1:1, 4:3, 3:4 The aspect ratio of the generated video.
duration int 5 2–30 The duration of the generated video in seconds. Default: 5. Without video input, use an integer from 2 to 30. When reference videos are provided, the total input video duration plus the generated output duration must not exceed 30 seconds.
enable_prompt_expansion bool false If set to true, the prompt optimizer will be enabled.
generate_audio bool true Whether to include audio in the generated video.
seed int The random seed to use for the generation. -1 means a random seed will be used.

prime_video_edit

alibaba/wan-3.0-prime/video-edit — Wan 3.0 Prime Video-Edit edits an input video using a text prompt and optional reference images and audio. Inputs longer than 15 seconds are trimmed to the first 15 seconds. Output aspect ratio is explicitly selected from the input display dimensions automatically.

Parameter Type Required Default Allowed Description
prompt str yes Describe the edit you want applied to the input video.
video str yes URL of the input video to edit. Videos longer than 15s are trimmed to 15s.
reference_images List[str] up to 10 items Optional reference images to guide the edit (up to 10).
reference_audios List[str] up to 5 items Array of reference audio URLs (up to 5). Total input audio duration must not exceed 15 seconds.
resolution str "720p" 480p, 720p, 1080p Output video resolution.
duration int 2–15 Output duration (2-15 seconds). When omitted, follows the input duration rounded up and clamped to 2-15 seconds.
generate_audio bool true Whether to generate native audio for the edited output. Defaults to true. When set to false, the input video's audio track is preserved on the output instead.
enable_prompt_expansion bool false If set to true, the prompt optimizer will be enabled.
seed int The random seed to use for the generation. -1 means a random seed will be used.

prime_video_extend

alibaba/wan-3.0-prime/video-extend — Wan 3.0 Prime Video Extend continues a video from its final frame and appends a newly generated 2-30 second segment. Inputs longer than 120 seconds retain their last 120 seconds. Supports 480p, 720p, and 1080p output.

Parameter Type Required Default Allowed Description
prompt str yes The positive prompt for the generation.
video str yes Source video URL. Inputs longer than 120 seconds are automatically trimmed to their last 120 seconds before extension.
last_image str The last frame image for generating the video (optional). Supports URL or Base64-encoded data.
resolution str "720p" 480p, 720p, 1080p The resolution of the generated video.
duration int 5 2–30 Length in seconds of the NEW segment to append (2-30). Final output duration is the retained source duration plus this value.
enable_prompt_expansion bool false If set to true, the prompt optimizer will be enabled.
generate_audio bool true Generate audio for the new segment. Existing source audio is preserved.
seed int The random seed to use for the generation. -1 means a random seed will be used.

REST and CLI

The wrapper is a thin layer over the REST API: submit, then poll for the result.

curl -s -X POST "https://api.wavespeed.ai/api/v3/alibaba/wan-3.0/text-to-video" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt": "A slow cinematic dolly shot through a rain-soaked neon night market, reflections on the pavement"}'
# -> {"data": {"id": "<prediction_id>"}}

curl -s "https://api.wavespeed.ai/api/v3/predictions/<prediction_id>/result" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY"
# -> status: completed, outputs: ["<url>"]
npm i -g @wavespeed/cli && wavespeed login
wavespeed run alibaba/wan-3.0/text-to-video -p "your prompt"

Related

Notes

  • Wan 3.0 is a model by Alibaba. This repository is maintained by WaveSpeedAI and wraps the WaveSpeedAI hosted API for it.
  • Function signatures and the tables above are generated from the live model schemas (last generated 2026-11-22). The model pages are the source of truth if an endpoint changes.
  • Issues and pull requests are welcome. License: MIT.

About

Wan 3.0 API — Python wrapper for Wan 3.0 and Wan 3.0 Prime on WaveSpeedAI: text-to-video, image-to-video, reference-to-video, video editing, video extension.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages