DocsICP FilingConsole
官方文档
首页

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

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

The Vidu image-to-video model generates a smooth video from an input 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 dialog box that appears, confirm the activation and authorization.

Scope

The model, Endpoint URL, and API Key must belong to the same region. Cross-region calls will fail.

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

China (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

Image-to-video

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

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 name of the model. Valid values are:

  • vidu/viduq3-pro_img2video

  • vidu/viduq3-turbo_img2video

  • vidu/viduq2-pro-fast_img2video

  • vidu/viduq2-pro_img2video

  • vidu/viduq2-turbo_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)

Important

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.

  • vidu/viduq3-pro_img2video: Valid values are 540P, 720P, and 1080P. The default is 720P.

  • vidu/viduq3-turbo_img2video: Valid values are 540P, 720P, and 1080P. The default is 720P.

  • vidu/viduq2-pro-fast_img2video: Valid values are 720P and 1080P. The default is 720P.

  • vidu/viduq2-pro_img2video: Valid values are 540P, 720P, and 1080P. The default is 720P.

  • vidu/viduq2-turbo_img2video: Valid values are 540P, 720P, and 1080P. The default is 720P.

duration integer (Optional)

Important

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.

  • vidu/viduq3-pro_img2video: An integer in the range [1, 16]. The default is 5.

  • vidu/viduq3-turbo_img2video: An integer in the range [1, 16]. The default is 5.

  • vidu/viduq2-pro-fast_img2video: An integer in the range [1, 10]. The default is 5.

  • vidu/viduq2-pro_img2video: An integer in the range [1, 10]. The default is 5.

  • vidu/viduq2-turbo_img2video: An integer in the range [1, 10]. The default is 5.

audio boolean (Optional)

Supported models: vidu/viduq3-pro_img2video, vidu/viduq3-turbo_img2video.

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

  • false: (Default) Outputs a silent video.

  • true: Outputs a video with audio.

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.

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

China (Beijing) region: GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

Note

  • 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

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

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

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.

end_time string

The time when the task was completed. format is YYYY-MM-DD HH:mm:ss.SSS.

orig_prompt string

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

Output usage statistics, counted only for successful tasks.

Properties

duration integer

The total billable video duration in seconds.

output_video_duration integer

The duration of the output video in seconds.

size string

The resolution of the output video.

fps integer

The frame rate of the output video. This is fixed at 24.

SR string

The resolution tier of the output video.

audio boolean

Indicates whether the output is a video with audio.

video_count integer

The number of output videos. This is fixed at 1.

request_id string

Unique request identifier for tracing and troubleshooting.

Error codes

If a model call fails, see Error Messages to troubleshoot the error.

Previous：Vidu - Text-to-VideoNext：Vidu - Image-to-video - First and last frame