MaaS_wan_3.0
User Guide
It is recommended to call the Wan 3.0 video generation API according to the following process:
-
Create a task
-
Call POST /v1/ai/{endpointPath}/wan3/videos/generate to submit a generation request. This interface operates in asynchronous task mode, and after successful creation, it will return the native DashScope task_id and the initial task_status (usually PENDING or RUNNING).
-
polling query task
-
Use the output.task_id from the creation response to call GET /v1/ai/{endpointPath}/wan/tasks/{taskId} to query the task status until the task_status reaches a terminal state:
-
Success: SUCCEEDED / SUCCESS
-
Failure: FAILED / FAIL
-
Cancel: CANCELED / CANCELLED
-
Expired or does not exist: UNKNOWN
-
Get Video
-
After the task succeeds, obtain the generated video URL from the output.video_url field in the query response (or the equivalent field returned by DashScope). The URL is usually time-limited, so please download or transfer it as soon as possible.
-
Billing Instructions
-
Charges are calculated based on the duration (in seconds) of the output video only after the task is successfully completed; no fees will be charged for failed or canceled tasks.
-
The billing tiers are differentiated by resolution: video_480p / video_720p / video_1080p.
-
The billing duration is obtained from the `usage.duration` field in the DashScope response; if this field is absent, the system will attempt to retrieve the value from `usage.output_video_duration` instead.
General Request Headers
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer ${your AK} |
| Content-Type | Yes (POST) | application/json |
1. Create a video generation task
Request URL
```plain text POST https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/wan3/videos/generate
### Path Parameters
| **Field** | **Type** | **Location** | **Required** | **Description** |
| ------------ | -------- | ------------ | ------------ | ------------------ |
| endpointPath | string | path | Yes | MaaS endpoint path |
### Request Body Fields
| **Field** | **Type** | **Required** | **Description** |
| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| model | string | No | Model name, default is wan3.0-video |
| input | object | Yes | Input Content |
| input.prompt | string | Conditionally Required | Text description; at least one of this field and input.media must be filled in |
| input.media | array | Conditionally Required | List of media resources; at least one of this field and input.prompt must be filled in |
| input.media\[].type | string | Yes | Media type, refer to the description of media.type |
| input.media\[].url | string | Yes | Media resource URL (must be a publicly accessible HTTPS direct link) |
| parameters | object | No | Generation Parameters |
| parameters.resolution | string | No | Resolution: 480P / 720P / 1080P, default: 1080P |
| parameters.ratio | string | No | Aspect Ratio: adaptive / 16:9 / 4:3 / 1:1 / 3:4 / 9:16, default is adaptive |
| parameters.duration | integer | No | Video duration (seconds): 2 to 30, or -1 (smart duration) |
| parameters.audio | boolean | No | Whether to output audio, default value is true |
| parameters.seed | integer | No | random seed |
| <span style="color: rgb(216,57,49); background-color: inherit">parameters.prompt_extend</span> | <span style="color: rgb(216,57,49); background-color: inherit">boolean</span> | <span style="color: rgb(216,57,49); background-color: inherit">No</span> | <span style="color: rgb(216,57,49); background-color: inherit">Whether to enable intelligent prompt rewriting. If enabled, a large language model will be used to intelligently rewrite the input prompt. This significantly improves the generation effect for shorter prompts, but increases processing time. true: the default value, intelligent rewriting is enabled. false: intelligent rewriting is disabled. When document (file) or web page (link) creatives are passed in, the value of prompt_extend must be true.</span> |
| parameters.watermark | boolean | No | Add watermark or not |
### input validation rules (platform side)
| **Rules** | **Description** |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Choose either prompt or media | input.prompt and input.media cannot both be empty |
| Mutually Exclusive Media Types (Group A vs. Group B) | Group A: first\_frame, last\_frame; Group B: reference\_image, reference\_video, reference\_audio, file, link. Mixing of the two groups is not allowed in a single request. |
| file/link mutual exclusion | The file and link types cannot be used simultaneously in the same request. |
| Resolution Billing Verification | If the billing tier cannot be inferred during creation (unsupported or unrecognized resolution), return 400 |
### Create Response Parameters
Common fields in the response body are as follows:
| **Field** | **Type** | **Description** |
| ------------------- | -------- | ------------------------------------------------------------ |
| request\_id | string | Request ID |
| output | object | Task Output Summary |
| output.task\_id | string | Task ID, which will be used for subsequent queries |
| output.task\_status | string | Task status: common values at creation are PENDING / RUNNING |
### Request Example A — Text-to-Video (Simplest Version)
```bash
curl --request POST \
--url 'https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/wan3/videos/generate' \
--header 'Authorization: Bearer ${your AK}' \
--header 'Content-Type: application/json' \
--data '{
"input": {
"prompt": "An orange tabby cat running across a sunlit grassy meadow, cinematic shot"
},
"parameters": {
"resolution": "720P",
"duration": 5
}
}'
Request Example B — Text-to-Video (Explicitly Specify model and ratio)
curl --request POST \
--url 'https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/wan3/videos/generate' \
--header 'Authorization: Bearer ${your AK}' \
--header 'Content-Type: application/json' \
--data '{
"model": "wan3.0-video",
"input": {
"prompt": "A cyberpunk city nightscape with flickering neon lights, slow push-in camera movement"
},
"parameters": {
"resolution": "1080P",
"ratio": "16:9",
"duration": 5,
"audio": true
}
}'
Request Example C — Reference Image-to-Video (reference_image)
curl --request POST \
--url 'https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/wan3/videos/generate' \
--header 'Authorization: Bearer ${your AK}' \
--header 'Content-Type: application/json' \
--data '{
"input": {
"prompt": "Generate a natural, smooth video in the style of the reference image",
"media": [
{
"type": "reference_image",
"url": "https://your-bucket.oss-cn-beijing.aliyuncs.com/reference.png"
}
]
},
"parameters": {
"resolution": "720P",
"duration": 5
}
}'
Request Example D — First Frame Image-to-Video (first_frame)
curl --request POST \
--url 'https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/wan3/videos/generate' \
--header 'Authorization: Bearer ${your AK}' \
--header 'Content-Type: application/json' \
--data '{
"input": {
"prompt": "Make the subject in the image move naturally",
"media": [
{
"type": "first_frame",
"url": "https://your-bucket.oss-cn-beijing.aliyuncs.com/first_frame.png"
}
]
},
"parameters": {
"resolution": "480P",
"duration": 5
}
}'
Create a response example
{
"request_id": "f4896824-7e51-9d8a-a42a-08c8b2d1fccd",
"output": {
"task_id": "7440b9dd-4c64-4773-a854-88fcf029fa1d",
"task_status": "PENDING"
}
}
2. Query Task
Request URL
```plain text GET https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/wan/tasks/{taskId}
### Path Parameters
| **Field** | **Type** | **Location** | **Required** | **Description** |
| ------------ | -------- | ------------ | ------------ | ------------------------------------------------------------------------------ |
| endpointPath | string | path | Yes | MaaS endpoint path (must be consistent with the one used during task creation) |
| taskId | string | path | Yes | the output.task\_id in the create task response |
### Query Response Parameters
The common fields in the response body are as follows:
| **Field** | **Type** | **Description** |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------ |
| request\_id | string | Request ID |
| output | object | Task Details |
| output.task\_id | string | Task ID |
| output.task\_status | string | Task Status |
| output.submit\_time | string | Submission Time |
| output.scheduled\_time | string | Scheduling Time |
| output.end\_time | string | End Time |
| output.video\_url | string | Video URL upon success (the field name shall be subject to the actual return of DashScope) |
| output.code | string | Error code on failure |
| output.message | string | Error message upon failure |
| usage | object | Usage information (used for billing upon success) |
| usage.duration | number | Billing Duration (seconds) |
### Description of task\_status
| **Status** | **Description** | **Recommended Action** |
| -------------------- | ----------------------- | --------------------------------------- |
| PENDING | Queuing | Continue polling |
| RUNNING | In Progress | Continue polling |
| SUCCEEDED / SUCCESS | Success | Read video\_url and stop polling |
| FAILED / FAIL | Failure | Read code/message and stop polling |
| CANCELED / CANCELLED | Cancelled | Stop polling |
| UNKNOWN | Expired or non-existent | Stop polling and handle it as a failure |
### Request Example
```bash
curl --request GET \
--url 'https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/wan/tasks/7440b9dd-4c64-4773-a854-88fcf029fa1d' \
--header 'Authorization: Bearer ${your AK}'
Query Response Example — Success
{
"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"output": {
"task_id": "7440b9dd-4c64-4773-a854-88fcf029fa1d",
"task_status": "SUCCEEDED",
"submit_time": "2026-08-13 16:38:19.123",
"scheduled_time": "2026-08-13 16:38:25.456",
"end_time": "2026-08-13 16:42:10.789",
"video_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/.../output.mp4"
},
"usage": {
"duration": 5
}
}
Query Response Example — Failure
{
"request_id": "f4896824-7e51-9d8a-a42a-08c8b2d1fccd",
"output": {
"task_id": "7440b9dd-4c64-4773-a854-88fcf029fa1d",
"task_status": "FAILED",
"submit_time": "2026-08-13 17:06:41.542",
"scheduled_time": "2026-08-13 17:10:21.644",
"end_time": "2026-08-13 17:11:05.951",
"code": "InvalidParameter",
"message": "Failed to download https://example.com/unreachable.png"
}
}
3. Billing Instructions
Product Information
| Item | value |
|---|---|
| Product Code | MaaS_wan_3.0_video |
| default model | wan3.0-video |
| Billing Type | By duration (DURATION), unit: seconds |
| Billing Timing | After the task SUCCEEDED, billing will be conducted based on the actual usage returned by DashScope |
Billing Tier (charge_item_code)
| resolution (parameters.resolution) | Billing Item |
|---|---|
| 480P | video_480p |
| 720P | video_720p |
| 1080P (or resolution not specified) | video_1080p |
When no resolution is specified, the platform will infer the billing tier (video_1080p) based on the default DashScope setting of 1080P.
Billing Duration
-
Preferentially take usage.duration
-
If none exists, take usage.output_video_duration
-
Example: If the requested duration is 5 and the task succeeds, the duration in the billing log is usually 5
Non-billing scenarios
-
Task FAILED / CANCELED / UNKNOWN
-
Platform parameter validation failed (HTTP 400, task not created)
-
DashScope synchronous creation failure (HTTP 4xx / 5xx)
4. Error Description
Platform parameter validation error (HTTP 400)
Response format:
{
"error": {
"message": "Error description",
"type": "invalid_request_error",
"code": "400"
},
"request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
| message | Causes | Handling Suggestions |
|---|---|---|
| prompt and media are required one of them | Both input.prompt and input.media are empty | Please fill in at least the prompt or a non-empty media array |
| reference_xx/file/link and first_frame/last_frame are mutually exclusive | Mixed use of head and tail frames and reference/media types | Select only one set of media types according to the scenario |
| file and link are mutually exclusive | Both file and link are used simultaneously | Keep only one type |
| media url is required | The media element is missing a url | Add a publicly accessible HTTPS URL |
| unsupported media type: ... | type is not in the supported list | Use the supported media.type |
| Wan3.0 missing/unsupported resolution for billing... | Resolution unrecognizable | Pass 480P / 720P / 1080P |
DashScope asynchronous task failed (task_status = FAILED)
The task has been created, but the execution phase failed. Common causes:
| code / message example | Causes | Handling Recommendations |
|---|---|---|
| Failed to download https://... | Media URL DashScope cannot be downloaded | Use public network OSS/CDN direct links to ensure that browsers can open them directly |
| Invalid or unresolvable URL: Failed to extract valid content from the provided URL | The URL of type link cannot be resolved | Switch to using reference_image / reference_video to pass direct links |
| Invalid request | The request parameters or media content do not meet the model requirements | Check the media type and URL against the DashScope documentation |
The platform does not pre-check whether the media URL is reachable before creation; such errors will be returned by DashScope during the task execution phase.
Other HTTP errors
| HTTP Status | Description |
|---|---|
| 401 / 403 | Invalid token or insufficient permissions |
| 404 | The taskId does not exist during query. |
| 5xx | Service internal error or upstream unavailable |
Description of media.type
| type | Applications | Note |
|---|---|---|
| first_frame | First-frame image-to-video | Mutually exclusive with Group B type |
| last_frame | End-frame to Video Generation | Mutually exclusive with Group B type |
| reference_image | Reference Image | Must be a direct image link |
| reference_video | Reference Video | Must be a direct video link |
| reference_audio | Reference Audio | Must be a direct audio link |
| file | File URL | Mutually exclusive with link, first_frame/last_frame |
| link | Webpage Link Parsing | Only applicable to pages supported by DashScope; Streaming Media sites such as iQiyi and Bilibili are not supported |
Media URL Requirements
-
Use a public HTTPS direct link so that the DashScope server can download it directly
-
Avoid content that requires login, anti-leeching protection, or intranet addresses
-
The sample URLs in this document may be invalid; please use your own OSS/CDN resources instead.
-
To upload images, use reference_image or first_frame; do not mistakenly use link