Skip to main content
Vidu

Vidu reference video API reference

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.
The 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
  • 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.
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 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_reference2videoThe 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.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)
The 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)
The 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.
vidu/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)
  • Drama (image only)
  • 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
    }
}'

Response parameters

  • 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"
}
output objectThe output data for the task.

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.
message stringDetailed 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}
  • 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

outputobjectThe output data for the task.

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.video_urlstringThe 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 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 objectUsage statistics (counted for successful tasks only).

Properties

duration integerThe total duration of the generated video, used for billing.size stringSpecifies the resolution of the generated video.fps integerSpecifies the frame rate of the generated video. The value is fixed at 24.SR stringSpecifies the resolution tier of the generated video.audio booleanIndicates whether the generated video includes audio.video_count integerSpecifies the number of videos generated. The value is fixed at 1.reference_type stringSpecifies the type of reference materials used.
request_id stringUnique request identifier for tracing and troubleshooting.
  • Task succeeded
  • Task failed
  • Task query expired
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"
    }
}

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.
API Usage
Text Generation
Image Generation
  • FAQ
Video Generation
World models
Audio
  • Audio generation
Real-time Multimodal
Realtime API
Text Embedding
Decision Model
More Models
Toolkit/Framework
TokenPlan
Model Production
File Management
Billing
Model Management
More