VACE Unified Video Editing

Doc version：v1.0.0 | Last updated：2026-07-22
This platform fully supports the official Tongyi Wanxiang (Wan) video generation API. Requests and responses are transparently proxied; parameter semantics are identical to the official API.

The Wan 2.1 unified video editing model (wanx2.1-vace-plus) supports multimodal input — text / image / video — and switches between five editing capabilities within a single endpoint via input.function. Tasks are asynchronous: creating a task returns output.task_id, then poll the query endpoint for results. Generation typically takes about 5–10 minutes.

Capability Overview

function	Capability	Key inputs
`image_reference`	Multi-Image Reference to video	`ref_images_url` (1–3 reference images, subject/background) + prompt; blends them into a coherent video
`video_repainting`	Video Repainting	`video_url`; extracts subject motion / composition contours / line-art structure (`control_condition`) and regenerates; optionally add 1 reference image to replace the subject
`video_edit`	Video Edit (inpainting)	`video_url` + mask (`mask_image_url` / `mask_video_url`, one of the two); add / modify / remove elements in the specified region
`video_extension`	Video Extension	First/last frame images (`first_frame_url` / `last_frame_url`) or first/last video clips (`first_clip_url` / `last_clip_url`); generates continuation content
`video_outpainting`	Video Outpainting	`video_url` + expansion ratios in four directions (`top_scale`, etc.); extends content beyond the frame

Output Specifications

Item	Rule
Duration	Fixed at 5 seconds (`duration` is fixed to 5 and cannot be changed). For Video Repainting / Video Edit / Video Outpainting: output duration = input duration, up to 5 seconds (3s input → 3s output; 6s input → first 5s output)
Resolution	720P tier only. For `image_reference`, specified via `size` (default `1280*720`); for video-input capabilities: inputs ≤720P keep their original resolution, inputs >720P are scaled down by aspect ratio to at most 720P
Format	MP4 (H.264 encoding); the download URL is valid for 24 hours — save the file promptly
Audio	Only silent video is generated; audio output is not supported

video_extension duration note (important): The output of Video Extension has a total duration of 5 seconds, meaning "input clip + newly generated content" together total 5 seconds — it is not 5 extra seconds appended to the original video. For example, with a 3-second first clip, only about 2 seconds of continuation content is newly generated.

Create Task

POST https://platform.dataeyes.ai/ali/api/v1/services/aigc/video-generation/video-synthesis

Request Headers

Parameter	Type	Required	Default	Description
`Content-Type`	string	Yes	application/json	Data exchange format
`Authorization`	string	Yes		Authentication, `Bearer {API_KEY}`

The X-DashScope-Async: enable header required by the official API is added automatically by the platform — you do not need to include it.

Common Parameters

The following parameters are shared by all functions:

Parameter	Type	Required	Default	Description
`model`	string	Yes		Model identifier, fixed to `wanx2.1-vace-plus`
`input`	object	Yes		Basic input information
`input.function`	string	Yes		Capability switch: `image_reference`, `video_repainting`, `video_edit`, `video_extension`, `video_outpainting`
`input.prompt`	string	Yes		Text prompt, in Chinese or English, length ≤ 800 characters; longer prompts are automatically truncated
`parameters`	object	Depends on function		Processing parameters; required for `video_repainting` (must include `control_condition`), optional for the others
`parameters.duration`	integer	No	5	Output video duration in seconds, fixed at 5, cannot be modified
`parameters.prompt_extend`	boolean	No	true	Whether to enable intelligent prompt rewriting. Recommended to set to false for capabilities with video input (rewriting can misinterpret when the text and video content diverge)
`parameters.seed`	integer	No	Random	Random seed, range [0, 2147483647]; the same seed yields relatively stable results
`parameters.watermark`	boolean	No	false	Whether to add an "AI generated" watermark in the bottom-right corner of the video

Function-specific fields are listed below per function.

image_reference (Multi-Image Reference to video)

input-specific fields:

Parameter	Type	Required	Default	Description
`input.ref_images_url`	array[string]	Yes		Array of reference image URLs, 1–3 images (only the first 3 are used if more are provided). Recommendations: each subject image should contain only one subject on a solid-color background; at most 1 background image, containing no subject

parameters-specific fields:

Parameter	Type	Required	Default	Description
`parameters.obj_or_bg`	array[string]	No	`["obj"]` for a single image	Identifies the purpose of each image, in one-to-one correspondence with `ref_images_url`: `obj` = subject image / `bg` = background image (at most 1 `bg`). Explicitly passing it is recommended; its length must match `ref_images_url`, otherwise an error is returned. Example: `["obj","obj","bg"]`
`parameters.size`	string	No	1280*720	Output resolution (720P tier only): `1280720`(16:9), `7201280`(9:16), `960960`(1:1), `8321088`(3:4), `1088*832`(4:3)

video_repainting (Video Repainting)

input-specific fields:

Parameter	Type	Required	Default	Description
`input.video_url`	string	Yes		Input video URL; limits are described in "Common Input Material Limits"
`input.ref_images_url`	array[string]	No		1 image only, preferably a subject image, used to replace the subject in the video (swap the character while keeping the motion)

parameters-specific fields (parameters is required for this capability):

Parameter	Type	Required	Default	Description
`parameters.control_condition`	string	Yes		Control condition extracted from the input video: `posebodyface`: facial expressions + body motion `posebody`: body motion only `depth`: composition and motion contours `scribble`: line-art structure
`parameters.strength`	float	No	1.0	Control strength, range [0.0, 1.0]; larger values stay closer to the motion and composition of the original video

video_edit (Video Edit / inpainting)

input-specific fields:

Parameter	Type	Required	Default	Description
`input.video_url`	string	Yes		Input video URL; limits are described in "Common Input Material Limits"
`input.ref_images_url`	array[string]	No		1 image only, usable as a subject or background image, to replace the content of the edited region
`input.mask_image_url`	string	No		Mask image URL, mutually exclusive with `mask_video_url` (this parameter is preferred). White [255,255,255] = edit region, black [0,0,0] = preserved region. Its resolution must be exactly identical to the input video
`input.mask_frame_id`	integer	No	1	Effective when `mask_image_url` is non-empty; the frame ID where the mask target is located. Range [1, max_frame_id], where max_frame_id = frame rate × duration + 1 (e.g. 16FPS × 5s → 81)
`input.mask_video_url`	string	No		Mask video URL, mutually exclusive with `mask_image_url`. Its format / frame rate / resolution / length must be fully identical to the input video; black/white semantics are the same as above

parameters-specific fields:

Parameter	Type	Required	Default	Description
`parameters.control_condition`	string	No	Empty (no extraction)	Options `posebodyface`, `depth`; `posebodyface` suits scenes where the subject's face is large in frame with clear features
`parameters.mask_type`	string	No	tracking	Effective when `mask_image_url` is non-empty: `tracking` = the edit region follows the target's motion trajectory; `fixed` = the edit region stays fixed
`parameters.expand_ratio`	float	No	0.05	Effective when `mask_type=tracking`; outward expansion ratio of the mask, range [0.0, 1.0]; the default value is recommended
`parameters.expand_mode`	string	No	hull	Effective when `mask_type=tracking`; shape of the mask region: `hull` (polygon) / `bbox` (rectangular bounding box) / `original` (fits the original shape)
`parameters.size`	string	No	1280*720	Same five options as for image_reference

video_extension (Video Extension)

input-specific fields (first/last frame images and first/last video clips are all optional; combine as needed, but at least one must be provided):

Parameter	Type	Required	Description
`input.first_frame_url`	string	No	First frame image URL; extends forward from this frame
`input.last_frame_url`	string	No	Last frame image URL; converges toward this frame
`input.first_clip_url`	string	No	First video clip URL, length ≤ 3 seconds (only the first 3 seconds are used if longer); when used together with a last clip, the two clips' combined duration must be ≤ 3 seconds, and matching frame rates are recommended
`input.last_clip_url`	string	No	Last video clip URL; same limits as `first_clip_url`
`input.video_url`	string	No	Reference video, used to extract motion features to guide generation, in combination with first/last frames or clips. Length ≤ 5 seconds; frame rate ≥ 16FPS and consistent with the first/last clips; resolution consistent with the first/last frames/clips

parameters-specific fields:

Parameter	Type	Required	Default	Description
`parameters.control_condition`	string	Required when `video_url` is provided	Empty (no extraction)	Options `posebodyface`, `depth`

Reminder: the output has a fixed total duration of 5 seconds, which includes the provided first/last clips themselves — it is not 5 seconds appended to the original video.

video_outpainting (Video Outpainting)

input-specific fields:

Parameter	Type	Required	Default	Description
`input.video_url`	string	Yes		Input video URL; limits are described in "Common Input Material Limits"

parameters-specific fields (all four direction ratios are relative to the centered frame; 1.0 = no expansion):

Parameter	Type	Required	Default	Description
`parameters.top_scale`	float	No	1.0	Upward expansion ratio, range [1.0, 2.0]
`parameters.bottom_scale`	float	No	1.0	Downward expansion ratio, range [1.0, 2.0]
`parameters.left_scale`	float	No	1.0	Leftward expansion ratio, range [1.0, 2.0]
`parameters.right_scale`	float	No	1.0	Rightward expansion ratio, range [1.0, 2.0]

Common Input Material Limits

Material	Limits
Images (reference / mask / first-last frames)	Format JPG, JPEG, PNG, BMP, TIFF, WEBP; width and height within [360, 2000] pixels; ≤ 10MB; URL must not contain Chinese characters. Mask image resolution must be exactly identical to the input video
Videos (`video_url`, etc.)	Format MP4; frame rate ≥ 16FPS; ≤ 50MB; length ≤ 5 seconds (only the first 5 seconds are used if longer; video_extension clips ≤ 3 seconds); URL must not contain Chinese characters
URL form	Publicly accessible HTTP/HTTPS address
Number of reference images	`image_reference`: 1–3 images (at most 1 `bg`); `video_repainting` / `video_edit`: 1 image only

Request Example: Multi-Image Reference to video (image_reference)

curl --request POST \
  --url 'https://platform.dataeyes.ai/ali/api/v1/services/aigc/video-generation/video-synthesis' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "wanx2.1-vace-plus",
    "input": {
      "function": "image_reference",
      "prompt": "In the video, a girl gracefully walks out from the depths of an ancient forest shrouded in morning mist, her steps light",
      "ref_images_url": [
        "http://wanx.alicdn.com/material/20250318/image_reference_2_5_16.png",
        "http://wanx.alicdn.com/material/20250318/image_reference_1_5_16.png"
      ]
    },
    "parameters": {
      "prompt_extend": true,
      "obj_or_bg": ["obj", "bg"],
      "size": "1280*720"
    }
  }'

Request Example: Video Repainting (video_repainting)

curl --request POST \
  --url 'https://platform.dataeyes.ai/ali/api/v1/services/aigc/video-generation/video-synthesis' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "wanx2.1-vace-plus",
    "input": {
      "function": "video_repainting",
      "prompt": "The video shows a black steampunk-style car driven by a gentleman, the vehicle adorned with gears and copper pipes",
      "video_url": "http://wanx.alicdn.com/material/20250318/video_repainting_1.mp4"
    },
    "parameters": {
      "prompt_extend": false,
      "control_condition": "depth"
    }
  }'

Request Example: Video Extension (video_extension)

curl --request POST \
  --url 'https://platform.dataeyes.ai/ali/api/v1/services/aigc/video-generation/video-synthesis' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "wanx2.1-vace-plus",
    "input": {
      "function": "video_extension",
      "prompt": "A dog wearing sunglasses skateboarding down the street, 3D cartoon style",
      "first_clip_url": "http://wanx.alicdn.com/material/20250318/video_extension_1.mp4"
    },
    "parameters": {
      "prompt_extend": false
    }
  }'

Response Example

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

Response Fields

Field	Type	Description
`output.task_id`	string	Task ID for querying the result, valid for 24 hours
`output.task_status`	string	Task status, `PENDING` on successful creation
`request_id`	string	Unique request identifier, used for tracing and troubleshooting
`code` / `message`	string	Returned only when creation fails; error code and details (e.g. `InvalidParameter`: size mismatch, `obj_or_bg` length inconsistent with `ref_images_url`, etc.)

Billing

Billed by the number of seconds of output video (a qualitative description; unit prices are subject to the platform's pricing page). After a task succeeds, the usage field in the query result is the billing basis; output is fixed at the 720P tier, up to 5 seconds. Failed tasks incur no charges.

Query Task

Poll the task status using the task_id returned when creating the task; after success, retrieve the video from output.video_url (valid for 24 hours).

GET https://platform.dataeyes.ai/ali/api/v1/tasks/{task_id}

See 09-Query-Task for details.

08-VACE-Video-Editing

VACE Unified Video Editing#

Capability Overview#

Output Specifications#

Create Task#

Request Headers#

Common Parameters#

image_reference (Multi-Image Reference to video)#

video_repainting (Video Repainting)#

video_edit (Video Edit / inpainting)#

video_extension (Video Extension)#

video_outpainting (Video Outpainting)#

Common Input Material Limits#

Request Example: Multi-Image Reference to video (image_reference)#

Request Example: Video Repainting (video_repainting)#

Request Example: Video Extension (video_extension)#

Response Example#

Response Fields#

Billing#

Query Task#

VACE Unified Video Editing

Capability Overview

Output Specifications

Create Task

Request Headers

Common Parameters

image_reference (Multi-Image Reference to video)

video_repainting (Video Repainting)

video_edit (Video Edit / inpainting)

video_extension (Video Extension)

video_outpainting (Video Outpainting)

Common Input Material Limits

Request Example: Multi-Image Reference to video (image_reference)

Request Example: Video Repainting (video_repainting)

Request Example: Video Extension (video_extension)

Response Example

Response Fields

Billing

Query Task