BRASILTradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗
Wan 2.7 -- Gerar a partir de referência
Envie um Wan 2.7 tarefa de referência ao vídeo
Gere vídeos de desempenho naturais e realistas a partir de entrada multimodal (texto, imagem, vídeo) usando o Wan Modelo 2.7 (wan2.7-r2v).
- Retrato do personagem: replique a aparência de um personagem a partir de uma imagem ou vídeo de referência. Os vídeos de referência também reproduzem o timbre da voz. Suporta performances de um ou vários caracteres com até 5 ativos de referência.
- Entrada de matriz de mídia: forneça imagens de referência, vídeos ou um primeiro quadro por meio do
mediamatriz. UsarVideo 1/Image 1em prompts para fazer referência aos caracteres por ordem. Imagens e vídeos são contados separadamente. - Storyboard de vários painéis: descreva narrativas de vários planos com segmentos de tempo (por exemplo,
Scene 1 [0-3s]: ...). Forneça fotos importantes e o modelo reconhecerá automaticamente a lógica do painel. - Clonagem de voz: fornece um
reference_voicearquivo de áudio para definir o timbre da voz. Se não for especificado, o áudio do vídeo de referência será usado por padrão. - Resolução e proporção: defina a qualidade de saída com
resolution(720P/1080P) e proporção comratio(16:9, 9:16, 1:1, 4:3, 3:4). Quando umfirst_framea imagem é fornecida,ratioé inferido a partir da imagem. - Aprimoramento de prompt: Ativar
prompt_extendpara reescrever o prompt com um LLM. Melhora os resultados para prompts mais curtos, mas aumenta o tempo de processamento.
OpenAPI
openapi: 3.1.0
info:
title: Wan 2.7 Reference-to-Video API
description: Wan 2.7 reference-to-video API. Generates performance videos from reference images or videos with multimodal input (text, image, video). Uses the new protocol with media array input, resolution+ratio parameters, and enhanced response metadata.
version: 1.0.0
servers:
- url: https://maas.qwencloudapi.com/api/v1
description: Singapore
security:
- BearerAuth: []
paths:
/services/aigc/video-generation/video-synthesis:
post:
operationId: createWan27RefToVideo
summary: Create Wan 2.7 reference-to-video task
description: Create a Wan 2.7 reference-to-video generation task.
parameters:
- name: X-DashScope-Async
in: header
required: true
description: Must be `enable` to create an asynchronous task.
schema:
type: string
enum:
- enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Wan27RefToVideoRequest"
responses:
"200":
description: Task created successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
"400":
description: Invalid request parameters.
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL - Multi-subject reference
source: |-
curl --location 'https://maas.qwencloudapi.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.7-r2v-2026-06-12",
"input": {
"prompt": "Video 2 holds Image 3 and plays a soothing American country ballad in a coffee shop, while Video 1 smiles, watches Video 2, and slowly walks towards him",
"media": [
{"type": "reference_video", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/hfugmr/wan-r2v-role1.mp4"},
{"type": "reference_video", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4"},
{"type": "reference_image", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"}
]
},
"parameters": {
"resolution": "720P",
"duration": 10,
"prompt_extend": false,
"watermark": true
}
}'
- lang: curl
label: cURL - Single-image reference
source: |-
curl --location 'https://maas.qwencloudapi.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.7-r2v-2026-06-12",
"input": {
"prompt": "Based on the reference image, in the style of a 3D cartoon adventure movie. The characters are in a cute Q-style but with detailed textures, smooth movements, and vibrant colors. Keep the characters and the forest scene consistent. Do not add text. Atmosphere: Adventurous, light-hearted, mysterious, whimsical. Characters: A young boy explorer with a round hat, backpack, and short cloak. His sidekick: a small flying robot with a round body and glowing blue eyes. Scene: A magical forest with giant tree roots, mushrooms, vines, a treasure cave entrance, and sunbeams. Storyboard: 1. Wide shot: Tall trees and intersecting sunbeams in the magical forest, creating a mysterious and bright environment. 2. Medium shot: The little boy pushes aside vines to explore forward. 3. Medium shot: The little robot flies beside him, scanning ahead with its blue light. 4. Close-up: An old treasure map unfolds in his hands. 5. Close-up: His face lights up with excitement. 6. Action shot: The two jump over tree roots and a small stream, venturing deeper into the forest. 7. Medium shot: A moss-covered treasure chest is revealed behind the vines. 8. Close-up: A golden glow emanates from the edge of the chest. 9. Final shot: The boy and the robot stand before the chest, looking at each other in surprise, filled with a sense of adventure.",
"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
}
}'
- lang: python
label: Python - Synchronous call
source: |-
import os
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
def sample_sync_call():
print('Please wait...')
rsp = VideoSynthesis.call(
api_key=api_key,
model='wan2.7-r2v-2026-06-12',
prompt='A person walking in a garden, natural lighting',
media=[
{
"type": "reference_video",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/hfugmr/wan-r2v-role1.mp4"
}
],
resolution='720P',
duration=5,
prompt_extend=True,
watermark=True)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output.video_url)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
if __name__ == '__main__':
sample_sync_call()
- lang: python
label: Python - Asynchronous call
source: |-
import os
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
def sample_async_call():
rsp = VideoSynthesis.async_call(
api_key=api_key,
model='wan2.7-r2v-2026-06-12',
prompt='A person walking in a garden, natural lighting',
media=[
{
"type": "reference_video",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/hfugmr/wan-r2v-role1.mp4"
}
],
resolution='720P',
duration=5,
prompt_extend=True,
watermark=True)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print("task_id: %s" % rsp.output.task_id)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
rsp = VideoSynthesis.wait(task=rsp, api_key=api_key)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output.video_url)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
if __name__ == '__main__':
sample_async_call()
- lang: java
label: Java - Synchronous call
source: |-
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;
import java.util.*;
public class Wan27R2V {
static {
Constants.baseHttpApiUrl = "https://maas.qwencloudapi.com/api/v1";
}
public static void main(String[] args) {
try {
VideoSynthesis vs = new VideoSynthesis();
List<VideoSynthesisParam.Media> media = new ArrayList<VideoSynthesisParam.Media>() {{
add(VideoSynthesisParam.Media.builder()
.url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/hfugmr/wan-r2v-role1.mp4")
.type("reference_video").build());
}};
Map<String, Object> parameters = new HashMap<>();
parameters.put("resolution", "720P");
parameters.put("duration", 5);
parameters.put("prompt_extend", true);
parameters.put("watermark", true);
VideoSynthesisParam param = VideoSynthesisParam.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("wan2.7-r2v-2026-06-12")
.prompt("A person walking in a garden, natural lighting")
.media(media)
.parameters(parameters)
.build();
System.out.println("Please wait...");
VideoSynthesisResult result = vs.call(param);
System.out.println(JsonUtils.toJson(result));
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.println(e.getMessage());
}
}
}
- lang: java
label: Java - Asynchronous call
source: |-
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;
import java.util.*;
public class Wan27R2V {
static {
Constants.baseHttpApiUrl = "https://maas.qwencloudapi.com/api/v1";
}
public static void main(String[] args) {
try {
String apiKey = System.getenv("DASHSCOPE_API_KEY");
VideoSynthesis vs = new VideoSynthesis();
List<VideoSynthesisParam.Media> media = new ArrayList<VideoSynthesisParam.Media>() {{
add(VideoSynthesisParam.Media.builder()
.url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/hfugmr/wan-r2v-role1.mp4")
.type("reference_video").build());
}};
Map<String, Object> parameters = new HashMap<>();
parameters.put("resolution", "720P");
parameters.put("duration", 5);
parameters.put("prompt_extend", true);
parameters.put("watermark", true);
VideoSynthesisParam param = VideoSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.7-r2v-2026-06-12")
.prompt("A person walking in a garden, natural lighting")
.media(media)
.parameters(parameters)
.build();
VideoSynthesisResult task = vs.asyncCall(param);
System.out.println(JsonUtils.toJson(task));
System.out.println("Please wait...");
VideoSynthesisResult result = vs.wait(task, apiKey);
System.out.println(JsonUtils.toJson(result));
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.println(e.getMessage());
}
}
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: DashScope API Key. Create one in the [QwenCloud console](https://home.qwencloud.com/api-keys).
schemas:
Wan27RefToVideoRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: Model name.
enum:
- wan2.7-r2v
- wan2.7-r2v-2026-06-12
example: wan2.7-r2v
input:
$ref: "#/components/schemas/Wan27RefToVideoInput"
parameters:
$ref: "#/components/schemas/Wan27RefToVideoParameters"
Wan27RefToVideoInput:
type: object
required:
- prompt
- media
description: Input data for Wan 2.7 reference-to-video generation.
properties:
prompt:
type: string
maxLength: 5000
description: |-
Text prompt describing the desired video content. Supports Chinese and English. Each Chinese character, letter, and punctuation mark counts as one character. Text that exceeds the limit is automatically truncated.
**Reference identifiers**: Use `Image 1`, `Image 2`, etc. to reference characters from reference images, and `Video 1`, `Video 2`, etc. to reference characters from reference videos. The numbering matches the order in the `media` array. Images and videos are counted separately — `Image 1` and `Video 1` can coexist. If there is only one reference image or video, you can use `the reference image` or `the reference video` instead.
**Scene description**: Two approaches — (1) Use identifiers directly: "Image 1 is playing in Image 2"; (2) Supplement with subject/scene context: "The cat from Image 1 is playing in the room from Image 2".
**Multi-panel storyboard**: Describe multi-shot narratives with time segments (e.g., `Scene 1 [0-3s]: ...`). You do not need to describe every panel — provide key shots, and the model automatically recognizes the panel logic.
example: Video 2 holds Image 3 and plays a soothing American country ballad in a coffee shop
negative_prompt:
type: string
maxLength: 500
description: "Content to exclude from the generated video. Supports Chinese and English. Maximum 500 characters. Text that exceeds the limit is automatically truncated. Example values: `low resolution, error, worst quality, low quality, disfigured, extra fingers, bad proportions`."
media:
type: array
description: |-
Array of reference media objects. Each object has a `type` and `url`. Supports image and video input for visual reference. Images support multiple views, commonly for referencing characters, props, and scenes.
**Ordering**: The first `reference_video` in the array is `Video 1`, the second is `Video 2`, and so on. The first `reference_image` is `Image 1`, the second is `Image 2`. Images and videos are counted separately.
**Limits**: At least 1 reference image or video is required. Total images + videos must not exceed 5. At most 1 `first_frame` is allowed. Each reference image or video should contain a single character when used for main character portrayal.
items:
$ref: "#/components/schemas/MediaItem"
minItems: 1
maxItems: 5
reference_voice:
type: string
format: uri
description: |-
URL of a reference audio file for voice timbre. Used with `reference_image` or `reference_video` to specify the voice timbre for the main character. This audio is used only for voice timbre reference and is not related to the spoken content.
Supported formats: WAV, MP3. Duration: 1-10 seconds. Max file size: 15 MB.
**Default behavior**: If `reference_video` has audio and `reference_voice` is not specified, the original video audio is used as the voice timbre.
**Priority**: If both `reference_video` audio and `reference_voice` are provided, `reference_voice` takes priority.
For best results, the language of the reference audio should match the language of the prompt.
MediaItem:
type: object
required:
- type
- url
description: A reference media item (image, video, or first frame).
properties:
type:
type: string
description: |-
Type of reference media.
- `reference_image`: Reference image containing a single character or object. Supported formats: JPEG, JPG, PNG (alpha channel not supported), BMP, WEBP. Resolution: 240-8000 px per side. Aspect ratio: 1:8 to 8:1. Max file size: 20 MB.
- `reference_video`: Reference video containing a single character. Supported formats: MP4, MOV. Duration: 1-30 seconds. Resolution: 240-4096 px per side. Aspect ratio: 1:8 to 8:1. Max file size: 100 MB.
- `first_frame`: First frame image for the generated video. At most 1 allowed. Supported formats and constraints same as `reference_image`. When used with subject references, two modes apply: (1) Subject already in the first frame — use subject reference to enhance character consistency or reference voice timbre. (2) Subject not in the first frame — use subject reference to define features of a new character appearing during the video.
enum:
- reference_image
- reference_video
- first_frame
url:
type: string
format: uri
description: URL of the reference media file.
Wan27RefToVideoParameters:
type: object
description: Generation parameters for Wan 2.7 reference-to-video.
properties:
resolution:
type: string
description: |-
Video clarity tier. Higher resolution costs more.
Actual output dimensions depend on `ratio`:
- **720P**: 16:9=1280x720, 9:16=720x1280, 1:1=960x960, 4:3=1104x832, 3:4=832x1104
- **1080P**: 16:9=1920x1080, 9:16=1080x1920, 1:1=1440x1440, 4:3=1648x1248, 3:4=1248x1648
enum:
- 720P
- 1080P
default: 1080P
ratio:
type: string
description: Aspect ratio of the output video. When a `first_frame` image is provided, `ratio` is ignored and the video uses the image's aspect ratio.
enum:
- 16:9
- 9:16
- 1:1
- 4:3
- 3:4
default: 16:9
duration:
type: integer
description: "Video duration in seconds. Longer videos cost more -- billing is per second. Conditional range: if reference material includes a video, the range is 2-10; if reference material does not include a video (images only), the range is 2-15."
minimum: 2
maximum: 15
default: 5
prompt_extend:
type: boolean
description: Whether to rewrite the prompt using a large language model. Improves results for shorter prompts but increases processing time.
default: true
seed:
type: integer
description: Random seed for reproducible generation. If not specified, a random seed is generated. A fixed seed improves reproducibility, but because model generation is probabilistic, the same seed does not guarantee identical results.
minimum: 0
maximum: 2147483647
watermark:
type: boolean
description: Whether to add an "AI Generated" watermark to the lower-right corner of the output video.
default: false
AsyncTaskSubmitResponse:
type: object
description: Response returned when an asynchronous task is created successfully.
properties:
request_id:
type: string
description: Unique request identifier.
output:
type: object
properties:
task_id:
type: string
description: Task identifier. Use this with `GET /tasks/{task_id}` to poll for results.
task_status:
type: string
description: Initial task status, typically `PENDING`.
enum:
- PENDING
TaskStatusResponse:
type: object
description: Response containing the current status and results of a Wan 2.7 reference-to-video task.
properties:
request_id:
type: string
description: Unique request identifier.
output:
type: object
properties:
task_id:
type: string
description: Task identifier.
task_status:
type: string
description: Current task status.
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: Task submission time in UTC+8 format (e.g., `2026-04-02 22:53:19.537`).
scheduled_time:
type: string
description: Task scheduling time in UTC+8 format.
end_time:
type: string
description: Task completion time in UTC+8 format.
orig_prompt:
type: string
description: The original prompt before any prompt extension was applied.
video_url:
type: string
format: uri
description: Generated video URL (MP4, H.264 codec). Only present when `task_status` is `SUCCEEDED`. Valid for 24 hours — download promptly.
code:
type: string
description: Error code. Only present when `task_status` is `FAILED`.
message:
type: string
description: Error message. Only present when `task_status` is `FAILED`.
usage:
type: object
description: Usage statistics (only present when task succeeds).
properties:
duration:
type: integer
description: Total billable duration in seconds (equals `input_video_duration` + `output_video_duration`).
input_video_duration:
type: integer
description: Duration of the input reference video(s) in seconds.
output_video_duration:
type: integer
description: Duration of the generated output video in seconds.
video_count:
type: integer
description: Number of videos generated (always 1).
SR:
type: integer
description: Resolution of the generated video (e.g., 720 or 1080).
ratio:
type: string
description: Aspect ratio of the generated video (e.g., `16:9`).
DashScopeErrorResponse:
type: object
description: DashScope API error response.
properties:
request_id:
type: string
description: Unique request identifier.
code:
type: string
description: Error code (e.g., `InvalidParameter`, `Throttling`, `Unauthorized`).
example: InvalidParameter
message:
type: string
description: Human-readable error message.
example: "Invalid parameter: resolution"