DocsICP FilingConsole
官方文档
首页

Vidu - Image-to-video - First and last frame API reference

更新时间：
复制 MD 格式
产品详情
我的收藏

The Vidu first and last frame video generation model creates a smoothly transitioning video 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

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.

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://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

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

First and last frame video generation

curl --location 'https://dashscope.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
    }
}'
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. 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)

Important

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)

Important

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.

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

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": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

output object

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://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

Note

  • 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

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

Response parameters

Task successful

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

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

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

Statistics for the output information. This parameter is counted only for successful results.

Properties

duration integer

The total billable video duration in seconds. Example: 5.

output_video_duration integer

The duration of the output video in seconds. Example: 5.

size string

The resolution of the output video. Example: 828*624.

fps integer

The frame rate of the output video. Example: 24.

SR string

The resolution tier of the output video. Example: 540.

audio boolean

Indicates whether the output video has sound. Example: false.

video_count integer

The number of output videos. This is a static field with a value of 1.

request_id string

Unique request identifier for tracing and troubleshooting.

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.

Previous：Vidu: Image-to-video from an initial frameNext：Vidu-reference-to-video