Vidu reference-to-video — Create a task

POST

/services/aigc/video-generation/video-synthesis

Reference-to-video

# Singapore (ap-southeast-1). This model is available only in this region.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl --location 'https://ap-southeast-1.maas.qwencloudapi.com/api/v1/services/aigc/video-generation/video-synthesis' \
  --header 'X-DashScope-Async: enable' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "vidu/viduq3-ad_reference2video",
  "input": {
    "prompt": "A man sits in a chair by a window, holding a guitar and playing a soothing American country folk song in a cafe.",
    "media": [
      {
        "type": "image",
        "url": "https://example.com/reference.png"
      }
    ]
  },
  "parameters": {
    "resolution": "720P",
    "size": "1280*720",
    "duration": 5,
    "audio": false,
    "watermark": false,
    "seed": 12345
  }
}'

{
  "output": {
    "task_status": "PENDING",
    "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
  },
  "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Vidu reference-to-video models use reference images and a text prompt to generate a video that keeps the subject consistent across scenes. Three models target different scenarios:

Model	Use this when
`vidu/viduq3-ad_reference2video`	Advertising videos. Marketing-grade shot transitions, camera movement, and audio. Upload product images.
`vidu/viduq3-drama_reference2video`	Premium dramas and AI comics. Strong character consistency and realistic emotional expression.
`vidu/viduq3-mix_reference2video`	General use. Balanced visual quality and motion.

Supported regions: Singapore only. Use an API key created in that region and the https://ap-southeast-1.maas.qwencloudapi.com endpoint. See Regions and endpoints.

Prompt: required, up to 5,000 characters.
Reference images: 1 to 7 images. JPEG, JPG, PNG, or WEBP; aspect ratio 1:4 to 4:1; up to 50 MB each; publicly accessible HTTP or HTTPS URL.
Duration: viduq3-ad 3 to 15s, viduq3-drama 2 to 15s, viduq3-mix 1 to 16s.
Audio: supported by viduq3-ad and viduq3-mix. viduq3-drama always outputs audio.

Processing is asynchronous: this operation returns a task_id, and you poll Query the result until the task finishes. Generation typically takes 1 to 5 minutes.

Authorizations

string

header

required

QwenCloud API key. See Get an API key.

Header Parameters

enum<string>

required

The content type of the request. Must be application/json.

Available options:application/json

enum<string>

required

Enables asynchronous processing. HTTP requests support only asynchronous calls, so this must be enable.

Available options:enable

Body

application/json

enum<string>

required

The model name. Choose a model based on the scenario:

viduq3-ad: advertising videos with marketing-grade shot transitions, camera movement, and audio.
viduq3-drama: narrative content with strong character consistency and emotional expression.
viduq3-mix: balanced visual quality for general reference-to-video tasks.

Available options:vidu/viduq3-ad_reference2video,vidu/viduq3-drama_reference2video,vidu/viduq3-mix_reference2video

Example:vidu/viduq3-ad_reference2video

object

required

The input object, including reference images and a prompt.

Show child attributes

string

required

The text prompt that describes the elements and visual characteristics of the video. Supports Chinese and English, up to 5,000 characters. Text beyond the limit is truncated.

object[]

required

The reference media. Provide 1 to 7 images.

Show child attributes

enum<string>

The media type. Must be image.

Available options:image

string

The publicly accessible URL of the reference image. Supports HTTP and HTTPS. Formats: JPEG, JPG, PNG, WEBP. Aspect ratio: 1:4 to 4:1. File size: up to 50 MB.

object

required

Video generation parameters.

Show child attributes

enum<string>

The resolution tier of the output video. Billing depends on this value. Defaults: viduq3-ad 720P, viduq3-drama 1080P, viduq3-mix 720P.

Available options:720P,1080P

string

The output resolution in width*height format. Defaults to 1280*720 for 720P and 1920*1080 for 1080P.

Supported aspect ratios:

viduq3-drama: 16:9 and 9:16 only.
Other models: 16:9, 4:3, 1:1, 3:4, and 9:16.

Valid values by 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

Example:1280*720

integer

default5

The video duration in seconds. Billing is per second.

viduq3-ad: 3 to 15. Default: 5.
viduq3-drama: 2 to 15. Default: 5. The model may adjust the length to preserve story completeness; billing uses the actual output duration.
viduq3-mix: 1 to 16. Default: 5.

Required range:1 <= x <= 16

boolean

defaultfalse

Whether to generate audio. When enabled, the model generates background music or sound effects that match the video. Default: false.

Supported by viduq3-ad and viduq3-mix. viduq3-drama ignores this parameter and always outputs audio.

boolean

defaultfalse

Whether to add a watermark in the lower-right corner. The watermark text is "Content generated by AI". Default: false.

integer

The random seed. Range: 0 to 2147483647. A fixed seed improves reproducibility.

Required range:0 <= x <= 2147483647

Response

200-application/json

string

Unique request identifier for tracing and troubleshooting.

object

Show child attributes

string

The task ID. It is valid for queries for 24 hours.

enum<string>

The task status. New tasks start as PENDING.

Available options:PENDING,RUNNING,SUCCEEDED,FAILED,CANCELED,UNKNOWN

string

Error code. Returned only when the request fails.

string

Detailed error message. Returned only when the request fails.