Vidu - Image-to-video from an initial frame API reference

Usage notes

To ensure successful API calls, you must use a model, endpoint URL, and API key that all belong to the same region. Cross-region calls will fail.

Select a model: Confirm the region where your model is located.
Select a URL: Choose the corresponding endpoint URL. Both HTTP and DashScope SDK URLs are supported.
Configure an API key: Select a region, get an API key, and then configure the API key as an environment variable.

The sample code in this topic applies to the Singapore region.

HTTP calls

Image-to-video generation is a long-running task that typically takes 1 to 5 minutes, so the API uses an asynchronous model. The workflow consists of two core steps: create a task, then poll for the result.

Step 1: Create a task

Singapore region: POST https://{WorkspaceId}.ap-southeast-1.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

Headers

Content-Type string (Required)The content type of the request. Must be application/json.Content-Type string (Required)The content type of the request. Must be application/json.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 name of the model. Valid values are:

vidu/viduq2-pro-fast_img2video

input object (Required)The basic input, including the text prompt and media assets.

Properties

prompt string (Optional)The text prompt, which describes the desired elements and visual characteristics of the generated video.The maximum length is 5,000 characters (both Chinese characters and English letters count as one). Text exceeding this limit is truncated.For more information about how to write prompts, see Vidu Video Generation Prompt Guide.media array (Required)A list of media assets specifying the image for generation.Each element in the array is a media object containing a type field and a url field.

Properties

type string (Required)The type of the media asset. This must be set to the following fixed value:

image: An image URL.

Asset limitation: You must provide exactly one image asset.url string (Required)The URL of the image file, which must be publicly accessible.

Supported protocols: HTTP or HTTPS.
Example: https://example.com/image.jpg.

Image constraints:

Formats: JPG, JPEG, PNG, WEBP.
Aspect ratio: 1:4 to 4:1.
File size: Up to 50 MB.

parameters object (Optional)Parameters for video processing, such as resolution and duration.

Properties

resolution string (Optional)

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

Specifies the resolution tier for the generated video.The model scales the video to a pixel count that approximates the selected tier while preserving the input image's aspect ratio.Valid values are 720P and 1080P. The default is 720P.duration integer (Optional)

The duration setting directly affects the cost, which is billed per 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.An integer in the range [1, 10]. The default is 5.audio boolean (Optional)watermark boolean (Optional)Specifies whether to add a watermark. The watermark is placed in the bottom-right corner of the video and contains the fixed text "Generated by AI".

false: (Default) No watermark is added.
true: A watermark is added.

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

curl --location 'https://{WorkspaceId}.ap-southeast-1.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/viduq2-pro-fast_img2video",
    "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260121/zlpocv/wan-i2v-haigui.webp"
            }
        ],
        "prompt": "The camera slowly pans up from below a sea turtle that is swimming leisurely, with clear details of its belly visible."
    },
    "parameters": {
        "duration": 5,
        "resolution": "720P",
        "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

Singapore region: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Polling recommendation: Video generation can take several minutes. Poll for the result at a reasonable interval, such as every 15 seconds.
Task status flow: PENDING (queued) → RUNNING (processing) → SUCCEEDED (successful) / FAILED (failed).
Task ID validity: The task_id is valid for 24 hours. After this period, queries will fail and return a status of UNKNOWN.
RPS limit: The query endpoint has a default limit of 20 RPS. For high-frequency queries or event notifications, configure asynchronous task callbacks.
More operations: To perform batch queries, cancel tasks, or run other operations, 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

curl -X GET https://{WorkspaceId}.ap-southeast-1.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.end_time stringThe time when the task was completed. format is YYYY-MM-DD HH:mm:ss.SSS.orig_prompt stringVideo URL. Returned only when task_status is SUCCEEDED.The video format is MP4 (H.264 encoding). The video link is valid for 24 hours. Please 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 objectOutput usage statistics, counted only for successful tasks.

Properties

duration integerThe total billable video duration in seconds.output_video_durationintegerThe duration of the output video in seconds.size stringThe resolution of the output video.fps integerThe frame rate of the output video. This is fixed at 24.SR stringThe resolution tier of the output video.audio booleanIndicates whether the output is a video with audio.video_count integerThe number of output videos. This is fixed at 1.

request_id stringUnique request identifier for tracing and troubleshooting.

Task succeeded
Task failed
Task query expired

{
    "request_id": "3606f9f4-b833-44ec-8385-xxxxxx",
    "output": {
        "task_id": "2846881f-0496-4288-947f-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-27 14:25:32.057",
        "scheduled_time": "2026-03-27 14:25:32.084",
        "end_time": "2026-03-27 14:28:29.600",
        "orig_prompt": "The camera slowly pans up from below a sea turtle that is swimming leisurely, with clear details of its belly visible.",
        "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/xxx.mp4?xxxx"
    },
    "usage": {
        "duration": 5,
        "size": "990*932",
        "output_video_duration": 5,
        "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 a model call fails, see Error Messages to troubleshoot the error.

​Usage notes

​HTTP calls

​Step 1: Create a task

Request parameters

Headers

Request body

Response parameters

​Step 2: Query the result

Request parameters

Headers

Path parameters

Response parameters

​Error codes

Usage notes

HTTP calls

Step 1: Create a task

Step 2: Query the result

Error codes