Vidu Reference-to-Video viduq4-preview

Generate videos using the Vidu next-generation flagship preview model viduq4-preview based on reference subjects. This model is optimized for character performance, camera language, and complex visual effects. Supports defining characters/objects through images and text, and referencing them in prompts. After submission, query status via GET /vidu/ent/v2/tasks/{task_id}. Uses model viduq4-preview.

POST /vidu/ent/v2/reference2video

cURL

basic_reference_video

curl --request POST \
  --url https://baze-api.powerbuyin.top/vidu/ent/v2/reference2video \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "viduq4-preview",
  "subjects": [
    {
      "name": "XiaoMing",
      "images": [
        "https://example.com/xiaoming.png"
      ]
    },
    {
      "name": "XiaoHong",
      "images": [
        "https://example.com/xiaohong.png"
      ]
    }
  ],
  "prompt": "@XiaoMing and @XiaoHong are cooking together, and both say they love hot pot.",
  "duration": 5
}
'

200

{
  "task_id": "your_task_id_here",
  "state": "created",
  "model": "viduq4-preview",
  "prompt": "@1 and @2 are cooking together, and both say they love hot pot.",
  "duration": 8,
  "seed": 123456789,
  "resolution": "1080p",
  "payload": "",
  "off_peak": false,
  "credits": "15",
  "created_at": "2025-01-01T15:41:31.968916Z"
}

Authorizations

Authorization · string · header · required

Pass Authorization: Bearer <token> in the request header.

Body

application/json

model · enum<string> · required

Video generation model name.

• viduq4-preview: Vidu next-generation flagship preview model, optimized for character performance, camera language, and complex visual effects. Supports intelligent camera switching, audio-video synchronization, superior consistency across multiple camera positions, and 2K/4K video output.

Available options: viduq4-preview

subjects · object[] · required

List of subjects.

• When using the viduq4-preview model, only image and text subjects can be used, with a maximum of 7 subjects
• Up to 15 reference images can be used (each subject supports up to 3 images)
• Up to 3 reference audio segments can be used as input
• viduq3-mix does not support the use of entities for the time being

Required array length: 1 - 7 elements

Show child attributes

prompt · string · required

Text prompt for describing video generation content, with a maximum length of 5000 characters. You can reference subject content using @subject_name. For example: @XiaoMing and @XiaoHong are cooking together, and both say they love hot pot.

Maximum string length: 5000

auto_subjects · boolean · default: false

Whether to use the intelligent entity library capability.

• true: Utilize the capabilities of the intelligent agent library
• false: Do not use the intelligent agent library capability

audio · boolean · default: true

Whether to enable audio-video output capability.

• false: Outputs silent video
• true: Outputs video with generated speech and background music based on the prompt Note: For the viduq4-preview model, audio defaults to true.

audio_type · enum<string> · default: all

Audio type, required when audio is true.

• all: Sound effects + vocals
• speech_only: Vocal only
• sound-effect_only: Sound effects only

Available options: all, speech_only, sound_effect_only

duration · integer · default: 5

Video duration in seconds. Default values vary by model:

• viduq4-preview: default 5, available: 3-16

Required range: 3 <= x <= 16

seed · integer

Random seed.

• Defaults to a random seed number
• Manually set values will override the default random seed

aspect_ratio · enum<string> · default: 16:9

The aspect ratio of the output video.

• Default: 16:9
• Accepted values: 16:9, 9:16, 1:1 Note: The viduq4-preview model supports any aspect ratio

Available options: 16:9, 9:16, 1:1

resolution · enum<string>

Resolution (based on model & duration):

• viduq4-preview (3-16s): default 720p, options: 540p, 720p, 1080p, 2K, 4K Note: The viduq4-preview model supports 2K and 4K video output.

Available options: 540p, 720p, 1080p, 2K, 4K

payload · string

Transparent transmission parameters. No processing, only data transmission, with a maximum length of 1048576 characters.

Maximum string length: 1048576

off_peak · boolean · default: false

Off peak mode.

• true: Off peak generate mode
• false: Normal generate mode Notes:

1. The off_peak mode consumes lower points (see Pricing for details)
2. Tasks submitted in off peak mode will be generated within 48 hours. Tasks that are not completed will be automatically cancelled and their points will be refunded
3. We also support cancel off_peak tasks
4. The viduq4-preview model supports off-peak tasks when the audio parameter is true

callback_url · string

Callback When creating a task, you need to actively set the callback_url with a POST request. When the video generation task changes its status, Vidu will send a callback request to this URL, containing the latest status of the task. The structure of the callback request content will be the same as the return body of the GET Generation API. The "status" in the callback response includes the following states:

• processing: Task is being processed.
• success: Task is completed (if sending fails, it will retry the callback three times).
• failed: Task failed (if sending fails, it will retry the callback three times). Vidu uses a callback signature algorithm for verification, check out the details here: Callback Signature

server_id · string

Subject ID obtained from the Create Subject API. Required when using an existing subject.

• See [Create and Use Subject Library] for creating subjects.

watermark · boolean · default: false

Whether to add a watermark.

• true: Add watermark
• false: Do not add watermark

Note 1: Currently the watermark content is fixed, default is no watermark Note 2: You can retrieve watermarked video content through the watermarked_url parameter in the query task API

wm_position · enum<integer> · default: 3

Watermark position on the image. Options:

• 1: Top left
• 2: Top right
• 3: Bottom right
• 4: Bottom left

Default: 3

Available options: 1, 2, 3, 4

Required range: 1 <= x <= 4

wm_url · string

Watermark image URL. When not specified, the default watermark is used.

meta_data · string

Metadata identifier, a JSON format string used as a passthrough field. You can customize the format or use the example format below:

{
  "Label": "your_label",
  "ContentProducer": "your_content_producer",
  "ContentPropagator": "your_content_propagator",
  "ProduceID": "your_product_id",
  "PropagateID": "your_propagate_id",
  "ReservedCode1": "your_reserved_code1",
  "ReservedCode2": "your_reserved_code2"
}

When this parameter is empty, the Vidu-generated metadata identifier is used by default.

Response

200

application/json

Submission successful, returns a video task object.

task_id · string

Task ID.

state · enum<string>

Task processing state:

• created: Task created successfully
• queueing: Task in queue
• processing: Task processing
• success: Generation successful
• failed: Task failed

Available options: created, queueing, processing, success, failed

model · string

Model parameter used for this call.

prompt · string

Text prompt used for this call.

images · string[]

Images used for this call.

duration · integer

Video duration parameter used for this call.

seed · integer

Random seed parameter used for this call.

aspect_ratio · string

Aspect ratio parameter used for this call.

resolution · string

Resolution parameter used for this call.

bgm · boolean

Whether to use background music for this call.

audio · boolean

Whether to use audio for this call.

audio_type · string

Audio type parameter used for this call.

payload · string

Payload parameter used for this call.

off_peak · boolean

Off-peak mode parameter used for this call.

credits · integer

Credits consumed for this call.

created_at · string<date-time>

Task creation time.

watermark · boolean

Whether a watermark was used for this task submission.