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_reference2videovidu/viduq3-drama_reference2videovidu/viduq3-mix_reference2videovidu/viduq3_reference2videovidu/viduq3-turbo_reference2videovidu/viduq2-pro_reference2videovidu/viduq2_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.
- Speed and cost efficiency: Use viduq3-turbo. The fastest generation speed.
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, vidu/viduq3_reference2video, vidu/viduq3-turbo_reference2video, vidu/viduq2_reference2video The value is fixed to: Asset limit: 1 to 7 images. Provide reference images and videos Supported model: vidu/viduq2-pro_reference2video Valid values:
image: The reference image. Required.video: The reference video. Optional. Asset limits: url string (required) The URL of the media asset. Assets include images and videos. Provide an image (type=image) The URL of the reference image. The URL must be publicly accessible. Image limits:
- Formats: JPEG, JPG, PNG, and WEBP.
- Aspect ratio: 1:4 to 4:1.
- File size: Up to 50 MB.
Provide a video (type=video) The URL of the reference video. The URL must be publicly accessible. Video limits:
- Formats: MP4, AVI, and MOV.
- Resolution: The total number of pixels must be at least 128 × 128.
- Aspect ratio: 1:4 to 4:1.
- Duration: 1 to 8 seconds for one reference video; 1 to 5 seconds for each of two reference videos.
- 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.
- vidu/viduq3_reference2video: 540P, 720P, or 1080P. Default: 720P.
- vidu/viduq3-turbo_reference2video: 540P, 720P, or 1080P. Default: 720P.
- vidu/viduq2-pro_reference2video: 540P, 720P, or 1080P. Default: 720P.
- vidu/viduq2_reference2video: 540P, 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=540P, size defaults to
1024*576.
- 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.
Resolution tier | Aspect ratio | Valid size values (width*height) | 540P | 16:9 | 960*528 | 4:3 | 1024*768 | 1:1 | 1024*1024 | 3:4 | 768*1024 | 9:16 | 576*1024 | 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.
-
vidu/viduq3_reference2video: The value is an integer from 1 to 16. The default value is 5.
-
vidu/viduq3-turbo_reference2video: An integer from 1 to 16. The default value is 5.
-
vidu/viduq2-pro_reference2video: An integer from 1 to 10. The default value is 5.
-
vidu/viduq2_reference2video: The value is an integer in the range of [1, 10]. The default value is 5.
audio boolean (optional) Supported models: vidu/viduq3-ad_reference2video, vidu/viduq3-mix_reference2video, vidu/viduq3_reference2video, vidu/viduq3-turbo_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. Replace {WorkspaceId} with your actual workspace ID. 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-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
}
}'
Python SDKfrom 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://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'}]
def sample_async_call():
# Submit video generation task asynchronously
rsp = VideoSynthesis.async_call(api_key=api_key,
model='vidu/viduq3-ad_reference2video',
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.',
media=media,
size='1080*1920',
resolution='1080P',
duration=8,
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()
Drama (image only)Supported model: vidu/viduq3-drama_reference2video. Replace {WorkspaceId} with your actual workspace ID. 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-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 onlyReplace {WorkspaceId} with your actual workspace ID. 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-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
}
}'
Image and videoSupported model: vidu/viduq2-pro_reference2video. Replace {WorkspaceId} with your actual workspace ID. 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/viduq2-pro_reference2video",
"input": {
"media": [
{
"type": "video",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4"
},
{
"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
}
}'
|
