Tradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗
Wan — Recuperar o resultado da troca de caracteres

Verifique o status da troca de rosto
Como fazer uma enquete

Crie uma tarefa para obter um task_id.
Pesquise este endpoint a cada 15 segundos até task_status é SUCCEEDED ou FAILED.
Se tiver sucesso, baixe o vídeo do video_url campo.
Fluxo de status e expiração de URL

Fluxo de status: PENDING → RUNNING → SUCCEEDED ou FAILED.
Expiração de URL: video_url expira após 24 horas. Baixe o vídeo imediatamente.
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:
  /tasks/{task_id}:
    get:
      operationId: getCharacterSwapTaskStatus
      summary: Query task result
      description: Query the status and result of the character swap task.
      parameters:
        - name: task_id
          in: path
          required: true
          description: The ID of the task to query.
          schema:
            type: string
      responses:
        "200":
          description: Task status retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaskStatusResponse"
              examples:
                SUCCEEDED:
                  summary: Task succeeded
                  value:
                    request_id: c1209113-8437-424f-a386-xxxxxx
                    output:
                      task_id: 966cebcd-dedc-4962-af88-xxxxxx
                      task_status: SUCCEEDED
                      submit_time: 2026-03-25 01:36:21.497
                      scheduled_time: 2026-03-25 01:36:30.247
                      end_time: 2026-03-25 01:37:31.910
                      results:
                        video_url: https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxx.mp4?Expires=xxxxxx
                    usage:
                      video_duration: 5.2
                      video_ratio: standard
                FAILED:
                  summary: Task failed
                  value:
                    request_id: c1209113-8437-424f-a386-xxxxxx
                    output:
                      task_id: 966cebcd-dedc-4962-af88-xxxxxx
                      task_status: FAILED
                      code: InvalidParameter
                      message: The specified parameter is not valid.
                      task_metrics:
                        TOTAL: 1
                        SUCCEEDED: 0
                        FAILED: 1
                RUNNING:
                  summary: Task running
                  value:
                    request_id: c1209113-8437-424f-a386-xxxxxx
                    output:
                      task_id: 966cebcd-dedc-4962-af88-xxxxxx
                      task_status: RUNNING
                      task_metrics:
                        TOTAL: 1
                        SUCCEEDED: 0
                        FAILED: 0
        "400":
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DashScopeErrorResponse"
      x-codeSamples:
        - lang: curl
          label: cURL - Query task result
          source: |-
            # Replace {task_id} with the actual task ID from the submit response
            curl -X GET 'https://maas.qwencloudapi.com/api/v1/tasks/{task_id}' \
              -H "Authorization: Bearer $DASHSCOPE_API_KEY"
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.