DocsICP FilingConsole
Documentation
Home Page Alibaba Cloud Model Studio API Reference (Models) Video Generation PixVerse PixVerse: Image-to-video from first and last frames

PixVerse: Image-to-video from first and last frames API reference

Updated at:
Copy as MD
Product
My Favorites

The PixVerse model for first and last frames generates a smooth video transition based on a first frame image, a last frame image, and a text prompt.

Important

This 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.

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.

Note

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.

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

Generate a video from first and last frames

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
    }
}'
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.

Important

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)

Important

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)

Important

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)

Important

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.

seed integer (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.

Response parameters

Successful 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"
}

Error response

Task creation failed. See Error codes.

{
    "code": "InvalidApiKey",
    "message": "Invalid API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

output object

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.

request_id string

Unique request identifier for tracing and troubleshooting.

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.

Step 2: Query the result by task ID

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

Note

  • 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

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"
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.

Response parameters

Task successful

{
    "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"
    }
}

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

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"
    }
}

output object

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_url string

The 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 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

The statistics of the output information. Only successful results are counted.

Properties

duration integer

The total duration of the generated video, which is used for billing.

size string

The resolution of the generated video.

fps integer

The frame rate of the generated video.

SR string

The resolution tier of the generated video.

audio boolean

Indicates whether the generated video contains sound.

video_count integer

The number of generated videos. The value is fixed at 1.

request_id string

Unique request identifier for tracing and troubleshooting.

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.

Previous：PixVerse - Image-to-video based on the first frameNext：PixVerse - Reference-to-video