跳转至

MaaS_wan_3.0

使用指南

推荐按以下流程调用 Wan 3.0 视频生成接口:

  1. 创建任务MaaS_wan_3.0

  2. 调用 POST /v1/ai/{endpointPath}/wan3/videos/generate 提交生成请求。接口为异步任务模式,创建成功后会返回 DashScope 原厂 task_id 及初始 task_status(通常为 PENDING 或 RUNNING)。

  3. 轮询查询任务

  4. 使用创建响应中的 output.task_id,调用 GET /v1/ai/{endpointPath}/wan/tasks/{taskId} 查询任务状态,直到 task_status 为终态:

  5. 成功:SUCCEEDED / SUCCESS

  6. 失败:FAILED / FAIL

  7. 取消:CANCELED / CANCELLED

  8. 过期或不存在:UNKNOWN

  9. 获取视频

  10. 任务成功后,从查询响应的 output.video_url(或 DashScope 返回的等价字段)获取生成视频 URL。URL 通常有时效,请尽快下载或转存。

  11. 计费说明

  12. 仅任务成功后按输出视频时长(秒)计费;失败、取消任务不计费。

  13. 计费档位按分辨率区分:video_480p / video_720p / video_1080p。

  14. 计费时长取自 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 要求

  1. 使用 HTTPS 公网直链,DashScope 服务端须能直接下载

  2. 避免需要登录、防盗链、内网地址

  3. 文档示例 URL 可能失效,请使用自有 OSS/CDN 资源

  4. 传图片用 reference_image 或 first_frame,不要误用 link