DocsICP FilingConsole
Documentation
Home Page Alibaba Cloud Model Studio API Reference (Models) Video Generation PixVerse PixVerse - Video Motion Control

PixVerse - Video Motion Control API Reference

Updated at:
Copy as MD
Product
My Favorites

The PixVerse - Video Motion Control model takes a character image and a motion reference video as input, transfers the motion from the video to the target character, and generates a new video where the character reproduces the same movements. Applicable to motion mimicking, choreography replication, character animation generation, and more.

ImportantThis document applies only to the China (Beijing) region. Use an API key from this region.

Activate the service

  1. Go to the Alibaba Cloud Model Studio console, search for PixVerse, find the PixVerse model card, and click Activate Now.
  2. In the pop-up window, confirm the activation and authorization.

Applicable scope

To ensure a successful API call, make sure that the model, Endpoint URL, and API Key all belong to the same region. Cross-region calls will fail.

NoteThe video motion control examples in this topic apply to the China (Beijing) region.

HTTP call

Since video motion control tasks take a relatively long time (typically 1-5 minutes), the API uses asynchronous calls. The entire process consists of two core steps: "Create task -> Poll for result", as follows:

Step 1: Create a task to obtain the task ID

Beijing region: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Replace {WorkspaceId} with your actual workspace ID.

Note

  • 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 Call APIs with Postman or cURL.

Request parameters

Request headers

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.

ImportantIf 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. Fixed value: pixverse/pixverse-motioncontrol.

input object (Required)

The basic input information, including the character image and motion video.

Properties

media array (Required)

The media resource list. Must contain 1 character image of type image_url and 1 motion video of type video_url.

Element properties

type string (Required)

The media type. Valid values:

  • image_url: Character image.
  • video_url: Motion video.

url string (Required)

The URL of the media resource.

  • image_url: The URL of the character image. A single-person subject with clear visuals is recommended.

    • File size: Maximum 20 MB.
    • Resolution: Longest edge up to 10000px.
    • Supported formats: PNG, JPEG, WebP.

  • video_url: The URL of the motion video. A single-person subject with clear movements is recommended.

    • File size: Maximum 100 MB.
    • Duration: Up to 30 seconds.
    • Supported formats: MP4, MOV.

parameters object (Required)

Video generation parameters, such as output video resolution and watermark settings.

Properties

resolution string (Required)

The output video resolution. Valid values: 360P, 540P, 720P. The actual output resolution is adaptively adjusted based on the aspect ratio of the input media.

watermark boolean (Optional)

Whether to add a watermark. The watermark is located at the bottom-right corner of the video with the fixed text "AI-generated".

  • false: Default value. No watermark is added.
  • true: A watermark is added.

Video Motion Control

Submit a character image and a motion video to generate a video where the character imitates the motion.

# Replace {WorkspaceId} with your actual workspace ID.
curl --location 'https://{WorkspaceId}.cn-beijing.maas.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": "pixverse/pixverse-motioncontrol",
    "input": {
        "media": [
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/adsyrp/move_input_image.jpeg"
            },
            {
                "type": "video_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/kaakcn/move_input_video.mp4"
            }
        ]
    },
    "parameters": {
        "resolution": "720P",
        "watermark": true
    }
}'

Python SDK

from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os

# If you have not configured environment variables, replace the following line with your API Key: api_key="sk-xxx"
# Get API Key: https://help.aliyun.com/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

media = [{'type': 'image_url', 'url': 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/adsyrp/move_input_image.jpeg'}, {'type': 'video_url', 'url': 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/kaakcn/move_input_video.mp4'}]

def sample_async_call():
    # Submit video generation task asynchronously
    rsp = VideoSynthesis.async_call(api_key=api_key,
                                model='pixverse/pixverse-motioncontrol',
                                media=media,
                                resolution='720P',
                                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))

    # Query task status
    status = VideoSynthesis.fetch(task=rsp, api_key=api_key)
    if status.status_code == HTTPStatus.OK:
        print(status.output.task_status)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (status.status_code, status.code, status.message))

    # Wait for task to complete
    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()

Step 2: Query result by task ID

Beijing region: GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Note

  • Polling recommendation: Video generation typically takes several minutes. Use a polling mechanism with a reasonable query interval (e.g., 15 seconds) to retrieve results.
  • Task status flow: PENDING (queued) → RUNNING (processing) → SUCCEEDED (success) / FAILED (failure).
  • task_id validity: 24 hours. After expiration, results cannot be queried, and the API will return task status as UNKNOWN.
  • RPS limit: The query API has a default RPS of 20. For higher-frequency queries or event notifications, consider Configure asynchronous task callbacks.
  • More operations: For batch queries, task cancellation, and other operations, see Manage asynchronous tasks.

Request parameters

Request headers

Authorization string (Required)

Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

URL path parameters

task_id string (Required)

The ID of the task.

Query task 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, Replace {WorkspaceId} with your actual workspace ID.

curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

outputobject

The task output information.

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. format is YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

The time when the task was executed. format is YYYY-MM-DD HH:mm:ss.SSS.

end_time string

The time when the task was completed. format is YYYY-MM-DD HH:mm:ss.SSS.

video_urlstring

The video URL. Only returned when task_status is SUCCEEDED.

The video format is MP4 (H.264 encoding). The video link currently has no expiration time, but it is not recommended for long-term storage. Please download promptly.

orig_prompt string

The original input prompt, corresponding to the request parameter prompt.

code string

Error code. Returned only for failed requests. See Error codes.

message string

Detailed error message. Returned only for failed requests. See Error codes.

usage object

Output statistics. Only counts successful results.

Properties

duration integer

Billing duration in seconds. The output video duration matches the input motion reference video duration, and billing is rounded up.

size string

The resolution of the output video.

fps integer

The frame rate of the output video.

SR string

The resolution tier of the output video.

video_count integer

The number of videos. Fixed value: 1.

Task succeeded

{
    "request_id": "43aa3b9f-71c7-98e0-9529-xxxxxx",
    "output": {
        "task_id": "e699df60-145c-464f-ab6a-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-07-14 18:15:04.045",
        "scheduled_time": "2026-07-14 18:15:04.093",
        "end_time": "2026-07-14 18:16:17.412",
        "video_url": "https://media.pixverseai.cn/xxxx.mp4"
    },
    "usage": {
        "duration": 6,
        "size": "1280*704",
        "fps": 24,
        "video_count": 1,
        "SR": "720"
    }
}

Task failed

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

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "Invalid field type or value. Please verify your input data."
    }
}

Task query expired

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

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

Error codes

If the model call fails and returns an error message, see Error codes for resolution.

Previous：PixVerse - Video Lip SyncNext：PixVerse - Video Upscale