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 guide, live pricing and playground: wavespeed.ai/wan-3-api
- No code: generate in the browser with the AI Video Generator on WaveSpeedAI
pip install git+https://github.com/WaveSpeedAI/wan-3.0-api.git
export WAVESPEED_API_KEY="your-api-key" # https://wavespeed.ai/accesskeyimport 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.
| 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.
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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"- awesome-wan-api — prompt library and variant guide
- More model wrappers: Seedance 2.5 · Kling 4.0 · Veo 3.1 · MiniMax H3 · HappyHorse 1.1 · FLUX 3 · Seedream 5.5 · GPT Image 2.6 · Nano Banana 2.1
- SDKs and tools: Python · JavaScript · CLI · MCP server · ComfyUI nodes
- Full model catalog
- 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.