Wan3.0 - Video Generation API Reference
Wan3.0 is an All-in-One reference-based video generation model that supports Text-to-Video , Image-to-Video (first frame/first-last frame), and Reference-based Video Generation . It can generate videos up to 30 seconds long at 30fps. Currently in preview .
For the usage guide, see Wan3.0 - Video Generation.
Prerequisites
To ensure a successful API call, make sure that the model, Endpoint URL and API Key all belong to the same region. Cross-region calls will fail.
- Select a model: Go to the Model Gallery to select a model and confirm the region it belongs to.
- Select a URL: Select the Endpoint URL for the corresponding region.
- Configure API Key: Select a region and Obtain an API key, then Configure API key as an environment variable.
NoteThe sample code in this topic applies to the Beijing region.
HTTP call
Since video generation tasks take a relatively long time (typically 1-5 minutes), the API uses asynchronous calls. The entire process consists of two core steps: "Create a task -> Poll for results", as described below:
Step 1: Create a task and obtain the task ID
Beijing
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
Singapore
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
Japan (Tokyo)
POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
Germany (Frankfurt)
POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
US (Virginia)
POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
China (Hong Kong)
POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
Replace {WorkspaceId} with your actual workspace ID.
Note
- After the task is created, use the returned
task_idto query the result. Thetask_idis valid for 24 hours. Do not create duplicate tasks. Instead, use polling to retrieve the result. - For guidance for beginners, see Call APIs with Postman or cURL.
Request parametersRequest headers (Headers)Content-Type The content type of the request. Must be Authorization Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx. X-DashScope-Async Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be ImportantIf this request header is missing, the error "current user api does not support synchronous calls" is returned. Request body (Request Body)model Model name. Valid values:
input Basic input information. Either parameters Video processing parameters. | File Reference to VideoPass in a file through the Reference-based Video GenerationPass in reference images, videos, audio, files, or web links through Text-to-VideoGenerate a video using only First Frame to VideoOnly pass in First-Last Frame to VideoOnly Video EditingPass in a video to edit through the Video ExtensionPass in the original video through the |
Response parametersoutput Task output information. request_id Unique request identifier for tracing and troubleshooting. code Error code. Returned only for failed requests. See Error codes. message Detailed error message. Returned only for failed requests. See Error codes. | Successful responseSave the Error responseTask creation failed. See Error codes. |
Step 2: Query results by task ID
Beijing
GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
Singapore
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
Japan (Tokyo)
GET https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
Germany (Frankfurt)
GET https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
US (Virginia)
GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
China (Hong Kong)
GET https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/tasks/{task_id}
Note
- Polling recommendation: Video generation takes several minutes. Use a polling mechanism with a reasonable interval, such as 15 seconds.
- Task state transition: PENDING → RUNNING → SUCCEEDED or FAILED.
- Result link: After a task succeeds, a video URL valid for 24 hours is returned. Download and save the video to permanent storage, such as OSS.
task_idvalidity: 24 hours. After this period, queries return the task status asUNKNOWN.- RPS limit: The default RPS for the query API is 20. For higher-frequency queries or event notifications, we recommend that you configure an asynchronous task callback.
- More operations: For batch queries, task cancellation, and other operations, see Manage asynchronous tasks.
Request parametersRequest headers (Headers)Authorization Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx. URL path parameters (Path parameters)task_id The ID of the task. | Query task resultsReplace |
Response parametersoutput Task output information. usage Output statistics. Only counts successful results. request_id Unique request identifier for tracing and troubleshooting. | Task succeededVideo URLs are valid for only 24 hours and then automatically purged. Save generated videos promptly. Task failedWhen a task fails, Task query expiredThe |
Material combinations
NoteOnly the following specific material combinations are supported. Passing in other combinations will result in an error.
Text-to-Video: Only pass in prompt. media is not supported.
// Text-to-Video
{
"input": {
"prompt": "..."
}
}
Image-to-Video, Reference-based Video Generation, Video Editing, Video Extension, and other modes require passing in materials through the media array, with each element specifying type and url. type combination rules:
first_frame/last_frameandreference_image/reference_video/reference_audio/file/linktypes are mutually exclusive and cannot be used together in the same request.fileandlinkare mutually exclusive (choose one), but both can be combined withreference_image/reference_video/reference_audio.reference_image/reference_video/reference_audiocan be freely combined with each other.
// First frame only
{
"media": [
{ "type": "first_frame", "url": "..." }
]
}
// First frame + last frame only
{
"media": [
{ "type": "first_frame", "url": "..." },
{ "type": "last_frame", "url": "..." }
]
}
// reference_image, reference_video, reference_audio can be freely combined
// Reference image only
{
"media": [
{ "type": "reference_image", "url": "..." }
]
}
// Reference video only
{
"media": [
{ "type": "reference_video", "url": "..." }
]
}
// Reference audio only
{
"media": [
{ "type": "reference_audio", "url": "..." }
]
}
// Image + video
{
"media": [
{ "type": "reference_image", "url": "..." },
{ "type": "reference_video", "url": "..." }
]
}
// Image + audio
{
"media": [
{ "type": "reference_image", "url": "..." },
{ "type": "reference_audio", "url": "..." }
]
}
// Video + audio
{
"media": [
{ "type": "reference_video", "url": "..." },
{ "type": "reference_audio", "url": "..." }
]
}
// Image + video + audio
{
"media": [
{ "type": "reference_image", "url": "..." },
{ "type": "reference_video", "url": "..." },
{ "type": "reference_audio", "url": "..." }
]
}
// Must include file or link (choose one), can be freely combined with reference_image/reference_video/reference_audio
// File only
{
"media": [
{ "type": "file", "url": "..." }
]
}
// File + image
{
"media": [
{ "type": "file", "url": "..." },
{ "type": "reference_image", "url": "..." }
]
}
// File + video
{
"media": [
{ "type": "file", "url": "..." },
{ "type": "reference_video", "url": "..." }
]
}
// File + audio
{
"media": [
{ "type": "file", "url": "..." },
{ "type": "reference_audio", "url": "..." }
]
}
// File + image + video
{
"media": [
{ "type": "file", "url": "..." },
{ "type": "reference_image", "url": "..." },
{ "type": "reference_video", "url": "..." }
]
}
// File + image + audio
{
"media": [
{ "type": "file", "url": "..." },
{ "type": "reference_image", "url": "..." },
{ "type": "reference_audio", "url": "..." }
]
}
// File + video + audio
{
"media": [
{ "type": "file", "url": "..." },
{ "type": "reference_video", "url": "..." },
{ "type": "reference_audio", "url": "..." }
]
}
// File + image + video + audio
{
"media": [
{ "type": "file", "url": "..." },
{ "type": "reference_image", "url": "..." },
{ "type": "reference_video", "url": "..." },
{ "type": "reference_audio", "url": "..." }
]
}
// Must include reference_video, can be combined with reference_image/reference_audio
// Prompt contains editing intent
// Reference video only
{
"media": [
{ "type": "reference_video", "url": "..." }
]
}
// Video + image
{
"media": [
{ "type": "reference_video", "url": "..." },
{ "type": "reference_image", "url": "..." }
]
}
// Video + audio
{
"media": [
{ "type": "reference_video", "url": "..." },
{ "type": "reference_audio", "url": "..." }
]
}
// Video + image + audio
{
"media": [
{ "type": "reference_video", "url": "..." },
{ "type": "reference_image", "url": "..." },
{ "type": "reference_audio", "url": "..." }
]
}
// Must include reference_video, can be combined with reference_image/reference_audio
// Prompt contains extension intent
// Reference video only
{
"media": [
{ "type": "reference_video", "url": "..." }
]
}
// Video + image
{
"media": [
{ "type": "reference_video", "url": "..." },
{ "type": "reference_image", "url": "..." }
]
}
// Video + audio
{
"media": [
{ "type": "reference_video", "url": "..." },
{ "type": "reference_audio", "url": "..." }
]
}
// Video + image + audio
{
"media": [
{ "type": "reference_video", "url": "..." },
{ "type": "reference_image", "url": "..." },
{ "type": "reference_audio", "url": "..." }
]
}
FAQ
Why can't I pass in audio or other media assets in first/first-last frame mode?
Wan3.0's first frame/first-last frame mode only supports first_frame and last_frame, and cannot accept other types such as audio at the same time (see Material combinations).
Difference from Wan2.7 Image-to-Video series: Wan2.7's first frame/first-last frame mode supports passing in driving_audio for audio-driven generation; Wan3.0's first frame/first-last frame mode does not. If you need audio-driven generation, use the all-modal reference mode (reference_image + reference_audio combination) instead. For specific usage, see Wan3.0 - Video Generation Guide.