全部产品
Search
文档中心

大模型服务平台百炼:万相-参考生视频API参考

更新时间:Feb 11, 2026

万相-参考生视频模型支持多模态输入(文本/图像/视频),可将人或物体作为主角,生成单角色表演或多角色互动视频。模型还支持智能分镜,生成多镜头视频。

相关文档使用指南

适用范围

为确保调用成功,请务必保证模型、Endpoint URL 和 API Key 均属于同一地域。跨地域调用将会失败。

说明

本文的示例代码适用于新加坡地域

HTTP调用

由于参考生视频任务耗时较长(通常为1-5分钟),API采用异步调用。整个流程包含 “创建任务 -> 轮询获取” 两个核心步骤,具体如下:

步骤1:创建任务获取任务ID

新加坡

POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

弗吉尼亚

POST https://dashscope-us.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

北京

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

说明
  • 创建成功后,使用接口返回的 task_id 查询结果,task_id 有效期为 24 小时。请勿重复创建任务,轮询获取即可。

请求参数

多角色互动(参考图像和视频)

通过reference_urls传入图像和视频URL。同时设置shot_typemulti,生成多镜头视频。

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.6-r2v-flash",
    "input": {
        "prompt": "Character2 坐在靠窗的椅子上,手持 character3,在 character4 旁演奏一首舒缓的美国乡村民谣。Character1 对Character2开口说道:“that sounds great“",
        "reference_urls": [
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/aacgyk/wan-r2v-role1.mp4",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mmizqq/wan-r2v-role2.mp4",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
        ]
    },
    "parameters": {
        "size": "1280*720",
        "duration": 10,
        "audio": true,
        "shot_type": "multi",
        "watermark": true
    }
}'

多角色互动(参考视频)

通过reference_urls传入多个视频URL。同时设置shot_typemulti,生成多镜头视频。

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.6-r2v",
    "input": {
        "prompt": "character1对character2说: “I’ll rely on you tomorrow morning!” character2 回答: “You can count on me!”",
        "reference_urls": [
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251217/dlrrly/%E5%B0%8F%E5%A5%B3%E5%AD%A91%E8%8B%B1%E6%96%872.mp4",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251217/fkxknn/%E9%93%83%E9%93%83.mp4"
        ]
    },
    "parameters": {
        "size": "1280*720",
        "duration": 10,
        "shot_type": "multi"
    }
}'

单角色扮演

通过reference_urls传入单个视频URL。同时设置shot_typemulti,生成多镜头视频。

# 注意:如果使用华北2(北京)地域的模型,需要将url替换为:https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.6-r2v",
    "input": {
        "prompt": "character1一边喝奶茶,一边随着音乐即兴跳舞。",
        "reference_urls":["https://cdn.wanxai.com/static/demo-wan26/vace.mp4"]
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "shot_type":"multi"
    }
}'

生成无声视频

仅支持wan2.6-r2v-flash生成无声视频。

当生成无声视频时,必须显式设置 parameters.audio = false

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.6-r2v-flash",
    "input": {
        "prompt": "character1一边喝奶茶,一边随着音乐即兴跳舞。",
        "reference_urls":["https://cdn.wanxai.com/static/demo-wan26/vace.mp4"]
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "audio": false,
        "shot_type":"multi"
    }
}'
请求头(Headers)

Content-Type string (必选)

请求内容类型。此参数必须设置为application/json

Authorization string(必选)

请求身份认证。接口使用阿里云百炼API-Key进行身份认证。示例值:Bearer sk-xxxx。

X-DashScope-Async string (必选)

异步处理配置参数。HTTP请求只支持异步,必须设置为enable

重要

缺少此请求头将报错:“current user api does not support synchronous calls”。

请求体(Request Body)

model string (必选)

模型名称。模型列表与价格详见模型价格

示例值:wan2.6-r2v-flash。

input object (必选)

输入的基本信息,如提示词等。

属性

prompt string (必选)

文本提示词。用来描述生成视频中期望包含的元素和视觉特点。

支持中英文,每个汉字、字母、标点占一个字符,超过部分会自动截断。

  • wan2.6-r2v-flash:长度不超过1500个字符。

  • wan2.6-r2v:长度不超过1500个字符。

角色引用说明:通过“character1、character2”这类标识引用参考角色,每个参考(视频或图像)仅包含单一角色。模型仅通过此方式识别参考中的角色。

示例值:character1在沙发上开心地看电影。

提示词的使用技巧请参见文生视频/图生视频Prompt指南

negative_prompt string (可选)

反向提示词,用来描述不希望在视频画面中出现的内容,可以对视频画面进行限制。

支持中英文,长度不超过500个字符,超过部分会自动截断。

示例值:低分辨率、错误、最差质量、低质量、残缺、多余的手指、比例不良等。

reference_urls array[string] (必选)

重要

reference_urls直接影响费用,计费规则请参见计费与限流

上传的参考文件 URL 数组,支持传入视频和图像。用于提取角色形象与音色(如有),以生成符合参考特征的视频。

  • 每个 URL 可指向 一张图像一段视频

    • 图像数量:0~5。

    • 视频数量:0~3。

    • 总数限制:图像 + 视频 ≤ 5。

  • 传入多个参考文件时,按照数组顺序定义角色的顺序。即第 1 个 URL 对应 character1,第 2 个对应 character2,以此类推。

  • 每个参考文件仅包含一个主体角色。例如 character1 为小女孩,character2 为闹钟。

支持输入的格式:

  1. 公网URL:

    • 支持 HTTP 或 HTTPS 协议。

    • 示例值:https://cdn.translate.alibaba.com/xxx.png。

参考视频要求:

  • 格式:MP4、MOV。

  • 时长:1s~30s。

  • 视频大小:不超过100MB。

参考图像要求:

  • 格式:JPEG、JPG、PNG(不支持透明通道)、BMP、WEBP。

  • 分辨率:宽高均需在 [240, 5000]像素之间。

  • 图像大小:不超过10MB。

示例值:["https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp4", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.jpg"]。

已废弃字段

reference_video_urls array[string]

重要

推荐使用reference_urls替代reference_video_urls

上传的参考视频文件 URL 数组。用于提取角色形象与音色(如有),以生成符合参考特征的视频。

  • 最多支持 3 个视频

  • 传入多个视频时,按照数组顺序定义视频角色的顺序。即第 1 个 URL 对应 character1,第 2 个对应 character2,以此类推。

  • 每个参考视频仅包含一个角色(如 character1 为小女孩,character2 为闹钟)。

  • URL支持 HTTP 或 HTTPS 协议。

单个视频要求:

  • 格式:MP4、MOV。

  • 时长:2~30s。

  • 文件大小:视频不超过100MB。

示例值:["https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp4"]。

parameters object (可选)

图像处理参数。如设置视频分辨率、开启prompt智能改写、添加水印等。

属性

size string (可选)

重要
  • size直接影响费用,费用 = 单价(基于分辨率)× 时长(秒)。同一模型:1080P > 720P ,请在调用前确认模型价格

  • size必须设置为具体数值(如 1280*720),而不是 1:1或720P。

指定生成的视频分辨率,格式为宽*高。该参数的默认值和可用枚举值依赖于 model 参数,规则如下:

  • wan2.6-r2v-flash:默认值为 1920*1080(1080P)。可选分辨率:720P、1080P对应的所有分辨率。

  • wan2.6-r2v:默认值为 1920*1080(1080P)。可选分辨率:720P、1080P对应的所有分辨率。

720P档位:可选的视频分辨率及其对应的视频宽高比为:

  • 1280*720:16:9。

  • 720*1280:9:16。

  • 960*960:1:1。

  • 1088*832:4:3。

  • 832*1088:3:4。

1080P档位:可选的视频分辨率及其对应的视频宽高比为:

  • 1920*1080: 16:9。

  • 1080*1920: 9:16。

  • 1440*1440: 1:1。

  • 1632*1248: 4:3。

  • 1248*1632: 3:4。

duration integer (可选)

重要

duration直接影响费用。费用 = 单价(基于分辨率)× 时长(秒),请在调用前确认模型价格

生成视频的时长,单位为秒。

  • wan2.6-r2v-flash:取值为[2, 10]之间的整数。默认值为5。

  • wan2.6-r2v:取值为[2, 10]之间的整数。默认值为5。

示例值:5。

shot_type string (可选)

指定生成视频的镜头类型,即视频是由一个连续镜头还是多个切换镜头组成。

参数优先级:shot_type > prompt。例如,若 shot_type设置为"single",即使 prompt 中包含“生成多镜头视频”,模型仍会输出单镜头视频。

可选值:

  • single:默认值,输出单镜头视频

  • multi:输出多镜头视频。

示例值:single。

说明

当希望严格控制视频的叙事结构(如产品展示用单镜头、故事短片用多镜头),可通过此参数指定。

audio boolean (可选)

重要

audio直接影响费用,有声视频与无声视频价格不同,请在调用前确认模型价格

支持模型:wan2.6-r2v-flash。

是否生成有声视频。

可选值:

  • true:默认值,输出有声视频。

  • false:输出无声视频。

示例值:true。

watermark boolean (可选)

是否添加水印标识,水印位于视频右下角,文案固定为“AI生成”。

  • false:默认值,不添加水印。

  • true:添加水印。

示例值:false。

seed integer (可选)

随机数种子,取值范围为[0, 2147483647]

未指定时,系统自动生成随机种子。若需提升生成结果的可复现性,建议固定seed值。

请注意,由于模型生成具有概率性,即使使用相同 seed,也不能保证每次生成结果完全一致。

示例值:12345。

响应参数

成功响应

请保存 task_id,用于查询任务状态与结果。

{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

异常响应

创建任务失败,请参见错误信息进行解决。

{
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

output object

任务输出信息。

属性

task_id string

任务ID。查询有效期24小时。

task_status string

任务状态。

枚举值

  • PENDING:任务排队中

  • RUNNING:任务处理中

  • SUCCEEDED:任务执行成功

  • FAILED:任务执行失败

  • CANCELED:任务已取消

  • UNKNOWN:任务不存在或状态未知

request_id string

请求唯一标识。可用于请求明细溯源和问题排查。

code string

请求失败的错误码。请求成功时不会返回此参数,详情请参见错误信息

message string

请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误信息

步骤2:根据任务ID查询结果

新加坡

GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}

弗吉尼亚

GET https://dashscope-us.aliyuncs.com/api/v1/tasks/{task_id}

北京

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

说明
  • 轮询建议:视频生成过程约需数分钟,建议采用轮询机制,并设置合理的查询间隔(如 15 秒)来获取结果。

  • 任务状态流转:PENDING(排队中)→ RUNNING(处理中)→ SUCCEEDED(成功)/ FAILED(失败)。

  • 结果链接:任务成功后返回视频链接,有效期为 24 小时。建议在获取链接后立即下载并转存至永久存储(如阿里云 OSS)。

  • task_id 有效期24小时,超时后将无法查询结果,接口将返回任务状态为UNKNOWN

请求参数

查询任务结果

{task_id}完整替换为上一步接口返回的task_id的值。

curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
请求头(Headers)

Authorization string(必选)

请求身份认证。接口使用阿里云百炼API-Key进行身份认证。示例值:Bearer sk-xxxx。

URL路径参数(Path parameters)

task_id string(必选)

任务ID。

响应参数

任务执行成功

视频URL仅保留24小时,超时后会被自动清除,请及时保存生成的视频。

{
    "request_id": "caa62a12-8841-41a6-8af2-xxxxxx",
    "output": {
        "task_id": "eff1443c-ccab-4676-aad3-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-12-16 00:25:59.869",
        "scheduled_time": "2025-12-16 00:25:59.900",
        "end_time": "2025-12-16 00:30:35.396",
        "orig_prompt": "character1在沙发上开心的看电影",
        "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
     "usage": {
        "duration": 10.0,
        "size": "1280*720",
        "input_video_duration": 5,
        "output_video_duration": 5,
        "video_count": 1,
        "SR": 720
    }
}

任务执行失败

若任务执行失败,task_status将置为 FAILED,并提供错误码和信息。请参见错误信息进行解决。

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The size is not match xxxxxx"
    }
}

任务查询过期

task_id查询有效期为 24 小时,超时后将无法查询,返回以下报错信息。

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

output object

任务输出信息。

属性

task_id string(必选)

任务ID。

task_status string

任务状态。

枚举值

  • PENDING:任务排队中

  • RUNNING:任务处理中

  • SUCCEEDED:任务执行成功

  • FAILED:任务执行失败

  • CANCELED:任务已取消

  • UNKNOWN:任务不存在或状态未知

submit_time string

任务提交时间。时区为UTC+8,格式为 YYYY-MM-DD HH:mm:ss.SSS。

scheduled_time string

任务执行时间。时区为UTC+8,格式为 YYYY-MM-DD HH:mm:ss.SSS。

end_time string

任务完成时间。时区为UTC+8,格式为 YYYY-MM-DD HH:mm:ss.SSS。

video_url string

视频URL。仅在 task_status 为 SUCCEEDED 时返回。

链接有效期24小时,可通过此URL下载视频。视频格式为MP4(H.264 编码)。

orig_prompt string

原始输入的prompt,对应请求参数prompt

code string

请求失败的错误码。请求成功时不会返回此参数,详情请参见错误信息

message string

请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误信息

usage object

输出信息统计。只对成功的结果计数。

属性

input_video_duration integer

输入的参考视频的时长,单位秒。

output_video_duration integer

输出视频的时长,单位秒。

duration float

总视频时长。计费按duration时长计算。

计算公式:duration = input_video_duration + output_video_duration

SR integer

生成视频的分辨率档位。示例值:720。

sizestring

生成视频的分辨率。格式为“宽*高,示例值:1280*720。

video_count integer

生成视频的数量。固定为1。

request_id string

请求唯一标识。可用于请求明细溯源和问题排查。

使用限制

  • 数据时效:任务task_id和 视频video_url均只保留 24 小时,过期后将无法查询或下载。

  • 内容审核:输入的 prompt 和输出的视频均会经过内容安全审核,包含违规内容的请求将报错“IPInfringementSuspect”或“DataInspectionFailed”,具体参见错误信息

  • 网络访问配置:视频链接存储于阿里云 OSS,如果业务系统因安全策略无法访问外部OSS链接,请将以下 OSS 域名加入网络访问白名单。

    # OSS域名列表
    dashscope-result-bj.oss-cn-beijing.aliyuncs.com
    dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
    dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
    dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
    dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
    dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
    dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
    dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
    dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com
    dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com

错误码

如果模型调用失败并返回报错信息,请参见错误信息进行解决。