PixVerse - Image-to-video based on the first frame API reference

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

Activate the service

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

Scope

To ensure successful invocations, the model, endpoint URL, and API key must all belong to the same region. Cross-region invocations will fail.

Select a model: Confirm the region where the model resides.
Select a URL: Choose the corresponding regional endpoint URL. HTTP URLs and DashScope SDK URLs are supported.
Configure an API key: Obtain an API key for the region, and then configure the API key as an environment variable.

The sample code in this topic applies to the China (Beijing) region.

HTTP invocation

Image-to-video tasks take a long time to run—typically 1 to 5 minutes—and use asynchronous invocation. The process consists of two core steps: Create a task → Poll for the result. Follow these steps:

Step 1: Create a task to get a 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.

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

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.

If 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.Valid values:

pixverse/pixverse-c1-it2v
pixverse/pixverse-v6-it2v
pixverse/pixverse-v5.6-it2v

Model selection

For dynamic scenarios such as fights, magic effects, and high-speed motion, use c1.
For general scenarios, use v6. Upgrade directly from v5.6 to v6.

input object (Required)Basic input information, including prompts and media materials.

Properties

prompt string (Optional)The text prompt describes the elements and visual features you want in the generated video.Chinese and English are supported. Each Chinese character or letter counts as one character. Character encoding is UTF-8. Text exceeding the limit is automatically truncated.

pixverse/pixverse-c1-it2v: Up to 5,000 characters.
pixverse/pixverse-v6-it2v: Up to 5,000 characters.
pixverse/pixverse-v5.6-it2v: Up to 2,048 characters.

media array (Required)A list of media materials specifying the images required for video generation.Each array element is a media object containing the type and url fields.

Properties

type string (Required)The type of media material. Valid value:

image_url: The URL of an image.

Material limits: Provide exactly one image.

If you provide multiple images, the system uses the last one. To ensure expected results, always provide only one image.

url string (Required)The URL of the image file. The URL must be publicly accessible over the internet.

HTTP and HTTPS protocols are supported.
Example: https://xxx/xxx.jpg.

Image limits:

Format: JPG, PNG, or WEBP.
Resolution: Width and height cannot exceed 10,000 pixels.
File size: Up to 20 MB.

parameters object (Optional)Video processing parameters, such as resolution, duration, audio generation, and watermarking.

Properties

resolution string (Required)

Resolution affects cost. Before calling the API, review the model pricing.

Specifies the resolution level of the generated video.Valid values: 360P, 540P, 720P, and 1080P.duration integer (Required)

Duration affects cost. Billing is per second. Before calling the API, review the model pricing.

The duration of the generated video, in seconds.

pixverse/pixverse-c1-it2v: An integer from 1 to 15.
pixverse/pixverse-v6-it2v: An integer from 1 to 15.
pixverse/pixverse-v5.6-it2v:
- When resolution is set to any resolution corresponding to 360P, 540P, or 720P: Valid values are 5, 8, and 10.
- When resolution is set to any resolution corresponding to 1080P: Valid values are 5 and 8.

audio boolean (Optional)

Audio setting affects cost. Before calling the API, review the model pricing.

Specifies whether to generate a video with audio. If enabled, the model automatically generates matching background music or sound effects based on the video content.

false: Default. Outputs a silent video.
true: Outputs a video with audio.

watermark boolean (Optional)Specifies whether to add a watermark. The watermark appears in the lower-right corner of the video and displays the fixed text "Generated by AI".

false: Default. Does not add a watermark.
true: Adds a watermark.

shot_type string (Optional)Supported model: pixverse/pixverse-v6-it2v.Specifies the shot type of the generated video—single continuous shot or multiple shots.

single: Default. Generates a single-shot video.
multi: Multi-shot. The system performs intelligent shot segmentation.

Suggestion: The prompt parameter takes precedence over shot_type. For best results, ensure consistency between this parameter and the prompt description.

To consistently output a single-shot video: Set shot_type="single" and describe a single-shot scenario in the prompt.
To consistently output a multi-shot video: Set shot_type="multi" and describe a multi-shot scenario in the prompt.

seed integer (Optional)The random number seed must be an integer in the range [0, 2147483647].If not specified, a random seed is generated. A fixed seed improves reproducibility.Because model generation is probabilistic, the same seed does not guarantee identical results.

Image-to-video
Python SDK
Image-to-video (multi-shot)

Supported models: pixverse/pixverse-c1-it2v, pixverse/pixverse-v6-it2v, and pixverse/pixverse-v5.6-it2v.

# 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-c1-it2v",
    "input": {
        "media": [
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260121/zlpocv/wan-i2v-haigui.webp"
            }
        ],
        "prompt": "The camera slowly moves up from below the sea turtle. The sea turtle swims leisurely, and the details of its belly are clearly visible."
    },
    "parameters": {
        "resolution": "720P",
        "duration": 5,
        "audio": false,
        "watermark": true
    }
}'

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/20260121/zlpocv/wan-i2v-haigui.webp'}]

def sample_async_call():
    # Submit video generation task asynchronously
    rsp = VideoSynthesis.async_call(api_key=api_key,
                                model='pixverse/pixverse-c1-it2v',
                                media=media,
                                prompt='The camera slowly moves up from below the sea turtle. The sea turtle swims leisurely, and the details of its belly are clearly visible.',
                                resolution='720P',
                                duration=5,
                                audio=False,
                                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()

pixverse-c1
pixverse-v6

Supported model: pixverse/pixverse-c1-it2v.Describe the multi-shot scenario in the prompt. Setting the shot_type parameter is not supported.

# 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-c1-it2v",
    "input": {
        "media": [
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260121/zlpocv/wan-i2v-haigui.webp"
            }
        ],
        "prompt": "Shot 1: The camera slowly moves up from below the sea turtle. The sea turtle swims leisurely, and the details of its belly are clearly visible. Shot 2: A long shot of the sea turtle surrounded by seaweed, which is also swaying from side to side."
    },
    "parameters": {
        "resolution": "720P",
        "duration": 8,
        "audio": false,
        "watermark": true
    }
}'

Supported model: pixverse/pixverse-v6-it2v.Describe the multi-shot scenario in the prompt and set shot_type to multi to generate a multi-shot video with audio.

# 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-v6-it2v",
    "input": {
        "media": [
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260121/zlpocv/wan-i2v-haigui.webp"
            }
        ],
        "prompt": "Shot 1: The camera slowly moves up from below the sea turtle. The sea turtle swims leisurely, and the details of its belly are clearly visible. Shot 2: A long shot of the sea turtle surrounded by seaweed, which is also swaying from side to side."
    },
    "parameters": {
        "resolution": "720P",
        "duration": 8,
        "shot_type": "multi",
        "audio": false,
        "watermark": true
    }
}'

Response parameters

output objectTask output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: The task does not exist or its status is unknown.

request_id stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.

Successful response
Error response

Save the task_id to query the task status and result.

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

Step 2: Query the result by task ID

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

Polling suggestion: Video generation takes several minutes. Use a polling mechanism with a reasonable interval—such as 15 seconds—to retrieve the result.
Task status flow: PENDING (queued) → RUNNING (processing) → SUCCEEDED (completed) / FAILED (failed).
task_id validity period: 24 hours. After this period, you can no longer query the result, and the API returns the task status as UNKNOWN.
RPS limit: The default records per second (RPS) for the query API is 20. For higher-frequency polling or event notifications, configure an asynchronous task callback.
More operations: For batch queries and task cancellation, see Manage asynchronous tasks.

Request parameters

Headers

Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

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

outputobjectTask output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe 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 stringThe time when the task was submitted. format is YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringThe time when the task was executed. format is YYYY-MM-DD HH:mm:ss.SSS.end_time stringThe time when the task was completed. format is YYYY-MM-DD HH:mm:ss.SSS.video_urlstringThe video URL. Returned only when task_status is SUCCEEDED.The video format is MP4 (H.264 encoding). The video link does not currently expire, but avoid relying on it for long-term storage. Download the video promptly.orig_prompt stringThe original input prompt, corresponding to the request parameter prompt.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.

usage objectStatistics for the output information. Only successful results are counted.

Properties

duration integerThe total duration of the generated video, used for billing.size stringThe resolution of the generated video.fps integerThe frame rate of the generated video.SR stringThe resolution level of the generated video.audio booleanIndicates whether the generated video contains audio.video_count integerThe number of generated videos. Value is fixed at 1.shot_typestringThe shot type of the generated video.

request_id stringUnique request identifier for tracing and troubleshooting.

Task successful
Task failed
Task query expired

{
    "request_id": "7df19cf7-d76c-4bb8-b4c5-xxxxxx",
    "output": {
        "task_id": "5abf2c85-ea81-4cbf-8918-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-20 11:48:50.499",
        "scheduled_time": "2026-03-20 11:48:50.551",
        "end_time": "2026-03-20 11:49:46.462",
        "orig_prompt": "The camera slowly moves up from below the sea turtle. The sea turtle swims leisurely, and the details of its belly are clearly visible.",
        "video_url": "https://media.pixverseai.cn/xxxx.mp4"
    },
    "usage": {
        "duration": 5,
        "shot_type": "single",
        "size": "992*944",
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "SR": "720"
    }
}

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": "The size is not match xxxxxx"
    }
}

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.

​Activate the service

​Scope

​HTTP invocation

​Step 1: Create a task to get a task ID

Request parameters

Request body

Response parameters

​Step 2: Query the result by task ID

Request parameters

Headers

Path parameters

Response parameters

​Error codes

Activate the service

Scope

HTTP invocation

Step 1: Create a task to get a task ID

Step 2: Query the result by task ID

Error codes