Vidu Q2 - Reference to Video

viduq2-reference2video

Vidu Q2 - Reference to Video provides premium image-to-video conversion with reference-guided animation and advanced audio synchronization.

Endpoints

POST /v1/queue/viduq2-reference2video # Create task

GET /v1/queue/viduq2-reference2video/requests/{request_id}/status # Check status

GET /v1/queue/viduq2-reference2video/requests/{request_id}/response # Get result

PUT /v1/queue/viduq2-reference2video/requests/{request_id}/cancel # Cancel task

Request parameters

curl --request 'POST' 'https://odirouter.ai/model/v1/queue/viduq2-reference2video' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --location \
  --data-raw '{
  "prompt": "A clean studio shot of a red apple on a white table, soft natural light.",
  "images": [
    "https://www.gstatic.com/webp/gallery/1.jpg"
  ],
  "subjects": [
    {
      "id": "subject_1",
      "images": [
        "https://www.gstatic.com/webp/gallery/2.jpg"
      ]
    }
  ],
  "audio": true,
  "duration": 5
}'

subjects array required

Subject information from reference images, supports 1 - 7 subjects, total 1 - 7 images

id string required

Subject ID, can be referenced later using @subject_id format

images array required

Image URLs for this subject, each subject supports up to 3 images

Format Requirements:

Supports Base64 encoding or image URL (must be accessible)

Supported formats: png, jpeg, jpg, webp

Image pixels must not be smaller than 128x128, and aspect ratio must be less than 1:4 or 4:1, and size must not exceed 50MB

HTTP request POST body must not exceed 20MB, and encoding must include appropriate content type string. Example: data:image/png;base64,{base64_encode}

voice_id string

Voice ID to determine the voice timbre in the video, when empty, the system will automatically recommend, refer to the available voice list for options

prompt string required

Text description for video generation, maximum 2000 characters

When using subjects parameter, you can use @subject_id to represent subject content, for example: "@1 and @2 eating hotpot together, with voiceover saying everyone loves hotpot."

audio boolean

Whether to use audio-video direct output capability

When true, uses audio-video direct output capability; when false, does not use audio-video direct output capability

Options: true, false

Default: false

duration integer

Video duration in seconds

Options: 1 - 10

Default: 5

seed integer

Random seed, when not provided or set to 0, uses a random number instead, manual setting uses the specified seed

aspect_ratio string

Aspect ratio

Note: Supports any aspect ratio

Options: 16:9, 9:16, 1:1

Default: 16:9

resolution string

Resolution parameter

Options: 540p, 720p, 1080p

Default: 720p

payload string

Pass-through parameter, no processing required, only data transmission, maximum 1048576 characters

off_peak boolean

Note: Temporarily unavailable

Off-peak mode, off-peak mode consumes fewer points. Tasks submitted in off-peak mode will be generated within 48 hours. Tasks that cannot be completed will be automatically canceled and points will be refunded

When true, generates video during off-peak hours; when false, generates video immediately

Note: Audio-video direct output function does not support off-peak mode

Options: true, false

Default: false

watermark boolean

Whether to add a watermark. When true, a watermark is added; when false, no watermark is added

Currently watermark content is fixed and AI-generated, by default no watermark is added

Options: true, false

Default: false

wm_position integer

Watermark position, indicating where the watermark appears on the image

Options: 1 (Top-left), 2 (Top-right), 3 (Bottom-right), 4 (Bottom-left)

Default: 3

wm_url string

Watermark content, provided as an image URL, when not provided, the default AI-generated watermark content is used

callback_url string

Callback URL

Response parameters

{
  "request_id": "task_01hxyz...",
  "response_url": "https://odirouter.ai/model/v1/queue/viduq2-reference2video/requests/task_01hxyz.../response",
  "status_url": "https://odirouter.ai/model/v1/queue/viduq2-reference2video/requests/task_01hxyz.../status",
  "cancel_url": "https://odirouter.ai/model/v1/queue/viduq2-reference2video/requests/task_01hxyz.../cancel",
  "queue_position": 0
}

Field	Type	Description
`request_id`	string	Task ID used for all follow-up operations.
`response_url`	string	URL to fetch the final result.
`status_url`	string	URL to query task status.
`cancel_url`	string	URL to cancel the task.
`queue_position`	int	Current queue position.

Follow-up operations

Check status

Get result

Cancel task

Error handling