Vidu - Image-to-video - First and last 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 Vidu, find the Vidu model card, and click Activate Now. In the pop-up window, confirm the activation and authorization.

Scope

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

Select a model: Confirm the region where the model is located.
Select a URL: Select the corresponding regional Endpoint URL. HTTP URLs are supported.
Configure an API key: Select a region and obtain an API key. Then, configure the API key as an environment variable (to be unpublished and merged into API key configuration).

HTTP calls

Because first and last frame video generation tasks take a long time (typically 1 to 5 minutes), the API uses asynchronous invocation. The entire process involves two core steps: Create a task -> Poll for the result. The procedure is as follows:

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

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. For more information about available models, see the Model List.Static field: vidu/viduq3-turbo_start-end2video.input object (Required)Basic input information, including the first frame, last frame image, and prompt.

Properties

prompt string (Required)The text prompt. It describes the transition process from the first frame to the last frame.Both Chinese and English are supported. Each Chinese character or letter counts as one character. The maximum length is 5,000 characters. Any excess characters are automatically truncated.Example: A kitten jumps down from the windowsill, lands lightly on the sofa, and then looks around curiously.For more information about how to write prompts, see Vidu Video Generation Prompt Guide.media array (Required)A list of media resources, including the first and last frame images.Each element in the array is a media object that contains type and url fields.

Properties

type string (Required)The media type. The static field is:

image: Image URL.

Material limits:

There must be exactly 2 images.
The first image in the array represents the first frame, and the second image represents the last frame.

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

HTTP or HTTPS protocols are supported.
Example: https://xxx/xxx.png.

Image limits:

Format: JPG, PNG, WEBP.
Aspect ratio: 1:4 to 4:1.
File size: No more than 50 MB.
Resolution: The resolutions of the first and last frames must be similar. The ratio of their total pixel values (width × height) must be between 0.8 and 1.25.

parameters object (Required)Video generation parameters, such as video resolution and duration.

Properties

resolution string (Required)

The resolution directly affects the cost. Before making a call, confirm the model pricing.

The resolution of the generated video. The optional values are:

540P
720P: Default value.
1080P

duration integer (Required)

The duration directly affects the cost. Billing is by the second. A longer duration results in a higher cost. Before making a call, confirm the model pricing.

The duration of the generated video, in seconds.

vidu/viduq3-pro_start-end2video, vidu/viduq3-turbo_start-end2video: An integer from 1 to 16. The default value is 5.
vidu/viduq2-pro_start-end2video, vidu/viduq2-turbo_start-end2video: An integer from 1 to 10. The default value is 5.

audio boolean (Optional)Supported models: vidu/viduq3-pro_start-end2video, vidu/viduq3-turbo_start-end2video.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: Default value. Outputs a silent video.
true: Outputs a video with sound.

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

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

seedinteger(Optional)A random number seed. The value can be an integer from 0 to 2147483647.If this parameter is not specified, the system automatically generates a random seed. To improve the reproducibility of the generated results, set a fixed seed value.Note that because model generation is probabilistic, using the same seed does not guarantee that the results will be identical every time.Example: 12345.

First and last frame video generation
Python SDK

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": "vidu/viduq3-turbo_start-end2video",
    "input": {
        "media": [
            {
                "type": "image",
                "url": "https://wanx.alicdn.com/material/20250318/first_frame.png"
            },
            {
                "type": "image",
                "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": "540P",
        "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': 'image', 'url': 'https://wanx.alicdn.com/material/20250318/first_frame.png'}, {'type': 'image', '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='vidu/viduq3-turbo_start-end2video',
                                media=media,
                                prompt='A kitten jumps down from the windowsill, lands lightly on the sofa, and then looks around curiously.',
                                resolution='540P',
                                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 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 recommendation: Video generation takes several minutes. We recommend that you use a polling mechanism and set a reasonable query interval, such as 15 seconds, to obtain the result.
Task status flow: PENDING (In queue) -> RUNNING (Processing) -> SUCCEEDED (Successful) / FAILED (Failed).
task_id validity: 24 hours. After this period, you cannot 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 queries or event notifications, you can configure an asynchronous task callback.
More operations: For operations such as batch queries and task cancellation, 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

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. This parameter is returned only when task_status is SUCCEEDED.The video is in MP4 format (H.264 encoding). The video link is valid for 24 hours. We recommend that you download it 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. This parameter is counted only for successful results.

Properties

duration integerThe total billable video duration in seconds. Example: 5.output_video_durationintegerThe duration of the output video in seconds. Example: 5.size stringThe resolution of the output video. Example: 828*624.fps integerThe frame rate of the output video. Example: 24.SR stringThe resolution tier of the output video. Example: 540.audio booleanIndicates whether the output video has sound. Example: false.video_count integerThe number of output videos. This is a static field with a value of 1.

request_id stringUnique request identifier for tracing and troubleshooting.

Task successful
Task failed
Task query expired

{
    "request_id": "cf7a3a1d-27b0-4d45-8b89-xxxxxx",
    "output": {
        "task_id": "88125b85-b53d-45f1-ba13-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-27 14:39:15.041",
        "scheduled_time": "2026-03-27 14:39:15.081",
        "end_time": "2026-03-27 14:40:03.428",
        "orig_prompt": "A kitten jumps down from the windowsill, lands lightly on the sofa, and then looks around curiously.",
        "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/xxx.mp4?xxx"
    },
    "usage": {
        "duration": 5,
        "size": "828*624",
        "output_video_duration": 5,
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "SR": "540"
    }
}

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 a model call fails and returns an error message, see Error messages to resolve the issue.

FAQ

Q: Is there a required order for the first and last frames in the media array?

A: Yes, there is. The media array must contain two type=image objects. The first element represents the first frame, and the second element represents the last frame.

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

A: No, they do not. However, we recommend that the resolutions are similar. The ratio of the total pixel count (width × height) between the first and last frames must be between 0.8 and 1.25. A large difference in resolution degrades the generation quality.

​Activate the service

​Scope

​HTTP calls

​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

URL path parameters

Response parameters

​Error codes

​FAQ

​Q: Is there a required order for the first and last frames in the media array?

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

Activate the service

Scope

HTTP calls

Step 1: Create a task and get the task ID

Step 2: Query the result by task ID

Error codes

FAQ

Q: Is there a required order for the first and last frames in the media array?

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