Vidu reference video API reference - Alibaba Cloud Model Studio

The Vidu reference-to-video model uses a reference image and a text prompt . The model incorporates the subject from the image into the scene described by the prompt to generate smooth video.

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.

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

HTTP calls

Because reference-to-video tasks are long-running (typically 1 to 5 minutes), the API uses asynchronous calls. The process consists of two core steps: "Create a task -> 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

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

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.

ImportantIf this request header is missing, the error "current user api does not support synchronous calls" is returned.

Request body

model string (required)

The model to use. Valid values:

vidu/viduq3-ad_reference2video
vidu/viduq3-drama_reference2video
vidu/viduq3-mix_reference2video

Model selection guide

Advertising videos: Use viduq3-ad. Designed for the advertising industry, it features marketing-grade smart shot transitions, camera movements, and direct audio output. Upload product images to generate advertising videos.
Premium dramas / AI comics: Use viduq3-drama. Strong character consistency, refined effects, and realistic emotional expression, ideal for narrative content production.
General use: Use viduq3-mix. Balanced visual quality and dynamic effects, suitable for most reference-to-video scenarios.

input object (required)

The basic input, which includes reference images and a prompt.

Properties

prompt string (required)

The text prompt. Describes the elements and visual characteristics that you want in the generated video.

Both Chinese and English are supported. The maximum length is 5,000 characters. Text that exceeds this limit is automatically truncated.

Example: A man sits in a chair by a window, holding a guitar and playing a soothing American country folk song in a cafe.

For more information about how to write prompts, see Vidu Video Generation Prompt Guide.

media array (required)

A list of media assets that specifies the reference materials for video generation.

Each element of the array is a media object that contains type and url fields.

Element properties

type string (required)

The media asset type. The valid values depend on the selected model.

Provide reference images only

Supported models: vidu/viduq3-ad_reference2video, vidu/viduq3-drama_reference2video, vidu/viduq3-mix_reference2video

The value is fixed to:

image: Reference image.

Asset limit: 1 to 7 images.

url string (required)

The URL of the media asset.

Provide an image (type=image)

The URL of the reference image. The URL must be publicly accessible.

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

Image limits:

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

parameters object (required)

Parameters for video generation, such as video resolution and duration.

Properties

resolution string (optional)

ImportantThe resolution directly affects billing. Before you call the API, confirm the model pricing.

The resolution of the generated video. The valid values depend on the selected model:

vidu/viduq3-ad_reference2video: 720P or 1080P. Default: 720P.
vidu/viduq3-drama_reference2video: 720P or 1080P. Default: 1080P.
vidu/viduq3-mix_reference2video: 720P or 1080P. Default: 720P.

size string (optional)

The resolution of the generated video, in pixels, formatted as width*height.

The default value depends on resolution:

When resolution=720P, size defaults to 1280*720.
When resolution is 1080P, size defaults to 1920*1080.

Supported aspect ratios vary by model:

vidu/viduq3-drama_reference2video: Only 16:9 and 9:16 are supported.
Other models: 16:9, 4:3, 1:1, 3:4, and 9:16 are supported.

Valid size values by resolution tier:

720P
- 16:9: 1280*720
- 4:3: 1280*960
- 1:1: 1280*1280
- 3:4: 960*1280
- 9:16: 720*1280
1080P
- 16:9: 1920*1080
- 4:3: 1920*1440
- 1:1: 1920*1920
- 3:4: 1440*1920
- 9:16: 1080*1920

duration integer (required)

ImportantThe duration directly affects billing, which is calculated per second. Before you call the API, confirm the model pricing.

The duration of the generated video, in seconds.

vidu/viduq3-ad_reference2video: An integer in the range of [3, 15]. The default value is 5.
vidu/viduq3-drama_reference2video: An integer in the range of [2, 15]. The default value is 5.
- When the number of shots is too many or significantly fewer than the duration, the model may automatically adjust the video length to ensure story completeness. The actual video duration may be longer or shorter than the specified duration value.
- Billing is calculated based on the actual output duration.
vidu/viduq3-mix_reference2video: The value is an integer in the range of [1, 16]. The default value is 5.

audio boolean (optional)

Supported models: vidu/viduq3-ad_reference2video, vidu/viduq3-mix_reference2video.

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

false: The default value. The output is a silent video.
true: Outputs a video with audio.

Notevidu/viduq3-drama_reference2video does not support this parameter. This model outputs videos with audio by default.

watermark boolean (optional)

Specifies whether to add a watermark to the lower-right corner of the video. The watermark text is fixed to "Content generated by AI".

false: Default value. A watermark is not added.
true: Adds a watermark.

seedinteger(optional)

The seed. The value range is [0, 2147483647].

If you do not specify a seed, the system generates one randomly. To improve the reproducibility of results, we recommend setting a fixed seed value.

Note that due to the model's probabilistic nature, using the same seed does not guarantee identical results across runs.

Example: 12345

Advertising (image only)

Supported model: vidu/viduq3-ad_reference2video.

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/viduq3-ad_reference2video",
    "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/dtnctw/ad-1.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/bspdpd/ad-2.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/mhsjyy/ad-3.png"
            }
        ],
        "prompt": "A yoga pants advertisement. The product is a pair of black high-waisted yoga pants with one pocket on each side. An Asian model happily says I will never wear yoga pants without pockets again. The video remains clear, stable, and easy to understand."
    },
    "parameters": {
        "duration": 8,
        "size": "1080*1920",
        "resolution": "1080P",
        "watermark": true
    }
}'

Drama (image only)

Supported model: vidu/viduq3-drama_reference2video.

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/viduq3-drama_reference2video",
       "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/eelcsu/daram-1.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/adglrn/drama-2.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/fmofkp/drama-3.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/mktdht/drama-4.png"
            }
        ],
        "prompt": "Hotel banquet hall. Wang Guilan (Image 3) sits on the right side of the frame. Su Wenbo (Image 1) and Xu Xiangnuan (Image 2) are in the distance on the left, making toasts. The wedding venue is packed with guests. Su Wenbo mother Wang Guilan sits at her seat, brow furrowed tightly, visibly displeased. The camera is fixed, capturing her frowning expression. The camera pushes in on Wang Guilan face - her gaze is dark, corners of her mouth turned down, showing disdain and dissatisfaction."
    },
    "parameters": {
        "duration": 9,
        "size": "1080*1920",
        "resolution": "1080P",
        "watermark": true
    }
}'

Image only

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/viduq3-mix_reference2video",
       "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            }
        ],
        "prompt": "A man sits in a chair by a window, holding a guitar and playing a soothing American country folk song in a cafe."
    },
    "parameters": {
        "duration": 5,
        "size": "1280*720",
        "resolution": "720P",
        "watermark": true
    }
}'

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 output data for the task. 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.

message `string` Detailed error message. Returned only for failed requests. See Error codes.

Step 2: Query the task result

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

Note

Polling recommendation: Video generation can take several minutes. We recommend using a polling mechanism with a reasonable query interval (for example, 15 seconds) to retrieve the result.
Task status transitions: PENDING (queued) → RUNNING (in progress) → SUCCEEDED (successful) / FAILED (failed).
task_id validity period: 24 hours. After the validity period expires, you can no longer query the result, and the API returns the task status as UNKNOWN.
RPS limit: The query API has a default RPS limit of 20. For higher-frequency queries or to receive event notifications, we recommend configuring asynchronous task callbacks.
More operations: For operations such as querying tasks in batches or canceling tasks, see Manage asynchronous tasks.

Request parameters

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.

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

outputobject

The output data for the task.

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_urlstring

The URL of the video. This parameter is returned only when task_status is SUCCEEDED.

The video is in MP4 format (H.264 encoded). The video URL is valid for 24 hours. 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

Usage statistics (counted for successful tasks only).

Properties

duration integer

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

size string

Specifies the resolution of the generated video.

fps integer

Specifies the frame rate of the generated video. The value is fixed at 24.

SR string

Specifies the resolution tier of the generated video.

audio boolean

Indicates whether the generated video includes audio.

video_count integer

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

reference_type string

Specifies the type of reference materials used.

request_id string

Unique request identifier for tracing and troubleshooting.

Task succeeded

Video URLs are valid for only 24 hours and then automatically purged. Save generated videos promptly.

{
    "request_id": "8f240644-efe8-43bf-86ff-xxxxxx",
    "output": {
        "task_id": "b7e05baa-c318-440d-b293-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-27 15:10:42.723",
        "scheduled_time": "2026-03-27 15:10:42.754",
        "end_time": "2026-03-27 15:11:17.388",
        "orig_prompt": "A man sits in a chair by a window, holding a guitar and playing a soothing American country folk song in a cafe.",
        "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/xxx.mp4?xxx"
    },
    "usage": {
        "duration": 5,
        "size": "960*528",
        "output_video_duration": 5,
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "reference_type": "image,video",
        "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"
    }
}

Error codes

If the model call fails and returns an error message, see Error codes for resolution.

FAQ

Q: Do I have to provide both `size` and `resolution`?

A: No. Both parameters are optional, but we recommend providing both. This allows you to precisely control the aspect ratio of the generated video. For details, see Valid size values.

If you do not provide both, the system handles the request as follows:

Only size is passed: The size parameter is ignored, and the system uses the default resolution=720P and its corresponding default size value (1280*720).

Example: The API returns size="1280*720" and SR=720.
If you provide only resolution: The output uses the specified resolution tier.

For example, if you set resolution=540P, the API returns size="960*528" and SR=540. If you set resolution=1080P, the API returns size="1920*1080" and SR=1080.

Usage notes

HTTP calls

Step 1: Create a task

Request parameters

Request headers

Request body

Advertising (image only)

Drama (image only)

Image only

Response parameters

Successful response

Error response

Step 2: Query the task result

Request parameters

Request headers

Path parameters

Query task result

Response parameters

Task succeeded

Task failed

Task query expired

Error codes

FAQ

Q: Do I have to provide both size and resolution?

Q: Do I have to provide both `size` and `resolution`?