PixVerse: Image-to-video from first and last frames 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, make sure that the model, Endpoint URL, and API key all belong to the same region. Invocations across different regions will fail.

Select a model: Confirm the region to which the model belongs.
Select a URL: Select the corresponding regional Endpoint URL. Both HTTP URLs and DashScope SDK URLs are supported.
Configure an API key: Select a region and obtain an API key. Then, configure the API key as an environment variable.

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

HTTP invocation

Generating a video from the first and last frames is a time-consuming task that usually takes 1 to 5 minutes. Therefore, the API uses asynchronous invocation. The process involves two core steps: Create a task -> Poll for the result, as described below:

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

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.

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-kf2v
pixverse/pixverse-v6-kf2v
pixverse/pixverse-v5.6-kf2v

Model selection

For dynamic scenarios such as fights, magic effects, and high-speed motion, use c1.
For general scenarios, use v6. If you are using v5.6, we recommend that you upgrade to v6.

input object (Required)The basic input information, which includes the first frame image, last frame image, and prompt.

Properties

prompt string (Required)The text prompt. It describes the transition from the first frame to the last frame.Both Chinese and English are supported. Each Chinese character or letter is counted as one character. The character encoding is UTF-8. Any excess characters are automatically truncated.

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

media array (Required)The list of media resources, which includes the first and last frame images.Each element in the array is a media object that contains the type and url fields.

Properties

type string (Required)The media type.

first_frame: The first frame image.
last_frame: The last frame image.

Image limits:

First frame image: Exactly one image.
Last frame image: Exactly one image.

url string (Required)The publicly accessible URL of the image.

The HTTP or HTTPS protocol is supported.
For example, https://xxx/xxx.png.

Image limits:

Format: JPG, PNG, or WEBP.
Resolution: The width and height must not exceed 10,000 pixels.
File size: Up to 20 MB.

parameters object (Required)The video generation parameters, such as the video resolution, duration, and whether to generate audio.

Properties

resolution string (Required)

The resolution directly affects the cost. Before you make a call, confirm the model price.

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

The duration directly affects the cost. Before you make a call, confirm the model price.

The duration of the generated video in seconds.

pixverse/pixverse-c1-kf2v: An integer from 1 to 15.
pixverse/pixverse-v6-kf2v: An integer from 1 to 15.
pixverse/pixverse-v5.6-kf2v:
- If the resolution is 360P, 540P, or 720P, the value can be 5, 8, or 10.
- If the resolution is 1080P, the value can be 5 or 8.

audio boolean (Optional)

The audio setting directly affects the cost. Before you make a call, confirm the model price.

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

false: The default value. A silent video is generated.
true: A video with sound is generated.

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

false: The default value. No watermark is added.
true: A watermark is added.

seedinteger(Optional)The random number seed. The value must be in the range [0, 2147483647].If this parameter is not specified, the system automatically generates a random seed. To improve the reproducibility of the generation results, you can set a fixed seed value.Note that because model generation is probabilistic, using the same seed does not guarantee that the results are identical every time.

Generate a video from first and last frames
Python SDK

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

# 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-kf2v",
    "input": {
        "media": [
            {
                "type": "first_frame",
                "url": "https://wanx.alicdn.com/material/20250318/first_frame.png"
            },
            {
                "type": "last_frame",
                "url": "https://wanx.alicdn.com/material/20250318/last_frame.png"
            }
        ],
        "prompt": "A kitten jumps down from the windowsill, lands lightly on the sofa, and then looks around curiously."
    },
    "parameters": {
        "resolution": "720P",
        "duration": 5,
        "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': 'first_frame', 'url': 'https://wanx.alicdn.com/material/20250318/first_frame.png'}, {'type': 'last_frame', 'url': 'https://wanx.alicdn.com/material/20250318/last_frame.png'}]

def sample_async_call():
    # Submit video generation task asynchronously
    rsp = VideoSynthesis.async_call(api_key=api_key,
                                model='pixverse/pixverse-c1-kf2v',
                                media=media,
                                prompt='A kitten jumps down from the windowsill, lands lightly on the sofa, and then looks around curiously.',
                                resolution='720P',
                                duration=5,
                                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()

Response parameters

output objectThe task 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 recommendation: Video generation takes several minutes. We recommend that you use a polling mechanism with a reasonable query interval, such as 15 seconds, to retrieve the result.
Task status flow: PENDING -> RUNNING -> SUCCEEDED / FAILED.
task_id validity: 24 hours. After this period, you cannot query the result. The API returns the task status as UNKNOWN.
RPS limit: The query API has a default limit of 20 records per second (RPS). For higher-frequency queries or event notifications, you can configure an asynchronous task callback.
More operations: For information about operations such as batch queries and canceling tasks, see Manage asynchronous tasks.

Request parameters

Request 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 the 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

outputobjectThe task 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. This parameter is returned only when the task_status is SUCCEEDED.The video format is MP4 with H.264 encoding. The video link does not expire. However, we recommend that you do not use 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 objectThe statistics of the output information. Only successful results are counted.

Properties

duration integerThe total duration of the generated video, which is used for billing.size stringThe resolution of the generated video.fps integerThe frame rate of the generated video.SR stringThe resolution tier of the generated video.audio booleanIndicates whether the generated video contains sound.video_count integerThe number of generated videos. The value is fixed at 1.

request_id stringUnique request identifier for tracing and troubleshooting.

Task successful
Task failed
Task query expired

{
    "request_id": "40799260-689c-4c44-9d7c-xxxxxx",
    "output": {
        "task_id": "408b6c3b-27c9-43dd-b928-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-20 13:47:42.916",
        "scheduled_time": "2026-03-20 13:47:42.949",
        "end_time": "2026-03-20 13:48:41.896",
        "orig_prompt": "A kitten jumps down from the windowsill, lands lightly on the sofa, and then looks around curiously.",
        "video_url": "https://media.pixverseai.cn/xxx.mp4"
    },
    "usage": {
        "duration": 5,
        "size": "1280*960",
        "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.

FAQ

Q: Does the order of the first and last frames in the media array matter?

A: The media array must contain two objects, with their type fields set to first_frame (first frame) and last_frame (last frame), respectively. The order does not affect the result because the system automatically detects them based on the type field.

Q: Do the first and last frame images need to have the same resolution?

A: No, they do not. The first and last frames can have different resolutions. The system handles this automatically. The aspect ratio of the output video is approximately the same as that of the first frame. The resolution is automatically adjusted to a similar total pixel count based on the selected resolution setting, such as 720P.

​Activate the service

​Scope

​HTTP invocation

​Step 1: Create a task and get the task ID

Request parameters

Request headers

Request body

Response parameters

​Step 2: Query the result by task ID

Request parameters

Request headers

Path parameters

Response parameters

​Error codes

​FAQ

​Q: Does the order of the first and last frames in the media array matter?

​Q: Do the first and last frame images need to have the same resolution?

Activate the service

Scope

HTTP invocation

Step 1: Create a task and get the task ID

Step 2: Query the result by task ID

Error codes

FAQ

Q: Does the order of the first and last frames in the media array matter?

Q: Do the first and last frame images need to have the same resolution?