万相-参考生视频模型支持 多模态输入 （图片、视频、音频），生成保持角色形象和音色一致性的视频，适用于单角色表演或多角色互动场景。
相关文档：使用指南
为确保调用成功，请务必保证模型、Endpoint URL和API Key 均属于同一地域。跨地域调用将会失败。
由于视频生成任务耗时较长（通常为1-5分钟），API采用异步调用。整个流程包含 “创建任务 -> 轮询获取” 两个核心步骤，具体如下：
调用时请将
调用时请将
SDK 的参数命名与HTTP接口基本一致，参数结构根据语言特性进行封装。
参考生视频任务通常需要1–5分钟。SDK 封装了HTTP异步调用流程，支持同步和异步两种调用方式。
根据模型所在地域设置 base_http_api_url:
调用时请将
根据模型所在地域设置 baseHttpApiUrl:
调用时请将
如果模型调用失败并返回报错信息，请参见错误码进行解决。
主要区别如下：
仅 wan2.7 支持。在
适用范围
为确保调用成功，请务必保证模型、Endpoint URL和API Key 均属于同一地域。跨地域调用将会失败。
- 选择模型：确认模型所属的地域。
- 选择 URL：选择对应的地域 Endpoint URL，支持HTTP URL。
- 配置API Key：选择地域并获取与配置 API Key，再配置API Key到环境变量。
本文的示例代码适用于北京地域。
HTTP调用
由于视频生成任务耗时较长（通常为1-5分钟），API采用异步调用。整个流程包含 “创建任务 -> 轮询获取” 两个核心步骤，具体如下：
步骤1：创建任务获取任务ID
- 北京
- 新加坡
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis{WorkspaceId}替换为真实的业务空间ID。
- 创建成功后，使用接口返回的
task_id查询结果，task_id 有效期为 24 小时。请勿重复创建任务，轮询获取即可。 - 新手指引请参见Postman。
请求参数请求头（Headers）Content-Typestring（必选）请求内容类型。此参数必须设置为application/json。Authorizationstring（必选）请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值：Bearer sk-xxxx。X-DashScope-Asyncstring（必选）异步处理配置参数。HTTP请求只支持异步，必须设置为enable。请求体（Request Body）modelstring （必选）模型名称。模型列表与价格详见模型价格。示例值：wan2.7-r2v、wan2.7-r2v-2026-06-12。input object （必选）输入的基本信息，如提示词等。
属性 prompt string （必选）文本提示词。用来描述生成视频中期望包含的元素和视觉特点。支持中英文，每个汉字、字母、标点占一个字符，超过部分会自动截断。
media数组顺序一致。图和视频分别计数，即同时存在图1、视频1等标识。若参考素材有且仅有一张图片或一个视频，则可简化表述为”参考图片”或“参考视频”。画面描述：假设参考图1是一只猫，图2是一个房间，要描述猫在房间里玩耍，支持两种写法：一种是直接使用标识指代（如“图1在图2里玩耍”）；另一种是结合主体与场景补充说明（如“图1的猫在图2的房间里玩耍”）。当参考图片为多宫格（故事板图像）时，提示词建议按照多分镜的形式描述画面内容。无需描述每个宫格，提供关键分镜内容即可，模型将自动识别宫格逻辑并智能补全镜头内容。为达到更好的效果，建议单次仅输入一张多宫格图。提示词的使用技巧请参见文生视频/图生视频Prompt指南。negative_prompt string （可选）反向提示词，用来描述不希望在视频画面中出现的内容，可以对视频画面进行限制。支持中英文，长度不超过500个字符，超过部分会自动截断。示例值：低分辨率、错误、最差质量、低质量、残缺、多余的手指、比例不良等。media array （必选）媒体素材数组，素材包括图像、视频和音频。支持图像/视频输入作为视觉参考，图像支持多视图，常见参考角色、道具、场景等。
属性 type string （必选）媒体素材类型。可选值为：
string （必选）媒体素材URL。每个值可指向一张图像或一段视频。
传入参考图像（type=reference_image） 参考图像URL或 Base64 编码数据。参考图可以是主体（人物/动物/物体）或者背景。当包含主体时，仅包含一个角色。图像限制：
传入参考视频（type=reference_video） 参考视频URL。视频内容建议包含主体（人物/动物/物体），不建议使用背景或空镜视频。当包含主体时，仅包含一个角色。若视频有声音，也可以参考音色。视频限制：
string （可选）音频 URL。用于指定参考素材（图像/视频）中主体角色的音色。与reference_image或reference_video搭配使用。该音频仅参考音色，与说话内容无关。建议参考音频语种与提示词语种保持一致，匹配效果更佳。音频生效逻辑：
object （可选）视频处理参数，如设置视频分辨率。
属性 resolution string （可选）生成视频的分辨率档位，用于控制视频的清晰度（总像素）。
string （可选）生成视频的宽高比。生效逻辑：
integer （可选）生成视频的时长，单位为秒。
boolean （可选）是否开启prompt智能改写。开启后使用大模型对输入prompt进行智能改写。对于较短的prompt生成效果提升明显，但会增加耗时。
boolean （可选）是否添加水印标识，水印位于视频右下角，文案固定为“AI生成”。
integer（可选）随机数种子，取值范围为[0, 2147483647]。未指定时，系统自动生成随机种子。若需提升生成结果的可复现性，建议固定seed值。请注意，由于模型生成具有概率性，即使使用相同 seed，也不能保证每次生成结果完全一致。 |
传入多张参考素材（图像+视频），并指定音色生成视频。 |
响应参数outputobject任务输出信息。
属性 task_id string任务ID。查询有效期24小时。task_status string任务状态。
枚举值
string请求唯一标识。可用于请求明细溯源和问题排查。codestring请求失败的错误码。请求成功时不会返回此参数，详情请参见错误码。messagestring请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误码。 |
请保存 task_id，用于查询任务状态与结果。 |
步骤2：根据任务ID查询结果
- 北京
- 新加坡
GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}{WorkspaceId}替换为真实的业务空间ID。
请求参数请求头（Headers）Authorizationstring（必选）请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值：Bearer sk-xxxx。URL路径参数（Path parameters）task_idstring（必选）任务ID。 |
将 {task_id}完整替换为上一步接口返回的task_id的值。task_id查询有效期为24小时，并请将{WorkspaceId}替换为真实的业务空间ID。 |
响应参数outputobject任务输出信息。
属性 task_id string（必选）任务ID。task_status string任务状态。
枚举值
string任务提交时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。scheduled_time string任务执行时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。end_time string任务完成时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。video_urlstring视频URL。仅在 task_status 为 SUCCEEDED 时返回。链接有效期24小时，可通过此URL下载视频。视频格式为MP4（H.264 编码）。orig_prompt string原始输入的prompt，对应请求参数prompt。codestring请求失败的错误码。请求成功时不会返回此参数，详情请参见错误码。messagestring请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误码。object输出信息统计。只对成功的结果计数。
属性 input_video_duration integer输入视频的时长，单位秒。output_video_duration integer输出视频的时长，单位秒。duration integer总视频时长。计费按duration时长计算。计算公式：duration = input_video_duration + output_video_duration。SR integer生成视频的分辨率档位。示例值：720。ratio string生成视频的宽高比。示例值：16:9。video_count integer生成视频的数量。固定为1。string请求唯一标识。可用于请求明细溯源和问题排查。 |
视频URL仅保留24小时，超时后会被自动清除，请及时保存生成的视频。 |
DashScope SDK调用
SDK 的参数命名与HTTP接口基本一致，参数结构根据语言特性进行封装。
参考生视频任务通常需要1–5分钟。SDK 封装了HTTP异步调用流程，支持同步和异步两种调用方式。
实际耗时取决于排队任务数和服务运行状态。
Python SDK调用
根据模型所在地域设置 base_http_api_url:
- 北京
- 新加坡
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'{WorkspaceId}替换为真实的业务空间ID。
- 同步调用
- 异步调用
同步调用会阻塞直到视频生成完成，直接返回结果。
请求示例
响应示例
video_url 有效期24小时，请及时下载视频。
Java SDK调用
根据模型所在地域设置 baseHttpApiUrl:
- 北京
- 新加坡
Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";{WorkspaceId}替换为真实的业务空间ID。
- 同步调用
- 异步调用
同步调用会阻塞直到视频生成完成，直接返回结果。
请求示例
响应示例
video_url 有效期24小时，请及时下载视频。
错误码
如果模型调用失败并返回报错信息，请参见错误码进行解决。
常见问题
从 wan2.6 升级到 wan2.7，代码需要改哪些地方？
主要区别如下：
- 提示词的参考引用写法不同 wan2.7 不再使用 character1、character2 这类标识，需要改为按类型分别指代：图像用“图n”（如图1、图2），视频用“视频n”（如视频1、视频2）。英文提示词则写为“Image 1”、"Video 1”这类标识。提示词说明详见prompt参数。
-
多镜头控制方式不同
- wan2.7：不支持 shot_type 参数，通过在 prompt 中描述分镜脚本来实现多镜头效果。
- wan2.6：通过设置 shot_type 为 multi 来生成多镜头视频。
-
请求参数结构不同
- 参考素材传入方式：wan2.7 使用
media（对象数组，每个元素含type和url），替代 wan2.6 的reference_urls（字符串数组）。 - 分辨率参数：wan2.7 使用
resolution（如720P），替代 wan2.6 的size（如1280*720）。 - audio 参数：wan2.7 默认生成有声视频，无需设置。wan2.6 需要显式设置
audio为true或false。
- 参考素材传入方式：wan2.7 使用
如何为主体配音（音色参考）？
仅 wan2.7 支持。在 media 中通过 reference_voice 传入音频 URL，可为参考图像或参考视频指定参考音色。