Skip to content

MaaS_wan_3.0

User Guide

It is recommended to call the Wan 3.0 video generation API according to the following process:

  1. Create a task

  2. 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).

  3. polling query task

  4. 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:

  5. Success: SUCCEEDED / SUCCESS

  6. Failure: FAILED / FAIL

  7. Cancel: CANCELED / CANCELLED

  8. Expired or does not exist: UNKNOWN

  9. Get Video

  10. 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.

  11. Billing Instructions

  12. 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.

  13. The billing tiers are differentiated by resolution: video_480p / video_720p / video_1080p.

  14. 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

  1. Use a public HTTPS direct link so that the DashScope server can download it directly

  2. Avoid content that requires login, anti-leeching protection, or intranet addresses

  3. The sample URLs in this document may be invalid; please use your own OSS/CDN resources instead.

  4. To upload images, use reference_image or first_frame; do not mistakenly use link