> ## Documentation Index
> Fetch the complete documentation index at: https://mulerouter.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Wan 2.1 Video Ace Plus Generation

> Edit videos using the wan2.1-vace-plus model with multi-modal inputs and various editing functions.

<Note>
  This API supports Alibaba Tongyi Wanxiang (Wan2) video editing models. Please refer to Alibaba Cloud's [official documentation](https://www.alibabacloud.com/help/en/model-studio/text-to-video-api-reference) for more details.
</Note>

## Overview

Edit videos using the wan2.1-vace-plus model with multi-modal inputs. This model supports multiple video editing functions.

## Supported Functions

| Function            | Description                               |
| ------------------- | ----------------------------------------- |
| `image_reference`   | Generate videos from 1-3 reference images |
| `video_repainting`  | Repaint/restyle an existing video         |
| `video_edit`        | Local (masked) editing of video regions   |
| `video_extension`   | Extend video with new content             |
| `video_outpainting` | Expand video canvas in any direction      |

## Example Requests

### Multi-image Reference

```json theme={null}
{
  "function": "image_reference",
  "prompt": "A cat playing in the garden",
  "ref_images_url": [
    "https://example.com/cat.jpg",
    "https://example.com/garden.jpg"
  ],
  "obj_or_bg": ["obj", "bg"],
  "size": "1280*720",
  "duration": 5
}
```

### Video Repainting

```json theme={null}
{
  "function": "video_repainting",
  "prompt": "Transform the scene into a cyberpunk style",
  "video_url": "https://example.com/source.mp4",
  "control_condition": "depth",
  "strength": 0.8
}
```

### Local Editing

```json theme={null}
{
  "function": "video_edit",
  "prompt": "Replace the background with a beach sunset",
  "video_url": "https://example.com/source.mp4",
  "mask_image_url": "https://example.com/mask.png",
  "mask_type": "tracking"
}
```

### Video Extension

```json theme={null}
{
  "function": "video_extension",
  "prompt": "Continue the scene with the character walking forward",
  "first_clip_url": "https://example.com/clip.mp4",
  "duration": 5
}
```

### Video Outpainting

```json theme={null}
{
  "function": "video_outpainting",
  "prompt": "Expand to show more of the surrounding environment",
  "video_url": "https://example.com/source.mp4",
  "top_scale": 1.5,
  "left_scale": 1.3,
  "right_scale": 1.3
}
```

## Function Details

### image\_reference

* **Required**: `ref_images_url` (1-3 images)
* **Required when multiple images**: `obj_or_bg` array
* **Output**: 720P resolution, 5s duration

### video\_repainting

* **Required**: `video_url`, `control_condition`
* **Control conditions**: posebodyface, posebody, depth, scribble
* **Strength**: 0.0-1.0 (default 1.0)

### video\_edit

* **Required**: `video_url`
* **Mask options**: `mask_image_url` or `mask_video_url`
* **Mask types**: tracking (follows motion), fixed (static)

### video\_extension

* **Required**: `prompt`
* **Optional**: `first_frame_url`, `last_frame_url`, `first_clip_url`, `last_clip_url`
* **With guidance video**: requires `control_condition`

### video\_outpainting

* **Required**: `video_url`
* **Scale options**: `top_scale`, `bottom_scale`, `left_scale`, `right_scale` (1.0-2.0)

## Video Requirements

| Property         | Requirement |
| ---------------- | ----------- |
| **Format**       | MP4         |
| **Max size**     | 50MB        |
| **Min FPS**      | 16          |
| **Max duration** | 5s          |


## OpenAPI

````yaml api-reference/endpoint/alibaba/wan2.1-vace-plus/wan2.1-vace-plus.yaml POST /vendors/alibaba/v1/wan2.1-vace-plus/generation
openapi: 3.1.0
info:
  title: Wan2.1-vace-plus API
  description: Wan2.1 VACE Plus Video Editing Model API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.mulerouter.ai/
security:
  - bearerAuth: []
paths:
  /vendors/alibaba/v1/wan2.1-vace-plus/generation:
    post:
      summary: Create Generation Task
      description: >-
        Edit videos using the wan2.1-vace-plus model with multi-modal inputs and
        various editing functions.
      operationId: wan21_vace_plus_generation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoEditRequest'
        required: true
      responses:
        '202':
          description: Accepted - Task created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskCreatedResponse'
components:
  schemas:
    VideoEditRequest:
      description: >-
        wan2.1-vace-plus video editing entry point. Select a function and supply
        the parameters supported by that function.
      oneOf:
        - $ref: '#/components/schemas/WanVideoEditImageReferenceRequest'
        - $ref: '#/components/schemas/WanVideoEditVideoRepaintingRequest'
        - $ref: '#/components/schemas/WanVideoEditLocalEditingRequest'
        - $ref: '#/components/schemas/WanVideoEditExtensionRequest'
        - $ref: '#/components/schemas/WanVideoEditOutpaintingRequest'
      discriminator:
        propertyName: function
        mapping:
          image_reference:
            $ref: '#/components/schemas/WanVideoEditImageReferenceRequest'
          video_repainting:
            $ref: '#/components/schemas/WanVideoEditVideoRepaintingRequest'
          video_edit:
            $ref: '#/components/schemas/WanVideoEditLocalEditingRequest'
          video_extension:
            $ref: '#/components/schemas/WanVideoEditExtensionRequest'
          video_outpainting:
            $ref: '#/components/schemas/WanVideoEditOutpaintingRequest'
    TaskCreatedResponse:
      type: object
      additionalProperties: true
      properties:
        task_info:
          $ref: '#/components/schemas/TaskInfoCreated'
    WanVideoEditImageReferenceRequest:
      title: Multi-image Reference
      type: object
      additionalProperties: false
      properties:
        model:
          type: string
          description: Model name (only wan2.1-vace-plus is supported)
          enum:
            - wan2.1-vace-plus
        function:
          type: string
          const: image_reference
          enum:
            - image_reference
          description: Multi-image reference feature selector.
        prompt:
          type: string
          description: Text description for the synthesized video (max 800 characters).
          maxLength: 800
        negative_prompt:
          anyOf:
            - type: string
            - type: 'null'
          description: Negative prompt (max 500 characters).
          maxLength: 500
        ref_images_url:
          type: array
          minItems: 1
          maxItems: 3
          description: >-
            Public URLs for 1-3 reference images (JPG/JPEG/PNG/BMP/TIFF/WEBP,
            360-2000px, ≤10MB, ASCII URL). Required.
          items:
            type: string
            format: uri
        obj_or_bg:
          type: array
          description: >-
            Matches ref_images_url to label each image as entity ("obj") or
            background ("bg"). Required when multiple images are supplied;
            defaults to ["obj"] for a single image.
          items:
            type: string
            enum:
              - obj
              - bg
        size:
          description: >-
            Output resolution ("width\*height"). Supported: 1280\*720 (default),
            720\*1280, 960\*960, 832\*1088, 1088\*832.
          enum:
            - 1280*720
            - 720*1280
            - 960*960
            - 832*1088
            - 1088*832
          default: 1280*720
        duration:
          anyOf:
            - type: integer
              enum:
                - 5
            - type: 'null'
          description: Output duration (seconds). Fixed at 5.
        prompt_extend:
          type: boolean
          description: Enable intelligent prompt rewriting (default true).
          default: true
        seed:
          type: integer
          description: Random seed [0, 2147483647].
          minimum: 0
          maximum: 2147483647
        safety_filter:
          anyOf:
            - type: boolean
            - type: 'null'
          description: >-
            Enable content safety filter. Defaults to true. Set to false to
            disable content safety inspection.
          default: true
      required:
        - model
        - function
        - prompt
        - ref_images_url
    WanVideoEditVideoRepaintingRequest:
      title: Video Repainting
      type: object
      additionalProperties: false
      properties:
        model:
          type: string
          description: Model name (only wan2.1-vace-plus is supported)
          enum:
            - wan2.1-vace-plus
        function:
          type: string
          const: video_repainting
          enum:
            - video_repainting
          description: Video repainting feature selector.
        prompt:
          type: string
          description: Text description for the repainted video (max 800 characters).
          maxLength: 800
        negative_prompt:
          anyOf:
            - type: string
            - type: 'null'
          description: Negative prompt (max 500 characters).
          maxLength: 500
        video_url:
          type: string
          format: uri
          description: >-
            Public MP4 URL for the source video (≤50MB, ≥16 FPS, ≤5s, ASCII
            URL).
        ref_images_url:
          type: array
          maxItems: 1
          description: >-
            Optional reference image URL (single entity image, same constraints
            as image_reference).
          items:
            type: string
            format: uri
        control_condition:
          type: string
          description: >-
            Feature extraction method: posebodyface, posebody, depth, or
            scribble.
          enum:
            - posebodyface
            - posebody
            - depth
            - scribble
        strength:
          anyOf:
            - type: number
              minimum: 0
              maximum: 1
            - type: 'null'
          description: >-
            Control strength applied to the extracted motion (0.0-1.0, default
            1.0).
        prompt_extend:
          type: boolean
          description: >-
            Enable prompt rewriting (default false, recommended off for
            consistency).
          default: false
        seed:
          type: integer
          description: Random seed [0, 2147483647].
          minimum: 0
          maximum: 2147483647
      required:
        - model
        - function
        - prompt
        - video_url
        - control_condition
    WanVideoEditLocalEditingRequest:
      title: Local Editing
      type: object
      additionalProperties: false
      properties:
        model:
          type: string
          description: Model name (only wan2.1-vace-plus is supported)
          enum:
            - wan2.1-vace-plus
        function:
          type: string
          const: video_edit
          enum:
            - video_edit
          description: Local (masked) editing feature selector.
        prompt:
          type: string
          description: Text description for the edited region (max 800 characters).
          maxLength: 800
        negative_prompt:
          anyOf:
            - type: string
            - type: 'null'
          description: Negative prompt (max 500 characters).
          maxLength: 500
        video_url:
          type: string
          format: uri
          description: >-
            Public MP4 URL for the source video (≤50MB, ≥16 FPS, ≤5s, ASCII
            URL).
        ref_images_url:
          type: array
          maxItems: 1
          description: >-
            Optional reference image URL for replacement (single
            entity/background).
          items:
            type: string
            format: uri
        mask_image_url:
          anyOf:
            - type: string
              format: uri
            - type: 'null'
          description: >-
            Public mask image URL (white = edit, black = keep). Resolution must
            match video_url.
        mask_frame_id:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          description: 1-based frame index where mask_image_url applies. Defaults to 1.
        mask_video_url:
          anyOf:
            - type: string
              format: uri
            - type: 'null'
          description: >-
            Public mask video URL (MP4, same specs as video_url). Provide
            mask_image_url or mask_video_url.
        control_condition:
          anyOf:
            - type: string
              enum:
                - posebodyface
                - depth
            - type: 'null'
          description: Optional feature extraction method ("posebodyface" or "depth").
        mask_type:
          anyOf:
            - type: string
              enum:
                - tracking
                - fixed
            - type: 'null'
          description: >-
            Mask behavior (tracking = follows motion, fixed = static). Applies
            when mask_image_url is provided.
        expand_ratio:
          anyOf:
            - type: number
              minimum: 0
              maximum: 1
            - type: 'null'
          description: Expansion ratio for tracking masks (0.0-1.0, default 0.05).
        expand_mode:
          anyOf:
            - type: string
              enum:
                - hull
                - bbox
                - original
            - type: 'null'
          description: Shape of the tracking mask expansion.
        size:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Output resolution ("width\*height"). Supported: 1280\*720 (default),
            720\*1280, 960\*960, 832\*1088, 1088\*832.
          enum:
            - 1280*720
            - 720*1280
            - 960*960
            - 832*1088
            - 1088*832
          default: 1280*720
        duration:
          anyOf:
            - type: integer
              enum:
                - 5
            - type: 'null'
          description: Output duration (seconds). Fixed at 5.
        prompt_extend:
          type: boolean
          description: Enable prompt rewriting (default false).
          default: false
        seed:
          type: integer
          description: Random seed [0, 2147483647].
          minimum: 0
          maximum: 2147483647
      required:
        - model
        - function
        - prompt
        - video_url
    WanVideoEditExtensionRequest:
      title: Video Extension
      type: object
      additionalProperties: false
      properties:
        model:
          type: string
          description: Model name (only wan2.1-vace-plus is supported)
          enum:
            - wan2.1-vace-plus
        function:
          type: string
          const: video_extension
          enum:
            - video_extension
          description: Video extension feature selector.
        prompt:
          type: string
          description: Text description for the extended video (max 800 characters).
          maxLength: 800
        negative_prompt:
          anyOf:
            - type: string
            - type: 'null'
          description: Negative prompt (max 500 characters).
          maxLength: 500
        first_frame_url:
          anyOf:
            - type: string
              format: uri
            - type: 'null'
          description: Public URL of the starting frame image (360-2000px, ≤10MB).
        last_frame_url:
          anyOf:
            - type: string
              format: uri
            - type: 'null'
          description: >-
            Public URL of the ending frame image (same constraints as
            first_frame_url).
        first_clip_url:
          anyOf:
            - type: string
              format: uri
            - type: 'null'
          description: Public MP4 opening clip (≤3s, ≥16 FPS, ≤50MB).
        last_clip_url:
          anyOf:
            - type: string
              format: uri
            - type: 'null'
          description: Public MP4 ending clip (≤3s, ≥16 FPS, ≤50MB).
        video_url:
          anyOf:
            - type: string
              format: uri
            - type: 'null'
          description: >-
            Optional guidance video (MP4, ≤5s, ≥16 FPS, ≤50MB). Requires
            control_condition.
        control_condition:
          anyOf:
            - type: string
              enum:
                - posebodyface
                - depth
            - type: 'null'
          description: >-
            Feature extraction for guidance video ("posebodyface" or "depth").
            Required when video_url is provided.
        duration:
          anyOf:
            - type: integer
              enum:
                - 5
            - type: 'null'
          description: Output duration (seconds). Fixed at 5.
        prompt_extend:
          type: boolean
          description: Enable prompt rewriting (default false).
          default: false
        seed:
          type: integer
          description: Random seed [0, 2147483647].
          minimum: 0
          maximum: 2147483647
      required:
        - model
        - function
        - prompt
    WanVideoEditOutpaintingRequest:
      title: Video Outpainting
      type: object
      additionalProperties: false
      properties:
        model:
          type: string
          description: Model name (only wan2.1-vace-plus is supported)
          enum:
            - wan2.1-vace-plus
        function:
          type: string
          const: video_outpainting
          enum:
            - video_outpainting
          description: Video outpainting feature selector.
        prompt:
          type: string
          description: Text description for the outpainted areas (max 800 characters).
          maxLength: 800
        negative_prompt:
          anyOf:
            - type: string
            - type: 'null'
          description: Negative prompt (max 500 characters).
          maxLength: 500
        video_url:
          type: string
          format: uri
          description: >-
            Public MP4 URL for the source video (≤50MB, ≥16 FPS, ≤5s, ASCII
            URL).
        top_scale:
          anyOf:
            - type: number
              minimum: 1
              maximum: 2
            - type: 'null'
          description: Upward scaling ratio [1.0, 2.0]. Default 1.0.
        bottom_scale:
          anyOf:
            - type: number
              minimum: 1
              maximum: 2
            - type: 'null'
          description: Downward scaling ratio [1.0, 2.0]. Default 1.0.
        left_scale:
          anyOf:
            - type: number
              minimum: 1
              maximum: 2
            - type: 'null'
          description: Leftward scaling ratio [1.0, 2.0]. Default 1.0.
        right_scale:
          anyOf:
            - type: number
              minimum: 1
              maximum: 2
            - type: 'null'
          description: Rightward scaling ratio [1.0, 2.0]. Default 1.0.
        duration:
          anyOf:
            - type: integer
              enum:
                - 5
            - type: 'null'
          description: Output duration (seconds). Fixed at 5.
        prompt_extend:
          type: boolean
          description: Enable prompt rewriting (default false).
          default: false
        seed:
          type: integer
          description: Random seed [0, 2147483647].
          minimum: 0
          maximum: 2147483647
      required:
        - model
        - function
        - prompt
        - video_url
    TaskInfoCreated:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          description: UUID of the task
          format: uuid
        status:
          type: string
          description: Task status (pending when created)
          enum:
            - pending
        created_at:
          type: string
          description: Task creation timestamp (ISO 8601)
          format: date-time
        updated_at:
          type: string
          description: Task last update timestamp (ISO 8601)
          format: date-time
      required:
        - id
        - status
        - created_at
        - updated_at
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````