Wan2.7 - video editing API reference

The Wan 2.7 video editing model accepts multimodal inputs (text, images, and videos) for instruction-based editing and style transfer.

Related documents : Guide

Applicability

The model, endpoint URL, and API Key must all belong to the same region. Cross-region calls fail.

Select a model: Confirm the region of the model.
Select an endpoint URL: Choose the endpoint URL for the corresponding region. Both HTTP and DashScope SDK URLs are supported.
Configure an API Key : Obtain an API Key for the region, then configure it as an environment variable.

Note

Sample code in this topic uses Singapore.

HTTP

Video editing tasks typically take 1 to 5 minutes. The API uses asynchronous calls with two core steps: Create a task -> Poll for the result.

Step 1: Create a task

Singapore

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

Beijing

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

After the task is created, use the returned task_id to query the result. The task_id is valid for 24 hours. Do not create duplicate tasks. Instead, use polling to retrieve the result.
For guidance for beginners, see Postman.

Request parameters

## Instruction-only editing

curl

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.7-videoedit",
 "input": {
 "prompt": "Convert the entire scene to a claymation style",
 "media": \[
 {
 "type": "video",
 "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260402/ldnfdf/wan2.7-videoedit-style-change.mp4"
 }
 \]
 },
 "parameters": {
 "resolution": "720P",
 "prompt_extend": true,
 "watermark": true
 }
 }'

## Instruction and reference image editing

curl

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.7-videoedit",
 "input": {
 "prompt": "Replace the girl''s clothes in the video with the clothes from the image",
 "media": \[
 {
 "type": "video",
 "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260403/nlspwm/T2VA_22.mp4"
 },
 {
 "type": "reference_image",
 "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260402/fwjpqf/wan2.7-videoedit-change-clothes.png"
 }
 \]
 },
 "parameters": {
 "resolution": "720P",
 "prompt_extend": true,
 "watermark": true
 }
 }'

Content-Type *string* (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.

**Important ** If this request header is missing, the error "current user api does not support synchronous calls" is returned.

Request body

model *string* (Required) The model name. Example value: wan2.7-videoedit. input *object* (Required) Input parameters, including the prompt. Properties

prompt *string* (Optional) Describes the desired elements and visual features in the generated video. Both Chinese and English are supported. Each Chinese character or English letter counts as one character. Longer text is automatically truncated.

wan2.7-videoedit: up to 5,000 characters. Example value: Change the character's clothes to a cool, flashy outfit and add the hat from the reference image.

negative_prompt *string* (Optional) A negative prompt that describes content to exclude from the video, which helps refine the output. Both Chinese and English are supported. The length cannot exceed 500 characters. Longer text is automatically truncated. Example value: low resolution, error, worst quality, low quality, disfigured, extra fingers, bad proportions.

media *array* (Required) A list of media assets, such as images and videos, used as references for video generation. Each element in the array is a media object that contains the type and url fields. Properties

type *string* (Required) The type of the media asset. Valid values:

video: Required. The video to be edited.
reference_image: Optional. A reference image. Asset limits:
Only one video is allowed.
Maximum four reference images.

url *string* (Required) The URL or Base64-encoded data of the media asset. Assets include videos and images. Input video (type=video) The URL of the video file to be edited. Video requirements:

Format: MP4, MOV.
Duration: 2--10 s.
Resolution: The width and height must be between 240 and 4096 pixels.
Aspect ratio: 1:8 to 8:1.
File size: Up to 100 MB. Supported input formats:
Public URL: <li> HTTP and HTTPS protocols are supported.
Example value: https://xxx/xxx.mp4. </li>

Input image (type=reference_image) The URL or Base64-encoded data of the reference image. Image requirements:

Format: JPEG, JPG, PNG (alpha channel not supported), BMP, WEBP.
Resolution: The width and height must be between 240 and 8000 pixels.
Aspect ratio: 1:8 to 8:1.
File size: Up to 20 MB. Supported input formats:
Public URL: <li> HTTP and HTTPS protocols are supported.
Example value: https://xxx/xxx.png. </li>
Base64-encoded string: <li> Data format: data:{MIME_type};base64,{base64_data}.
Example value: data:image/png;base64,GDU7MtCZzEbTbmRZ...... (This example is truncated for demonstration purposes).

Base64-encoded data format Format: data:{MIME_type};base64,{base64_data} .

{base64_data}: The Base64-encoded string of the image file.
{MIME_type}: The media type of the image, which must correspond to the file format.

Image format	MIME type
JPEG	image/jpeg
JPG	image/jpeg
PNG	image/png
BMP	image/bmp
WEBP	image/webp

</li>

parameters *object* (Optional) Parameters for video processing, such as resolution, duration, intelligent prompt rewriting, and watermarking. Properties

resolution *string* (Optional) The resolution tier of the generated video, which controls its clarity (total pixels).

wan2.7-videoedit: Valid values are 720P and 1080P. The default value is 1080P.

ratio *string* (Optional) The aspect ratio of the generated video. Behavior:

If you do not specify the ratio parameter, the model generates a video with an aspect ratio similar to that of the input video.
If you specify the ratio parameter, the model generates a video with the specified ratio. Valid values:
16:9
9:16
1:1
4:3
3:4 See the table below for the output video resolution (width × height) for different aspect ratios.

Resolution tier	Aspect ratio	Output video resolution (width*height)
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

duration *integer* (Optional) The duration of the generated video, in seconds. Recommendation: Only set this parameter to truncate the video. To keep the same duration as the input video, omit this parameter or pass the default value of 0. Usage rules:

Default behavior: The default value is 0, which means the duration of the input video is used without truncation.
Truncation: When a specific duration is passed, the system truncates the original video from 0 seconds to the length specified by duration.
Value range: An integer in the range [2, 10].

audio_setting *string* (Optional) Video sound settings.

auto (Default): The model intelligently determines the audio based on the prompt. If the prompt describes sound, new audio might be generated. Otherwise, the original audio of the input asset might be retained.
origin: Forces the retention of the original audio from the input video without regeneration.

**prompt_extend ***boolean* (Optional) Enables intelligent prompt rewriting. When enabled, a large model rewrites the input prompt, significantly improving generation quality for shorter prompts at the cost of increased processing time.

true: Default value. Enables intelligent rewriting.
false: Disables intelligent rewriting.

watermark *boolean* (Optional) Whether to add a watermark. The watermark is in the lower-right corner of the video with the text "AI Generated".

false (default)
true Example: false.

seed *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.

Response parameters

Successful response

Save the task_id to query the task status and result.

json

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

Error response

Task creation failed. See Error messages.

json

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

     **output** `*object*`  Contains the task output.

Properties

task_id *string* The task ID. Valid for queries for 24 hours.

task_status *string* The status of the task. Enumeration values

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: The task does not exist or its status is unknown.

request_id *string* Unique request identifier for tracing and troubleshooting.

code *string* Error code. Returned only for failed requests. See Error messages.

message *string* Detailed error message. Returned only for failed requests. See Error messages.

Step 2: Query the result

Singapore

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

Beijing

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

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_id****validity : 24 hours . After this period, queries return the task status as UNKNOWN.

Request parameters

## Query result

Replace {task_id} with the task_id value returned by the previous API call. The task_id is valid for queries for 24 hours.

curl

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

Headers

Authorization *string* (Required) Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

Path parameters

task_id *string* (Required) The ID of the task.

Response parameters

## Task succeeded

Video URLs are valid for only 24 hours and then automatically purged. Save generated videos promptly.

json

{
 "request_id": "f16ae7e9-d518-92f8-a02c-xxxxxx",
 "output": {
 "task_id": "05e68c7e-850c-49e4-b866-xxxxxx",
 "task_status": "SUCCEEDED",
 "submit_time": "2026-04-03 00:08:03.576",
 "scheduled_time": "2026-04-03 00:08:13.408",
 "end_time": "2026-04-03 00:11:57.286",
 "orig_prompt": "Replace the girl''s clothes in the video with the clothes from the image",
 "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?xxxx"
 },
 "usage": {
 "duration": 10.04,
 "input_video_duration": 5.02,
 "output_video_duration": 5.02,
 "video_count": 1,
 "SR": 720
 }
}

## Task failed

When a task fails, task_status is FAILED with an error code and message. See Error messages.

json

{
 "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"
 }
}

## Expired query

The task_id is valid for 24 hours. After this period, queries return the following error.

json

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

     **output **`*object*`* * Contains the task output.

Properties

task_id *string* The task ID. Valid for queries for 24 hours.

task_status *string* The status of the task. Enumeration values

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: The task does not exist or its status is unknown.

State transitions during polling:

PENDING → RUNNING → SUCCEEDED or FAILED.
The initial query status is usually PENDING or RUNNING.
When the status changes to SUCCEEDED, the response contains the generated video URL.
If the status is FAILED, check the error message and retry the task.

submit_time *string* The 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 *string* The 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 *string* The 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 *string* URL 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 *string* The original input prompt, corresponding to the request parameter prompt.

code *string* Error code. Returned only for failed requests. See Error messages.

message *string* Detailed error message. Returned only for failed requests. See Error messages.

usage *object* Usage statistics for billing. Billed only for successful tasks. Properties

input_video_duration *float* The duration of the input video, in seconds.

output_video_duration *float* The duration of the output video, in seconds.

duration *float* The total video duration, which is used for billing. Billing formula: duration=input_video_duration+output_video_duration.

SR *integer* The resolution tier of the output video. Example value: 720.

video_count *integer* The number of generated videos. This value is fixed at 1.

request_id *string* Unique request identifier for tracing and troubleshooting.

DashScope SDK

The parameter names in the SDK are mostly consistent with the HTTP API, but the parameter structure follows each language's conventions.

Video editing typically takes 1 to 5 minutes. The SDK handles the asynchronous HTTP call process internally, supporting both synchronous and asynchronous calls.

Actual processing time depends on the number of queued tasks and service status. Wait for the result to complete.

Python SDK

Important

Ensure you are using DashScope Python SDK version 1.25.16 or later.

Using an older version might trigger errors such as "url error, please check url!". Refer to Install the SDK to update your version.

Set the base_http_api_url based on the service region:

Singapore

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

China (Beijing)

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

Synchronous call

Request example

HELPCODEESCAPE-python
import base64
import mimetypes
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os


dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# If the DASHSCOPE_API_KEY environment variable is not set, provide your Model Studio API key here: api_key="sk-xxx"
# API keys are region-specific. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

# The format is data:{MIME_type};base64,{base64_data}
def encode_file(file_path):
    mime_type, _ = mimetypes.guess_type(file_path)
    if not mime_type or not mime_type.startswith("image/"):
        raise ValueError("Unsupported or unrecognized image format.")
    with open(file_path, "rb") as image_file:
        encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
    return f"data:{mime_type};base64,{encoded_string}"

# The reference_image_url parameter supports the following three input methods.

# Method 1: Use a public URL of an image.
reference_image_url = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260402/fwjpqf/wan2.7-videoedit-change-clothes.png"

# Method 2: Use a local file (absolute and relative paths are supported).
# Format: file:// + file path
# Example (absolute path):
# reference_image_url = "file://" + "/path/to/image.png"     # Linux/macOS
# reference_image_url = "file://" + "C:/path/to/image.png"    # Windows
# Example (relative path):
# reference_image_url = "file://" + "./image.png"             # Relative to the path of the current script.

# Method 3: A Base64-encoded string.
# reference_image_url = encode_file("/path/to/image.png")

def sample_sync_call_videoedit():
    # Call the synchronous API, which will return the result directly.
    print('Please wait...')
    rsp = VideoSynthesis.call(
        api_key=api_key,
        model='wan2.7-videoedit',
        prompt='Replace the clothes of the girl in the video with the clothes from the image.',
        media=[
            {
                "type": "video",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260403/nlspwm/T2VA_22.mp4"
            },
            {
                "type": "reference_image",
                "url": reference_image_url
            }
        ],
        resolution='720P',
        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_videoedit()

Response example

The video_url is valid for 24 hours. Please download the video promptly.

HELPCODEESCAPE-json
{
    "status_code": 200,
    "request_id": "d6c3c865-34e9-98a9-a53d-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "1de7c853-755a-454a-91bc-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxxx",
        "submit_time": "2026-04-10 17:16:30.821",
        "scheduled_time": "2026-04-10 17:16:46.379",
        "end_time": "2026-04-10 17:24:59.352",
        "orig_prompt": "Replace the clothes of the girl in the video with the clothes from the image."
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 10.08,
        "input_video_duration": 5.04,
        "output_video_duration": 5.04,
        "SR": 720
    }
}

Asynchronous call

Request example

HELPCODEESCAPE-python
import base64
import mimetypes
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os

# The following is the URL for the Singapore region. The URL is region-specific.
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# If the DASHSCOPE_API_KEY environment variable is not set, provide your Model Studio API key here: api_key="sk-xxx"
# API keys are region-specific. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

# The format is data:{MIME_type};base64,{base64_data}
def encode_file(file_path):
    mime_type, _ = mimetypes.guess_type(file_path)
    if not mime_type or not mime_type.startswith("image/"):
        raise ValueError("Unsupported or unrecognized image format.")
    with open(file_path, "rb") as image_file:
        encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
    return f"data:{mime_type};base64,{encoded_string}"

# The reference_image_url parameter supports the following three input methods.

# Method 1: Use a public URL of an image.
reference_image_url = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260402/fwjpqf/wan2.7-videoedit-change-clothes.png"

# Method 2: Use a local file (absolute and relative paths are supported).
# Format: file:// + file path
# Example (absolute path):
# reference_image_url = "file://" + "/path/to/image.png"     # Linux/macOS
# reference_image_url = "file://" + "C:/path/to/image.png"    # Windows
# Example (relative path):
# reference_image_url = "file://" + "./image.png"             # Relative to the path of the current script.

# Method 3: A Base64-encoded string.
# reference_image_url = encode_file("/path/to/image.png")

def sample_async_call_videoedit():
    # Call the asynchronous API, which returns task information.
    # You can then check the task status using the returned task ID.
    rsp = VideoSynthesis.async_call(
        api_key=api_key,
        model='wan2.7-videoedit',
        prompt='Replace the clothes of the girl in the video with the clothes from the image.',
        media=[
            {
                "type": "video",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260403/nlspwm/T2VA_22.mp4"
            },
            {
                "type": "reference_image",
                "url": reference_image_url
            }
        ],
        resolution='720P',
        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))

    # Get the task information, which includes the task status.
    status = VideoSynthesis.fetch(task=rsp, api_key=api_key)
    if status.status_code == HTTPStatus.OK:
        print(status.output.task_status)  # Check the task status.
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (status.status_code, status.code, status.message))

    # Wait for the task to complete. This method polls at intervals until the task is finished.
    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_videoedit()

Response examples

Task creation response

HELPCODEESCAPE-json
{
    "status_code": 200,
    "request_id": "f16ae7e9-d518-92f8-a02c-xxxxxx",
    "code": "",
    "message": "",
    "output": {
        "task_id": "05e68c7e-850c-49e4-b866-xxxxxx",
        "task_status": "PENDING",
        "video_url": ""
    },
    "usage": null
}

Task query response

The video_url is valid for 24 hours. Please download the video promptly.

HELPCODEESCAPE-json
{
    "status_code": 200,
    "request_id": "d6c3c865-34e9-98a9-a53d-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "1de7c853-755a-454a-91bc-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxxx",
        "submit_time": "2026-04-10 17:16:30.821",
        "scheduled_time": "2026-04-10 17:16:46.379",
        "end_time": "2026-04-10 17:24:59.352",
        "orig_prompt": "Replace the clothes of the girl in the video with the clothes from the image."
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 10.08,
        "input_video_duration": 5.04,
        "output_video_duration": 5.04,
        "SR": 720
    }
}

Java SDK

Important

Ensure you are using DashScope Java SDK version 2.22.14 or later.

Using an older version might trigger errors such as "url error, please check url!". Refer to Install the SDK to update your version.

Set the Constants.baseHttpApiUrl based on the service region:

Singapore

Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";

China (Beijing)

Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";

Synchronous call

Request example

HELPCODEESCAPE-java
// Copyright (c) Alibaba, Inc. and its affiliates.

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.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Base64;

public class VideoEdit {

    static {
        // The following is the URL for the Singapore region. The URL is region-specific.
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
    }

    // If the DASHSCOPE_API_KEY environment variable is not set, provide your Model Studio API key here: apiKey="sk-xxx"
    // API keys are region-specific. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    // The referenceImageUrl parameter supports the following three input methods.

    // Method 1: Use a public URL of an image.
    static String referenceImageUrl = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260402/fwjpqf/wan2.7-videoedit-change-clothes.png";

    // Method 2: Use a local file (absolute and relative paths are supported).
    // Format: file:// + file path
    // Example (absolute path):
    // static String referenceImageUrl = "file://" + "/path/to/image.png";     // Linux/macOS
    // static String referenceImageUrl = "file://" + "C:/path/to/image.png";   // Windows
    // Example (relative path):
    // static String referenceImageUrl = "file://" + "./image.png";             // Relative to the path of the current executable.

    // Method 3: Use Base64 encoding.
    // static String referenceImageUrl = encodeFile("/path/to/image.png");

    // The format is data:{MIME_type};base64,{base64_data}
    public static String encodeFile(String filePath) {
        Path path = Paths.get(filePath);
        if (!Files.exists(path)) {
            throw new IllegalArgumentException("File does not exist: " + filePath);
        }
        String mimeType = null;
        try {
            mimeType = Files.probeContentType(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("Cannot detect file type: " + filePath);
        }
        if (mimeType == null || !mimeType.startsWith("image/")) {
            throw new IllegalArgumentException("Unsupported or unrecognized image format.");
        }
        byte[] fileBytes = null;
        try {
            fileBytes = Files.readAllBytes(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("Cannot read file content: " + filePath);
        }
        String encodedString = Base64.getEncoder().encodeToString(fileBytes);
        return "data:" + mimeType + ";base64," + encodedString;
    }

    public static void videoEdit() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        List&lt;VideoSynthesisParam.Media&gt; media = new ArrayList&lt;VideoSynthesisParam.Media&gt;(){{
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260403/nlspwm/T2VA_22.mp4")
                    .type("video")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url(referenceImageUrl)
                    .type("reference_image")
                    .build());
        }};
        Map&lt;String, Object&gt; parameters = new HashMap<>();
        parameters.put("resolution", "720P");
        parameters.put("prompt_extend", true);
        parameters.put("watermark", true);

        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.7-videoedit")
                        .prompt("Replace the clothes of the girl in the video with the clothes from the image.")
                        .media(media)
                        .parameters(parameters)
                        .build();
        System.out.println("Please wait...");
        VideoSynthesisResult result = vs.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            videoEdit();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

Response example

The video_url is valid for 24 hours. Please download the video promptly.

HELPCODEESCAPE-json
{
    "request_id": "0a15ad3c-cde7-9f7e-b8d2-xxxxxx",
    "output": {
        "task_id": "0025d1e1-009a-4f53-9c27-xxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
        "orig_prompt": "Replace the clothes of the girl in the video with the clothes from the image.",
        "submit_time": "2026-04-10 17:21:01.719",
        "scheduled_time": "2026-04-10 17:21:13.182",
        "end_time": "2026-04-10 17:31:41.286"
    },
    "usage": {
        "video_count": 1,
        "duration": 10.08,
        "input_video_duration": 5.04,
        "output_video_duration": 5.04,
        "SR": "720"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Asynchronous call

Request example

HELPCODEESCAPE-java
// Copyright (c) Alibaba, Inc. and its affiliates.

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.aigc.videosynthesis.VideoSynthesisListResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.task.AsyncTaskListParam;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Base64;

public class VideoEdit {

    static {
        // The following is the URL for the Singapore region. The URL is region-specific.
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
    }

    // If the DASHSCOPE_API_KEY environment variable is not set, provide your Model Studio API key here: apiKey="sk-xxx"
    // API keys are region-specific. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    // The referenceImageUrl parameter supports the following three input methods.

    // Method 1: Use a public URL of an image.
    static String referenceImageUrl = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260402/fwjpqf/wan2.7-videoedit-change-clothes.png";

    // Method 2: Use a local file (absolute and relative paths are supported).
    // Format: file:// + file path
    // Example (absolute path):
    // static String referenceImageUrl = "file://" + "/path/to/image.png";     // Linux/macOS
    // static String referenceImageUrl = "file://" + "C:/path/to/image.png";   // Windows
    // Example (relative path):
    // static String referenceImageUrl = "file://" + "./image.png";             // Relative to the path of the current executable.

    // Method 3: Use Base64 encoding.
    // static String referenceImageUrl = encodeFile("/path/to/image.png");

    // The format is data:{MIME_type};base64,{base64_data}
    public static String encodeFile(String filePath) {
        Path path = Paths.get(filePath);
        if (!Files.exists(path)) {
            throw new IllegalArgumentException("File does not exist: " + filePath);
        }
        String mimeType = null;
        try {
            mimeType = Files.probeContentType(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("Cannot detect file type: " + filePath);
        }
        if (mimeType == null || !mimeType.startsWith("image/")) {
            throw new IllegalArgumentException("Unsupported or unrecognized image format.");
        }
        byte[] fileBytes = null;
        try {
            fileBytes = Files.readAllBytes(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("Cannot read file content: " + filePath);
        }
        String encodedString = Base64.getEncoder().encodeToString(fileBytes);
        return "data:" + mimeType + ";base64," + encodedString;
    }

    public static void videoEdit() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        List&lt;VideoSynthesisParam.Media&gt; media = new ArrayList&lt;VideoSynthesisParam.Media&gt;(){{
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260403/nlspwm/T2VA_22.mp4")
                    .type("video")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url(referenceImageUrl)
                    .type("reference_image")
                    .build());
        }};
        Map&lt;String, Object&gt; parameters = new HashMap<>();
        parameters.put("resolution", "720P");
        parameters.put("prompt_extend", true);
        parameters.put("watermark", true);

        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.7-videoedit")
                        .prompt("Replace the clothes of the girl in the video with the clothes from the image.")
                        .media(media)
                        .parameters(parameters)
                        .build();

        // Make an asynchronous call.
        VideoSynthesisResult task = vs.asyncCall(param);
        System.out.println(JsonUtils.toJson(task));
        System.out.println("Please wait...");

        // Wait for the task to complete and retrieve the final result.
        VideoSynthesisResult result = vs.wait(task, apiKey);
        System.out.println(JsonUtils.toJson(result));
    }

    // Retrieve the task list.
    public static void listTask() throws ApiException, NoApiKeyException {
        VideoSynthesis is = new VideoSynthesis();
        AsyncTaskListParam param = AsyncTaskListParam.builder().build();
        param.setApiKey(apiKey);
        VideoSynthesisListResult result = is.list(param);
        System.out.println(result);
    }

    // Retrieve the result of a single task.
    public static void fetchTask(String taskId) throws ApiException, NoApiKeyException {
        VideoSynthesis is = new VideoSynthesis();
        // The apiKey can be null if the DASHSCOPE_API_KEY environment variable is set.
        VideoSynthesisResult result = is.fetch(taskId, apiKey);
        System.out.println(result.getOutput());
        System.out.println(result.getUsage());
    }

    public static void main(String[] args) {
        try {
            videoEdit();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

Response examples

Task creation response

HELPCODEESCAPE-json
{
    "request_id": "f16ae7e9-d518-92f8-a02c-xxxxxx",
    "output": {
        "task_id": "05e68c7e-850c-49e4-b866-xxxxxx",
        "task_status": "PENDING",
        "video_url": ""
    },
    "usage": null,
    "status_code": 200,
    "code": "",
    "message": ""
}

Task query response

The video_url is valid for 24 hours. Please download the video promptly.

HELPCODEESCAPE-json
{
    "request_id": "0a15ad3c-cde7-9f7e-b8d2-xxxxxx",
    "output": {
        "task_id": "0025d1e1-009a-4f53-9c27-xxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
        "orig_prompt": "Replace the clothes of the girl in the video with the clothes from the image.",
        "submit_time": "2026-04-10 17:21:01.719",
        "scheduled_time": "2026-04-10 17:21:13.182",
        "end_time": "2026-04-10 17:31:41.286"
    },
    "usage": {
        "video_count": 1,
        "duration": 10.08,
        "input_video_duration": 5.04,
        "output_video_duration": 5.04,
        "SR": "720"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Error codes

If a model call fails, refer to Error messages for troubleshooting.

Wan2.7 - video editing API reference ​

Applicability ​

HTTP ​

Step 1: Create a task ​

Singapore ​

Beijing ​

Request parameters ​

## Instruction-only editing ​

## Instruction and reference image editing ​

Request body ​

Response parameters ​

Successful response ​

Error response ​

Step 2: Query the result ​

Singapore ​

Beijing ​

Request parameters ​

## Query result ​

Headers ​

Path parameters ​

Response parameters ​

## Task succeeded ​

## Task failed ​

## Expired query ​

DashScope SDK ​

Python SDK ​

Singapore ​

China (Beijing) ​

Synchronous call ​

Request example ​

Response example ​

Asynchronous call ​

Request example ​

Response examples ​

Java SDK ​

Singapore ​

China (Beijing) ​

Synchronous call ​

Request example ​

Response example ​

Asynchronous call ​

Request example ​

Response examples ​

Error codes ​

Wan2.7 - video editing API reference

Applicability

HTTP

Step 1: Create a task

Singapore

Beijing

Request parameters

## Instruction-only editing

## Instruction and reference image editing

Request body

Response parameters

Successful response

Error response

Step 2: Query the result

Singapore

Beijing

Request parameters

## Query result

Headers

Path parameters

Response parameters

## Task succeeded

## Task failed

## Expired query

DashScope SDK

Python SDK

Singapore

China (Beijing)

Synchronous call

Request example

Response example

Asynchronous call

Request example

Response examples

Java SDK

Singapore

China (Beijing)

Synchronous call

Request example

Response example

Asynchronous call

Request example

Response examples

Error codes