MaaS_wan_3.0
使用指南
推荐按以下流程调用 Wan 3.0 视频生成接口:
-
创建任务MaaS_wan_3.0
-
调用 POST /v1/ai/{endpointPath}/wan3/videos/generate 提交生成请求。接口为异步任务模式,创建成功后会返回 DashScope 原厂 task_id 及初始 task_status(通常为 PENDING 或 RUNNING)。
-
轮询查询任务
-
使用创建响应中的 output.task_id,调用 GET /v1/ai/{endpointPath}/wan/tasks/{taskId} 查询任务状态,直到 task_status 为终态:
-
成功:SUCCEEDED / SUCCESS
-
失败:FAILED / FAIL
-
取消:CANCELED / CANCELLED
-
过期或不存在:UNKNOWN
-
获取视频
-
任务成功后,从查询响应的 output.video_url(或 DashScope 返回的等价字段)获取生成视频 URL。URL 通常有时效,请尽快下载或转存。
-
计费说明
-
仅任务成功后按输出视频时长(秒)计费;失败、取消任务不计费。
-
计费档位按分辨率区分:video_480p / video_720p / video_1080p。
-
计费时长取自 DashScope 响应 usage.duration(若无则尝试 usage.output_video_duration)。
通用请求头
| Header | 必填 | 说明 |
|---|---|---|
| Authorization | 是 | Bearer ${your AK} |
| Content-Type | 是(POST) | application/json |
1. 创建视频生成任务
请求 URL
```plain text POST https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/wan3/videos/generate
### 路径参数
| **字段** | **类型** | **位置** | **必填** | **说明** |
| ------------ | ------ | ------ | ------ | --------- |
| endpointPath | string | path | 是 | MaaS 端点路径 |
### 请求体字段
| **字段** | **类型** | **必填** | **说明** |
| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| model | string | 否 | 模型名称,默认 wan3.0-video |
| input | object | 是 | 输入内容 |
| input.prompt | string | 条件必填 | 文本描述;与 input.media 至少填一项 |
| input.media | array | 条件必填 | 媒体资源列表;与 input.prompt 至少填一项 |
| input.media\[].type | string | 是 | 媒体类型,见 media.type 说明 |
| input.media\[].url | string | 是 | 媒体资源 URL(须公网可访问的 HTTPS 直链) |
| parameters | object | 否 | 生成参数 |
| parameters.resolution | string | 否 | 分辨率:480P / 720P / 1080P,默认 1080P |
| parameters.ratio | string | 否 | 宽高比:adaptive / 16:9 / 4:3 / 1:1 / 3:4 / 9:16,默认 adaptive |
| parameters.duration | integer | 否 | 视频时长(秒):2~30,或 -1(智能时长) |
| parameters.audio | boolean | 否 | 是否输出音频,默认 true |
| parameters.seed | integer | 否 | 随机种子 |
| <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">否</span> | <span style="color: rgb(216,57,49); background-color: inherit">是否开启prompt智能改写。开启后使用大模型对输入prompt进行智能改写。对于较短的prompt生成效果提升明显,但会增加耗时。true:默认值,开启智能改写。false:不开启智能改写。当传入文档(file)或网页(link)素材时,prompt_extend 取值必须为 true。</span> |
| parameters.watermark | boolean | 否 | 是否添加水印 |
### input 校验规则(平台侧)
| **规则** | **说明** |
| ------------------ | ------------------------------------------------------------------------------------------------------- |
| prompt / media 二选一 | input.prompt 与 input.media 不能同时为空 |
| 媒体类型互斥(组 A vs 组 B) | 组 A:first\_frame、last\_frame;组 B:reference\_image、reference\_video、reference\_audio、file、link。同一请求中不可混用 |
| file / link 互斥 | 同一请求中不可同时使用 file 与 link 类型 |
| 分辨率计费校验 | 创建时若无法推断计费档位(分辨率不支持或未识别),返回 400 |
### 创建响应参数
响应体常见字段如下:
| **字段** | **类型** | **说明** |
| ------------------- | ------ | ---------------------------- |
| request\_id | string | 请求 ID |
| output | object | 任务输出摘要 |
| output.task\_id | string | 任务 ID,后续查询时使用此 ID |
| output.task\_status | string | 任务状态,创建时常见 PENDING / RUNNING |
### 请求示例 A — 文生视频(最简)
```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": "一只橘猫在阳光明媚的草地上奔跑,电影感镜头"
},
"parameters": {
"resolution": "720P",
"duration": 5
}
}'
请求示例 B — 文生视频(显式指定 model 与 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": "赛博朋克风格的城市夜景,霓虹灯闪烁,镜头缓慢推进"
},
"parameters": {
"resolution": "1080P",
"ratio": "16:9",
"duration": 5,
"audio": true
}
}'
请求示例 C — 参考图生视频(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": "参考图片中的风格,生成一段自然流畅的视频",
"media": [
{
"type": "reference_image",
"url": "https://your-bucket.oss-cn-beijing.aliyuncs.com/reference.png"
}
]
},
"parameters": {
"resolution": "720P",
"duration": 5
}
}'
请求示例 D — 首帧图生视频(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": "让画面中的主体自然动起来",
"media": [
{
"type": "first_frame",
"url": "https://your-bucket.oss-cn-beijing.aliyuncs.com/first_frame.png"
}
]
},
"parameters": {
"resolution": "480P",
"duration": 5
}
}'
创建响应示例
{
"request_id": "f4896824-7e51-9d8a-a42a-08c8b2d1fccd",
"output": {
"task_id": "7440b9dd-4c64-4773-a854-88fcf029fa1d",
"task_status": "PENDING"
}
}
2. 查询任务
请求 URL
```plain text GET https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/wan/tasks/{taskId}
### 路径参数
| **字段** | **类型** | **位置** | **必填** | **说明** |
| ------------ | ------ | ------ | ------ | ------------------------ |
| endpointPath | string | path | 是 | MaaS 端点路径(须与创建任务时一致) |
| taskId | string | path | 是 | 创建任务响应中的 output.task\_id |
### 查询响应参数
响应体常见字段如下:
| **字段** | **类型** | **说明** |
| ---------------------- | ------ | --------------------------------- |
| request\_id | string | 请求 ID |
| output | object | 任务详情 |
| output.task\_id | string | 任务 ID |
| output.task\_status | string | 任务状态 |
| output.submit\_time | string | 提交时间 |
| output.scheduled\_time | string | 调度时间 |
| output.end\_time | string | 结束时间 |
| output.video\_url | string | 成功时的视频 URL(字段名以 DashScope 实际返回为准) |
| output.code | string | 失败时的错误码 |
| output.message | string | 失败时的错误信息 |
| usage | object | 用量信息(成功时用于计费) |
| usage.duration | number | 计费时长(秒) |
### task\_status 说明
| **状态** | **说明** | **建议操作** |
| -------------------- | ------ | ---------------------- |
| PENDING | 排队中 | 继续轮询 |
| RUNNING | 执行中 | 继续轮询 |
| SUCCEEDED / SUCCESS | 成功 | 读取 video\_url,停止轮询 |
| FAILED / FAIL | 失败 | 读取 code / message,停止轮询 |
| CANCELED / CANCELLED | 已取消 | 停止轮询 |
| UNKNOWN | 过期或不存在 | 停止轮询,按失败处理 |
### 请求示例
```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}'
查询响应示例 — 成功
{
"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
}
}
查询响应示例 — 失败
{
"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. 计费说明
产品信息
| 项 | 值 |
|---|---|
| 产品编码 | MaaS_wan_3.0_video |
| 默认模型 | wan3.0-video |
| 计费类型 | 按时长(DURATION),单位:秒 |
| 计费时机 | 任务 SUCCEEDED 后,按 DashScope 返回的实际用量计费 |
计费档位(charge_item_code)
| 分辨率(parameters.resolution) | 计费项 |
|---|---|
| 480P | video_480p |
| 720P | video_720p |
| 1080P(或未指定 resolution) | video_1080p |
未传 resolution 时,平台按 DashScope 默认 1080P 推断计费档位(video_1080p)。
计费时长
-
优先取 usage.duration
-
若无,取 usage.output_video_duration
-
示例:请求 duration: 5 且任务成功,计费日志中 duration 通常为 5
不计费场景
-
任务 FAILED / CANCELED / UNKNOWN
-
平台入参校验失败(HTTP 400,任务未创建)
-
DashScope 创建阶段同步失败(HTTP 4xx / 5xx)
4. 错误说明
平台入参校验错误(HTTP 400)
响应格式:
{
"error": {
"message": "错误描述",
"type": "invalid_request_error",
"code": "400"
},
"request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
| message | 原因 | 处理建议 |
|---|---|---|
| prompt and media are required one of them | input.prompt 与 input.media 均为空 | 至少填写 prompt 或非空 media 数组 |
| reference_xx/file/link and first_frame/last_frame are mutually exclusive | 混用了首尾帧与参考/media 类型 | 按场景只选一组 media 类型 |
| file and link are mutually exclusive | 同时使用了 file 与 link | 只保留一种 |
| media url is required | media 元素缺少 url | 补充公网可访问的 HTTPS URL |
| unsupported media type: ... | type 不在支持列表内 | 使用支持的 media.type |
| Wan3.0 missing/unsupported resolution for billing... | 分辨率无法识别 | 传 480P / 720P / 1080P |
DashScope 异步任务失败(task_status = FAILED)
任务已创建,但执行阶段失败。常见原因:
| code / message 示例 | 原因 | 处理建议 |
|---|---|---|
| Failed to download https://... | 媒体 URL DashScope 无法下载 | 使用公网 OSS/CDN 直链,确保浏览器可直接打开 |
| URL 无效或无法解析:未能从提供的 URL 提取有效内容 | link 类型 URL 无法解析 | 改用 reference_image / reference_video 传直链 |
| Invalid request | 请求参数或媒体内容不符合模型要求 | 对照 DashScope 文档检查 media 类型与 URL |
平台不会在创建前预检媒体 URL 是否可达;此类错误在任务执行阶段由 DashScope 返回。
其他 HTTP 错误
| HTTP 状态 | 说明 |
|---|---|
| 401 / 403 | Token 无效或无权限 |
| 404 | 查询时 taskId 不存在 |
| 5xx | 服务内部错误或上游不可用 |
media.type 说明
| type | 用途 | 备注 |
|---|---|---|
| first_frame | 首帧图生视频 | 与组 B 类型互斥 |
| last_frame | 尾帧图生视频 | 与组 B 类型互斥 |
| reference_image | 参考图片 | 须为图片直链 |
| reference_video | 参考视频 | 须为视频直链 |
| reference_audio | 参考音频 | 须为音频直链 |
| file | 文件 URL | 与 link、first_frame/last_frame 互斥 |
| link | 网页链接解析 | 仅适用于 DashScope 支持的页面;不支持爱奇艺、B 站等流媒体站点 |
媒体 URL 要求
-
使用 HTTPS 公网直链,DashScope 服务端须能直接下载
-
避免需要登录、防盗链、内网地址
-
文档示例 URL 可能失效,请使用自有 OSS/CDN 资源
-
传图片用 reference_image 或 first_frame,不要误用 link