> ## Documentation Index > Fetch the complete documentation index at: https://docs.powertokens.ai/llms.txt > Use this file to discover all available pages before exploring further. # 万相2.7-参考生视频 > 提交一个异步的 Ali `wan2.7-r2v` 参考生视频任务。通过 `input.media` 指定参考图像、参考视频或首帧图像，可搭配 `reference_voice` 进行音色参考。 提交任务后，请通过 `GET /ali/api/v1/tasks/{task_id}` 查询任务状态。 ## OpenAPI ````yaml api-reference/zh-Hans/zmodelVideo/ali/api/wan2.7-r2v.json POST /ali/api/v1/services/aigc/video-generation/video-synthesis openapi: 3.0.1 info: title: 万相2.7-参考生视频 version: 1.0.0 description: >- 阿里云万相 `wan2.7-r2v` 参考生视频能力文档。统一公开入口为 `/ali/api/v1/services/aigc/video-generation/video-synthesis`，用于创建异步视频生成任务。 license: name: Project License url: https://github.com/QuantumNous/new-api/blob/main/LICENSE servers: - url: https://api.powertokens.ai description: Baze API 服务地址 security: [] tags: - name: Wan 2.7 Video description: Ali wan2.7-r2v 参考生视频能力 paths: /ali/api/v1/services/aigc/video-generation/video-synthesis: post: tags: - Wan 2.7 Video summary: 创建 wan2.7-r2v 参考生视频任务 description: >- 提交一个异步的 Ali `wan2.7-r2v` 参考生视频任务。通过 `input.media` 指定参考图像、参考视频或首帧图像，可搭配 `reference_voice` 进行音色参考。 提交任务后，请通过 `GET /ali/api/v1/tasks/{task_id}` 查询任务状态。 operationId: aliWan27R2VCreate parameters: - name: Content-Type in: header required: true schema: type: string description: 请求内容类型。此参数必须设置为application/json。 - name: X-DashScope-Async in: header required: true schema: type: string description: 异步处理配置参数。HTTP请求只支持异步，必须设置为enable。 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Wan27R2VRequest' examples: 多主体参考（图像+视频+音色）: summary: 多主体参考（图像+视频+音色） value: model: wan2.7-r2v input: prompt: >- 视频1抱着图3，在图4的椅子上弹奏一支舒缓的乡村民谣，并说道：“今天的阳光真好。”图1手中拿着图2，路过视频1，把手中的图2放到视频1旁边的桌子上，并说道：“真好听，能不能再唱一遍”。 media: - type: reference_image url: >- https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg reference_voice: >- https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3 - type: reference_video url: >- https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4 reference_voice: >- https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3 - type: reference_image url: >- https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png - type: reference_image url: >- https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png - type: reference_image url: >- https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png parameters: resolution: 720P ratio: '16:9' duration: 10 prompt_extend: false watermark: true 单图参考（多宫格图像）: summary: 单图参考（多宫格图像） value: model: wan2.7-r2v-2026-06-12 input: prompt: >- 参考图片，3D卡通冒险电影风，角色Q版但材质细腻，动作流畅，色彩鲜明，保持角色与森林场景一致，不要加入文字。氛围： 冒险、轻快、神秘、童趣。角色： 小男孩探险家：圆帽、背包、短斗篷。小伙伴：会飞的小机器人，圆形身体，蓝色发光眼。场景： 奇幻森林，巨大树根、蘑菇、藤蔓、藏宝洞口、阳光光束。分镜脚本： 1. 全景：奇幻森林里高大树木与光束交错，环境神秘明亮。 2. 中景：小男孩拨开藤蔓向前探路。 3. 中景：小机器人飞在他身边，用蓝光扫描前方。 4. 特写：一张旧藏宝图在男孩手里展开。 5. 近景：他露出兴奋表情，眼睛亮起来。 6. 动作镜头：两人跳过树根和小溪，继续深入森林。 7. 中景：藤蔓后方露出一个被苔藓覆盖的宝箱。 8. 特写：宝箱边缘闪出金色光芒。 9. 收束镜头：男孩和小机器人站在宝箱前惊喜对望，冒险感拉满。 media: - type: reference_image url: >- https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260403/wgjaxy/banana_storyboard_00000020.png parameters: resolution: 720P duration: 10 prompt_extend: false watermark: true responses: '200': description: 提交成功，返回视频任务对象。 content: application/json: schema: $ref: '#/components/schemas/VideoTaskResponse' example: output: task_status: PENDING task_id: 0385dc79-5ff8-4d82-bcb6-xxxxxx request_id: 4909100c-7b5a-9f92-bfe5-xxxxxx '400': description: 请求参数不合法。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: 鉴权失败，例如未提供令牌或令牌无效。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: 触发速率限制或账户额度不足。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: 服务端处理请求时发生内部错误。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: Wan27R2VRequest: type: object required: - model - input properties: model: type: string enum: - wan2.7-r2v description: 模型名称。可选值：`wan2.7-r2v`。 input: $ref: '#/components/schemas/Wan27R2VInput' parameters: $ref: '#/components/schemas/Wan27R2VParameters' VideoTaskResponse: type: object properties: output: type: object properties: task_id: type: string description: 任务ID。查询有效期24小时。 task_status: type: string description: |- 任务状态。 枚举值 PENDING：任务排队中 RUNNING：任务处理中 SUCCEEDED：任务执行成功 FAILED：任务执行失败 CANCELED：任务已取消 UNKNOWN：任务不存在或状态未知 request_id: type: string description: 请求唯一标识。可用于请求明细溯源和问题排查。 code: type: string description: 请求失败的错误码。请求成功时不会返回此参数。 message: type: string description: 请求失败的详细信息。请求成功时不会返回此参数。 ErrorResponse: type: object properties: code: type: string description: 错误码。 message: type: string description: 错误信息。 request_id: type: string description: 请求 ID。 Wan27R2VInput: type: object required: - prompt - media properties: prompt: type: string description: >- 文本提示词。用来描述生成视频中期望包含的元素和视觉特点。 支持中英文，每个汉字、字母、标点占一个字符，超过部分会自动截断。 `wan2.7-r2v`：不超过5000个字符。 **参考指代：** 当为中文提示词时，参考图片时通过"图1、图2"这类标识指代，参考视频时通过"视频1、视频2"这类标识指代。英文提示词则写为"Image 1"、"Video 1"这类标识。英文字母和数字之间有空格，首字母大写。顺序与media数组顺序一致。图和视频分别计数，即同时存在图1、视频1等标识。若参考素材有且仅有一张图片或一个视频，则可简化表述为"参考图片"或"参考视频"。 **画面描述：** 假设参考图1是一只猫，图2是一个房间，要描述猫在房间里玩耍，支持两种写法：一种是直接使用标识指代（如"图1在图2里玩耍"）；另一种是结合主体与场景补充说明（如"图1的猫在图2的房间里玩耍"）。 **多宫格（故事板图像）：** 当参考图片为多宫格（故事板图像）时，提示词建议按照多分镜的形式描述画面内容。无需描述每个宫格，提供关键分镜内容即可，模型将自动识别宫格逻辑并智能补全镜头内容。为达到更好的效果，建议单次仅输入一张多宫格图。 maxLength: 5000 negative_prompt: type: string description: |- 反向提示词，用来描述不希望在视频画面中出现的内容，可以对视频画面进行限制。 支持中英文，长度不超过500个字符，超过部分会自动截断。 示例值：低分辨率、错误、最差质量、低质量、残缺、多余的手指、比例不良等。 maxLength: 500 media: type: array description: |- 媒体素材数组，素材包括图像、视频和音频。支持图像/视频输入作为视觉参考，图像支持多视图，常见参考角色、道具、场景等。 数组中每个元素为一个媒体对象，包含 `type` 与 `url` 字段。 按照数组顺序定义prompt中角色引用的顺序。图和视频分别计数，即可同时存在图1、视频1。 - 数组中的第 1 个 `reference_video` 对应 视频1，第 2 个对应 视频2，以此类推。 - 数组中的第 1 个 `reference_image` 对应 图1，第 2 个对应 图2，以此类推。 items: $ref: '#/components/schemas/Wan27R2VMedia' Wan27R2VParameters: type: object properties: resolution: type: string enum: - 720P - 1080P description: |- **重要** `resolution` 直接影响费用，请在调用前确认百炼控制台。 生成视频的分辨率档位，用于控制视频的清晰度（总像素）。 `wan2.7-r2v`：可选值：`720P`、`1080P`。默认值为 `1080P`。 default: 1080P ratio: type: string enum: - '16:9' - '9:16' - '1:1' - '4:3' - '3:4' description: |- 生成视频的宽高比。 **生效逻辑：** - 未传入首帧图像：按指定的 `ratio` 参数生成视频。 - 已传入首帧图像：自动忽略 `ratio` 参数，以首帧图像的宽高比生成近似比例的视频。 可选值为： - `16:9`（默认值） - `9:16` - `1:1` - `4:3` - `3:4` 不同宽高比对应的输出视频分辨率（宽高像素值）： **720P：** - `16:9` → 1280×720 - `9:16` → 720×1280 - `1:1` → 960×960 - `4:3` → 1104×832 - `3:4` → 832×1104 **1080P：** - `16:9` → 1920×1080 - `9:16` → 1080×1920 - `1:1` → 1440×1440 - `4:3` → 1648×1248 - `3:4` → 1248×1648 default: '16:9' duration: type: integer description: |- **重要** `duration` 直接影响费用，请在调用前确认模型价格。 生成视频的时长，单位为秒。 `wan2.7-r2v`：默认值为5。 - 当参考素材中包含视频时：取值为 [2, 10] 之间的整数。 - 当参考素材中不包含视频时：取值为 [2, 15] 之间的整数。 minimum: 2 maximum: 15 default: 5 prompt_extend: type: boolean description: |- 是否开启prompt智能改写。开启后使用大模型对输入prompt进行智能改写。对于较短的prompt生成效果提升明显，但会增加耗时。 - `true`：默认值，开启智能改写。 - `false`：不开启智能改写。 default: true watermark: type: boolean description: |- 是否添加水印标识，水印位于视频右下角，文案固定为"AI生成"。 - `false`：默认值，不添加水印。 - `true`：添加水印。 default: false seed: type: integer description: |- 随机数种子，取值范围为 [0, 2147483647]。 未指定时，系统自动生成随机种子。若需提升生成结果的可复现性，建议固定 seed 值。 请注意，由于模型生成具有概率性，即使使用相同 seed，也不能保证每次生成结果完全一致。 minimum: 0 maximum: 2147483647 Wan27R2VMedia: type: object required: - type - url properties: type: type: string description: |- type string （必选） 媒体素材类型。可选值为： reference_image：参考图像。提供主体角色（人物/动物/物体）和场景参考。 reference_video：参考视频。提供主体角色（人物/动物/物体）和音色参考，不推荐传入空镜视频。 first_frame：首帧图像。基于首帧生成视频，通常包含主体角色（人物/动物/物体）。支持同时传入首帧图联合控制，常见用法如下： 首帧中已经出现待参考主体：此时可以搭配主体参考强化一致性，或进行音色参考。 首帧中未出现待参考主体：此时可以用主体参考来定义视频动态过程中新出现的主体特征。 素材限制： 首帧图像，最多传入1张。 参考图像和参考视频至少传入1个，参考图像 + 参考视频 ≤ 5。 参考素材为主体角色时，仅包含单一角色。 url: type: string description: >- 媒体素材URL。每个值可指向一张图像或一段视频。 **传入参考图像（`type=reference_image`）：** 参考图像URL或 Base64 编码数据。参考图可以是主体（人物/动物/物体）或者背景。当包含主体时，仅包含一个角色。 图像限制： - 格式：JPEG、JPG、PNG（不支持透明通道）、BMP、WEBP。 - 分辨率：宽度和高度范围为[240, 8000]像素。 - 宽高比：1:8～8:1。 - 文件大小：不超过20MB。 支持输入的格式： - 公网URL：支持HTTP或HTTPS协议。示例值：`https://xxx/xxx.png`。 - 临时URL（OSS）：支持OSS协议，必须通过上传文件获取临时URL。示例值：`oss://dashscope-instant/xxx/xxx.png`。 - Base64 编码图像后的字符串：`data:{MIME_type};base64,{base64_data}`。示例值：`data:image/png;base64,GDU7MtCZzEbTbmRZ......`。 **传入参考视频（`type=reference_video`）：** 参考视频URL。视频内容建议包含主体（人物/动物/物体），不建议使用背景或空镜视频。当包含主体时，仅包含一个角色。若视频有声音，也可以参考音色。 视频限制： - 格式：mp4、mov。 - 时长：1～30s。 - 分辨率：宽度和高度范围为[240,4096]像素。 - 宽高比：1:8～8:1。 - 文件大小：不超过100MB。 支持输入的格式： - 公网URL：支持HTTP和HTTPS协议。示例值：`https://xxx/xxx.mp4`。 - 临时URL（OSS）：支持OSS协议，必须通过上传文件获取临时URL。示例值：`oss://dashscope-instant/xxx/xxx.mp4`。 reference_voice: type: string description: >- 音频 URL。用于指定参考素材（图像/视频）中主体角色的音色。与 `reference_image` 或 `reference_video` 搭配使用。该音频仅参考音色，与说话内容无关。建议参考音频语种与提示词语种保持一致，匹配效果更佳。 **音频生效逻辑：** - 默认行为：若 `reference_video` 本身包含音频，但未指定 `reference_voice`，默认使用视频原声。 - 优先级：若同时传入 `reference_video`（含音频）和 `reference_voice`，则优先使用 `reference_voice` 的音色，覆盖视频原声。 音频限制： - 格式：wav、mp3。 - 时长：1～10s。 - 文件大小：不超过15MB。 支持输入的格式： - 公网URL：支持HTTP和HTTPS协议。示例值：`https://xxx/xxx.mp3`。 - 临时URL（OSS）：支持OSS协议，必须通过上传文件获取临时URL。示例值：`oss://dashscope-instant/xxx/xxx.mp3`。 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: '在请求头中传入 `Authorization: Bearer `。' ````