The Wan reference-to-video model accepts multimodal input and generates single-character or multi-character interaction videos using people or objects as protagonists.
See also: User guide
The model, endpoint URL, and API key must belong to the same region. Cross-region calls will fail.
Video generation tasks typically take 1–5 minutes. The API uses asynchronous calls with two steps: "create a task -> poll for the result". Details are as follows:
SDK parameters follow the same naming conventions as the HTTP API, with language-specific wrappers.
Reference-to-video tasks typically take 1–5 minutes. The SDK wraps the HTTP asynchronous workflow and supports both synchronous and asynchronous calls.
Set
Set
If the model call fails and returns an error message, see Error codes for resolution.
Availability
The model, endpoint URL, and API key must belong to the same region. Cross-region calls will fail.
- Select a model: Confirm the region of the model.
- Select a URL: Use the endpoint URL for the corresponding region. HTTP URLs are supported.
- Configure API key: Select a region and Obtain an API key, then Configure API key as an environment variable.
The sample code in this topic applies to the Singapore region.
HTTP
Video generation tasks typically take 1–5 minutes. The API uses asynchronous calls with two steps: "create a task -> poll for the result". Details are as follows:
Step 1: Create a task
- Singapore
- US (Virginia)
- Frankfurt
- China (Beijing)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesisReplace {WorkspaceId} with your actual workspace ID.- After the task is created, use the returned
task_idto query the result. Thetask_idis valid for 24 hours. Do not create duplicate tasks. Instead, use polling to retrieve the result. - For guidance for beginners, see Call APIs with Postman or cURL.
Request parametersHeadersContent-Typestring (Required)The content type of the request. Must be application/json.Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.X-DashScope-Async string (Required)Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be enable.Request bodymodelstring (Required)The model to use. See Model pricing for available models and pricing.Example: wan2.6-r2v-flash.input object (Required)Input parameters such as the prompt.
Properties prompt string (Required)Text prompt describing the desired elements and visual characteristics of the generated video.Supports Chinese and English. Each character counts as one. Content exceeding the limit is automatically truncated.
string (Optional)Negative prompt describing unwanted elements in the video.Supports Chinese and English. Maximum length: 500 characters. Content exceeding the limit is automatically truncated.Example: low resolution, errors, worst quality, low quality, incomplete, extra fingers, poor proportions, etc.reference_urls array[string] (Required)Array of reference file URLs. Supports both video and image inputs. Used to extract character appearance and voice (if available) to generate videos that match the reference characteristics.
Deprecated reference_video_urls array[string]Array of reference video URLs. Used to extract character appearance and voice (if available) to generate videos that match the reference characteristics.
object (Optional)Video generation parameters such as resolution, prompt rewriting, and watermark.
Properties size string (Optional)Resolution of the generated video, in width*height format. The default value and available options depend on the model parameter:
integer (Optional)Duration of the generated video, in seconds.
string (Optional)Shot composition of the generated video, determining whether the video consists of a single continuous shot or multiple shots.Parameter priority: shot_type > prompt. For example, if shot_type is set to "single", the model outputs a single-shot video even if the prompt says "generate a multi-shot video".Valid values:
Use this parameter to control the narrative structure of the video, such as single-shot for product showcases or multi-shot for story clips. boolean (Optional)Supported model: wan2.6-r2v-flash.Whether to generate audio in the video.Valid values:
boolean (Optional)Whether to add a watermark. The watermark appears in the bottom-right corner with the text "AI-generated".
integer (Optional)The random number seed must be an integer in the range [0, 2147483647].If not specified, a random seed is generated. A fixed seed improves reproducibility.Because model generation is probabilistic, the same seed does not guarantee identical results. |
Pass image and video URLs through reference_urls. Set shot_type to multi for multi-shot video. |
Response parametersoutputobjectTask output.
Properties task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.
Enumeration values
stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes. |
Save the task_id to query the task status and result. |
Step 2: Retrieve task result
- Singapore
- US (Virginia)
- Frankfurt
- China (Beijing)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}Replace {WorkspaceId} with your actual workspace ID.- Polling recommendation: Video generation takes several minutes. Use a polling mechanism with a reasonable interval, such as 15 seconds.
- Task state transition: PENDING → RUNNING → SUCCEEDED or FAILED.
- Result link: After a task succeeds, a video URL valid for 24 hours is returned. Download and save the video to permanent storage, such as OSS.
task_idvalidity: 24 hours. After this period, queries return the task status asUNKNOWN.
Request parametersHeadersAuthorizationstring (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.Path parameterstask_idstring (Required)The ID of the task. |
Replace {task_id} with the task_id value returned by the previous API call. The task_id is valid for queries for 24 hours, Replace {WorkspaceId} with your actual workspace ID. |
Response parametersoutputobjectTask output.
Properties task_id string (Required)The ID of the task.task_status stringTask status.
Enumeration values
stringThe time when the task was submitted. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringThe time when the task was executed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.end_time stringThe time when the task was completed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.video_url stringURL of the generated video. Returned only when task_status is SUCCEEDED.Valid for 24 hours. The video is in MP4 format with H.264 encoding.orig_prompt stringThe original input prompt, corresponding to the request parameter prompt.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.objectUsage statistics. Only counts successful results.
Properties input_video_duration integerDuration of the input reference video, in seconds.output_video_duration integerDuration of the output video, in seconds.duration floatTotal video duration. Billing is based on this value.Formula: duration = input_video_duration + output_video_duration.SR integerResolution tier of the generated video. Example: 720.size stringResolution of the generated video in width*height format. Example: 1280*720.video_count integerNumber of generated videos. Always 1.stringUnique request identifier for tracing and troubleshooting. |
Video URLs are valid for only 24 hours and then automatically purged. Save generated videos promptly. |
DashScope SDK
SDK parameters follow the same naming conventions as the HTTP API, with language-specific wrappers.
Reference-to-video tasks typically take 1–5 minutes. The SDK wraps the HTTP asynchronous workflow and supports both synchronous and asynchronous calls.
Actual processing time depends on the task queue and server load.
Python
Set base_http_api_url based on the model's region:
- Singapore
- China (Beijing)
- Frankfurt
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'Replace {WorkspaceId} with your actual workspace ID.- Synchronous
- Asynchronous
Synchronous calls block until video generation completes and the result is returned.
Request example
Java
Set baseHttpApiUrl based on the model's region:
- Singapore
- China (Beijing)
- Frankfurt
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";Replace {WorkspaceId} with your actual workspace ID.- Synchronous
- Asynchronous
Synchronous calls block until video generation completes and the result is returned.