Wan — Trocar personagem de vídeo

Enviar tarefa de troca de rosto

A modelo substitui o personagem principal de um vídeo por uma pessoa de uma imagem. Ele preserva a cena, a iluminação, as ações e as expressões para uma integração perfeita.

Modos de serviço

wan2.2-animate-mix oferece dois modos de serviço:

OpenAPI

openapi: 3.1.0
info:
  title: Wan Video Character Swap API
  description: Wan video character swap API. Replaces the main character in a video with a character from an image, preserving the scene, lighting, and tone of the original video. Uses asynchronous task processing.
  version: 1.0.0
servers:
  - url: https://maas.qwencloudapi.com/api/v1
    description: Singapore
security:
  - BearerAuth: []
paths:
  /services/aigc/image2video/video-synthesis:
    post:
      operationId: createCharacterSwap
      summary: Create character swap task
      description: Create a video character swap task.
      parameters:
        - name: X-DashScope-Async
          in: header
          required: true
          description: Must be set to `enable` for asynchronous task submission. Returns a "current user api does not support synchronous calls" error if not included.
          schema:
            type: string
            enum:
              - enable
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CharacterSwapRequest"
      responses:
        "200":
          description: Task submitted 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 (Submit Task)
          source: |-
            curl --location 'https://maas.qwencloudapi.com/api/v1/services/aigc/image2video/video-synthesis' \
            --header 'X-DashScope-Async: enable' \
            --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
            --header 'Content-Type: application/json' \
            --data '{
              "model": "wan2.2-animate-mix",
              "input": {
                "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg",
                "video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4",
                "watermark": true
              },
              "parameters": {
                "mode": "wan-std"
              }
            }'
        - 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.2-animate-mix',
                image_url='https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg',
                video_url='https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4',
                watermark=True,
                mode='wan-std')
              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.2-animate-mix',
                image_url='https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg',
                video_url='https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4',
                watermark=True,
                mode='wan-std')
              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 WanCharacterSwap {
              static {
                Constants.baseHttpApiUrl = "https://maas.qwencloudapi.com/api/v1";
              }
              public static void main(String[] args) {
                try {
                  VideoSynthesis vs = new VideoSynthesis();
                  Map<String, Object> parameters = new HashMap<>();
                  parameters.put("mode", "wan-std");
                  VideoSynthesisParam param = VideoSynthesisParam.builder()
                    .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                    .model("wan2.2-animate-mix")
                    .parameters(parameters)
                    .imageUrl("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg")
                    .videoUrl("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4")
                    .watermark(true)
                    .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 WanCharacterSwap {
              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();
                  Map<String, Object> parameters = new HashMap<>();
                  parameters.put("mode", "wan-std");
                  VideoSynthesisParam param = VideoSynthesisParam.builder()
                    .apiKey(apiKey)
                    .model("wan2.2-animate-mix")
                    .parameters(parameters)
                    .imageUrl("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg")
                    .videoUrl("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4")
                    .watermark(true)
                    .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:
    CharacterSwapRequest:
      type: object
      required:
        - model
        - input
        - parameters
      properties:
        model:
          type: string
          description: The model name.
          enum:
            - wan2.2-animate-mix
          example: wan2.2-animate-mix
        input:
          type: object
          required:
            - image_url
            - video_url
          description: Basic input information.
          properties:
            image_url:
              type: string
              format: uri
              description: |-
                A publicly accessible HTTP or HTTPS link to the input character image. The URL cannot contain non-ASCII characters; encode the URL if it does. The image must show a single front-facing person with an unobstructed face, occupying a moderate portion of the frame.

                - **Format**: JPG, JPEG, PNG, BMP, or WEBP.
                - **Resolution**: Width and height must be within [200, 4096] pixels. Aspect ratio must be between 1:3 and 3:1.
                - **File size**: Up to 5 MB.
              example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg
            video_url:
              type: string
              format: uri
              description: |-
                A publicly accessible HTTP or HTTPS link to the input reference video. The URL cannot contain non-ASCII characters; encode the URL if it does. The video must show a single front-facing person with an unobstructed face, occupying a moderate portion of the frame. Increasing the resolution and frame rate of the reference video improves the quality of the generated video.

                - **Format**: MP4, AVI, or MOV.
                - **Resolution**: Width and height must be within [200, 2048] pixels. Aspect ratio must be between 1:3 and 3:1.
                - **File size**: Up to 200 MB.
                - **Duration**: 2 to 30 seconds.
              example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4
            watermark:
              type: boolean
              description: Whether to add a "generated by qwen.ai" watermark in the lower-right corner of the video.
              default: false
        parameters:
          type: object
          required:
            - mode
          description: Generation parameters.
          properties:
            check_image:
              type: boolean
              description: "Whether to perform image detection on the input image. `true` (default): the API detects the input image. `false`: image detection is skipped."
              default: true
            mode:
              type: string
              description: |-
                The model service mode.

                - `wan-std`: Standard mode. Generates results faster and is cost-effective. Suitable for quick previews and basic animation scenarios.
                - `wan-pro`: Professional mode. Provides smoother animations and better effects, but processing time and costs increase accordingly.
              enum:
                - wan-std
                - wan-pro
              example: wan-std
    AsyncTaskSubmitResponse:
      type: object
      description: Response from an asynchronous task submission.
      properties:
        request_id:
          type: string
          description: Unique request identifier for tracing and troubleshooting.
          example: 4909100c-7b5a-9f92-bfe5-xxxxxx
        output:
          type: object
          properties:
            task_id:
              type: string
              description: Task ID for polling status. Use with `GET /tasks/{task_id}`. Valid for 24 hours.
              example: 0385dc79-5ff8-4d82-bcb6-xxxxxx
            task_status:
              type: string
              description: Initial task status, typically `PENDING`.
              enum:
                - PENDING
                - RUNNING
                - SUCCEEDED
                - FAILED
                - CANCELED
                - UNKNOWN
    TaskStatusResponse:
      type: object
      description: Response from polling the task status.
      properties:
        request_id:
          type: string
          description: Unique request identifier for tracing and troubleshooting.
          example: a67f8716-18ef-447c-a286-xxxxxx
        output:
          type: object
          description: Task output information.
          properties:
            task_id:
              type: string
              description: The ID of the task. Valid for 24 hours.
              example: 0385dc79-5ff8-4d82-bcb6-xxxxxx
            task_status:
              type: string
              description: The status of the task.
              enum:
                - PENDING
                - RUNNING
                - SUCCEEDED
                - FAILED
                - CANCELED
                - UNKNOWN
            submit_time:
              type: string
              description: "The time when the task was submitted. UTC+8. Format: `YYYY-MM-DD HH:mm:ss.SSS`."
              example: 2025-09-18 15:32:00.105
            scheduled_time:
              type: string
              description: "The time when the task started running. UTC+8. Format: `YYYY-MM-DD HH:mm:ss.SSS`."
              example: 2025-09-18 15:32:15.066
            end_time:
              type: string
              description: "The time when the task completed. UTC+8. Format: `YYYY-MM-DD HH:mm:ss.SSS`."
              example: 2025-09-18 15:34:41.898
            results:
              type: object
              description: Task results. Only present when `task_status` is `SUCCEEDED`.
              properties:
                video_url:
                  type: string
                  format: uri
                  description: The URL of the generated video in MP4 format (H.264 encoding). Valid for 24 hours. Download promptly.
                  example: http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxx.mp4?Expires=xxxxxx
            code:
              type: string
              description: Error code. Returned only when the task fails.
            message:
              type: string
              description: Detailed error message. Returned only when the task fails.
        usage:
          type: object
          description: Usage statistics. Returned only for successful results.
          properties:
            video_duration:
              type: number
              description: Duration of the generated video, in seconds.
              example: 5.2
            video_ratio:
              type: string
              description: The model service mode used. `standard` corresponds to `wan-std`; `pro` corresponds to `wan-pro`.
              enum:
                - standard
                - pro
    DashScopeErrorResponse:
      type: object
      description: DashScope API error response.
      properties:
        request_id:
          type: string
          description: Unique request identifier.
          example: 7438d53d-6eb8-4596-8835-xxxxxx
        code:
          type: string
          description: Error code (e.g., `InvalidApiKey`, `Throttling`, `InvalidParameter`).
          example: InvalidApiKey
        message:
          type: string
          description: Human-readable error message.
          example: No API-key provided.