Vidu Q4 Reference to Video API

vidu/q4/reference-to-video

540p–4K · 3–16 sec

Vidu Q4 Reference to Video combines a prompt with up to 12 reference images and 3 voice clips into 3–16 second videos at up to 4K. Tag each reference in the prompt to keep characters, products and places recognisable, with optional generated audio at no extra cost.

Input

Prompt324/5000

Reference Image Urls

Drag and drop files, paste from clipboard, or provide a URL. Required. 1–12 JPEG, PNG or WebP images.

2/12 files added

Reference Audio Urls

Drag and drop files, paste from clipboard, or provide a URL. Optional. Up to 3 MP3 voice clips, ideally 3–12 seconds each.

Duration

Resolution

Aspect Ratio

Generate Audio

Enable Safety Checker

OutputExample

Continue with

Vidu Q4 Image to Video MiniMax H3 Max Reference to Video Seedance 2.5 Reference to Video

REST API

Quick Start

Make your first Vidu Q4 reference-to-video request in three steps. The example tags two reference images in the prompt and returns a task_id.

Connect to the Vidgo API

Create an API key, keep it on your server, and send it in the Authorization header as a Bearer token.

Endpoint: POSThttps://api.vidgo.ai/api/generate/submit
Authentication: Authorization: Bearer VIDGO_API_KEY

Submit one generation task

Run the short example with a prompt and at least one reference image; voice clips are optional.

Submit request

curl --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "vidu/q4/reference-to-video",
  "input": {
    "prompt": "[@reference_image_1] is the shop owner, [@reference_image_2] is her corner bookshop at dusk. She slides the last paperback onto the shelf, flips the hanging sign on the door and smiles at the street outside. Soft rain on the window, a bell rings as the door closes. One continuous medium shot with a slow dolly to the right.",
    "reference_image_urls": [
      "https://cdn.vidgo.ai/apis/models/vidu/q4/reference-to-video/v1/01/input-01.png",
      "https://cdn.vidgo.ai/apis/models/vidu/q4/reference-to-video/v1/01/input-02.png"
    ],
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}'

Wait for the result

Use the returned task_id to check the same task until it reaches finished or failed. On success, read data.files[].file_url.

Track status

GET https://api.vidgo.ai/api/generate/status/{task_id}

Poll about every 2 seconds while the status is not_started or running. Stop on finished or failed; on success, read data.files[].file_url. For long-running jobs, increase the interval gradually, or add callback_url to the submit request to receive the final result asynchronously.

not_startedrunningfinishedfailed

Submit response

{
  "code": 200,
  "data": {
    "task_id": "KJ245166VBTPWOAM",
    "status": "not_started",
    "created_time": "2026-11-05T07:10:52"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "KJ245166VBTPWOAM",
    "status": "finished",
    "files": [
      {
        "file_url": "https://cdn.vidgo.ai/apis/models/vidu/q4/reference-to-video/v2/01/output-01.mp4",
        "file_type": "video"
      }
    ],
    "created_time": "2026-11-05T07:10:52",
    "error_message": null,
    "progress": 100
  }
}

Complete runnable example

Open this after the three-step flow is clear. It combines submission, polling, terminal-state handling, and result extraction in one script.

Complete runnable example

set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "vidu/q4/reference-to-video",
  "input": {
    "prompt": "[@reference_image_1] is the shop owner, [@reference_image_2] is her corner bookshop at dusk. She slides the last paperback onto the shelf, flips the hanging sign on the door and smiles at the street outside. Soft rain on the window, a bell rings as the door closes. One continuous medium shot with a slow dolly to the right.",
    "reference_image_urls": [
      "https://cdn.vidgo.ai/apis/models/vidu/q4/reference-to-video/v1/01/input-01.png",
      "https://cdn.vidgo.ai/apis/models/vidu/q4/reference-to-video/v1/01/input-02.png"
    ],
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
if [ -z "$TASK_ID" ]; then
  printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi

while true; do
  STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
    --url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
    --header "Authorization: Bearer $VIDGO_API_KEY")
  STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')

  case "$STATUS" in
    finished)
      printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
      break
      ;;
    failed)
      printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
      exit 1
      ;;
    not_started|running)
      sleep 2
      ;;
    *)
      printf 'Unexpected task status: %s
' "$STATUS" >&2
      exit 1
      ;;
  esac
done

Request Parameters

model and callback_url belong at the request root; generation parameters belong inside input.

Field	Type	Required	Default	Description
model	string	Yes	—	Fixed to vidu/q4/reference-to-video.
callback_url	string (URL)	No	—	A public HTTP(S) URL for receiving task completion notifications.
input	object	Yes	—	Generation parameters: a prompt plus 1–12 reference images, with optional voice clips, aspect ratio and audio generation.
input.prompt	string	Yes	—	Scene description, up to 5,000 characters, not blank. Refer to inputs as [@reference_image_1], [@reference_audio_1] and so on, numbered by array order.
input.reference_image_urls	string[]	Yes	—	1–12 public HTTP(S) image URLs for characters, products and locations.
input.reference_audio_urls	string[]	No	—	Up to 3 public HTTP(S) audio URLs used as voice references. Short, clean MP3 clips of about 3–12 seconds work best.
input.duration	integer	No	5	Output length in whole seconds, 3–16. Integer strings such as "5" are also accepted.
input.resolution	string	No	720p	Output resolution: 540p, 720p, 1080p, 2k or 4k (case-insensitive). The rate per second follows this value.
input.aspect_ratio	string	No	—	16:9, 9:16, 4:3, 3:4 or 1:1. Omit it to keep the model default.
input.generate_audio	boolean	No	—	Set true to generate an audio track. The price stays the same.
input.enable_safety_checker	boolean	No	—	Set true or false to control the content safety checker; omit it to keep the model default.

Response Fields

Submission returns the task identity immediately. Status responses add progress, output files, or a failure message as the task advances.

Field	Type	Description
code	integer	Application result code. Successful responses use 0 or 200.
message	string	Human-readable response or error message when present.
data.task_id	string	Task identifier used in the status endpoint path.
data.status	string	Current state: not_started, running, finished, or failed.
data.created_time	string	Task creation time in date-time format.
data.progress	number	Completion percentage when the provider reports progress.
data.files[]	array	Generated output files returned after a successful task.
data.files[].file_url	string	Public URL of the generated video.
data.files[].file_type	string	Generated file type, such as video.
data.files[].watermark_url	string \| null	Watermarked output URL when one is available.
data.error_message	string \| null	Failure detail when status is failed.

Task Lifecycle

Treat not_started and running as non-terminal states. finished and failed are terminal alternatives; stop polling when either is returned.

not_started
The task has been accepted and is queued to start.
running
The video is being generated. Continue polling the status endpoint.
finished
The task is complete. Read the video URL from data.files[].file_url.
failed
Generation failed. Read data.error_message for details and stop polling.

Polling and Errors

Authentication401 indicates a missing or invalid Bearer API Key. Check your key in the dashboard before retrying.
Validation400 indicates invalid parameters. Check the prompt, the 1–12 image and 0–3 audio limits, and that image_urls is not sent.
Polling intervalPoll the status every 2 seconds. For longer tasks, use exponential backoff to gradually increase the interval to 5 seconds.
Terminal statesPoll only while the status is not_started or running. Stop immediately on finished or failed.
Callback optionProvide callback_url to receive an automatic notification when generation finishes, without continuous polling.

Model Specifications

Specification	Value	Description
Model	vidu/q4/reference-to-video	Model identifier for asynchronous Vidu Q4 reference-to-video generation.
Input mode	Prompt + 1–12 images + 0–3 audio	Reference tags in the prompt follow array order.
Aspect ratio	16:9 \| 9:16 \| 4:3 \| 3:4 \| 1:1	Optional.
Duration	3–16	Whole seconds; defaults to 5.
Resolution	540p \| 720p \| 1080p \| 2k \| 4k	Defaults to 720p.
Pricing	9 / 19 / 24 / 38 / 78 credits/s	540p / 720p / 1080p / 2k / 4k, multiplied by duration.

View the Vidu Q4 Reference to Video API documentation

Vidu Q4 Reference to Video

Vidu Q4 Reference to Video belongs to ShengShu Technology's Vidu Q4 (Preview) release of October 2026, focused on multi-reference control and character voices. Reference images supply identities, props and places, while optional reference audio guides how a character sounds. Pick 16:9, 9:16, 4:3, 3:4 or 1:1 and a resolution from 540p to 4K for series, ads and dubbed character clips.

Why choose the Vidu Q4 Reference to Video API?

Up to 12 reference imagesMix characters, products, wardrobe and locations in one request and address each one by its position.
Voice referencesAttach up to 3 reference audio clips to guide how characters sound in the generated video.
Generated audio at the same priceTurn on generate_audio for a soundtrack; the per-second rate stays the same.
Five aspect ratiosDeliver 16:9, 9:16, 4:3, 3:4 or 1:1 directly for each placement.
540p to 4KDraft cheaply at 540p and render finals at 1080p, 2k or 4k from the same references.

Parameters

Parameter	Requirement	Description
prompt	Required	Scene description, up to 5,000 characters, not blank. Refer to inputs as [@reference_image_1], [@reference_audio_1] and so on, numbered by array order. Default`—`
reference_image_urls	Required	1–12 public HTTP(S) image URLs for characters, products and locations. Default`—`
reference_audio_urls	Optional	Up to 3 public HTTP(S) audio URLs used as voice references. Short, clean MP3 clips of about 3–12 seconds work best. Default`—`
duration	Optional	Output length in whole seconds, 3–16. Integer strings such as "5" are also accepted. Default`5`
resolution	Optional	Output resolution: 540p, 720p, 1080p, 2k or 4k (case-insensitive). The rate per second follows this value. Default`720p`
aspect_ratio	Optional	16:9, 9:16, 4:3, 3:4 or 1:1. Omit it to keep the model default. Default`—`
generate_audio	Optional	Set true to generate an audio track. The price stays the same. Default`—`
enable_safety_checker	Optional	Set true or false to control the content safety checker; omit it to keep the model default. Default`—`

How to Use

Collect the referencesGather one clear image per character, product or place, plus optional short voice clips, all at public HTTP(S) URLs.
Tag each reference in the promptWrite [@reference_image_1], [@reference_image_2] or [@reference_audio_1] where each one should appear or speak.
Choose format and soundSet aspect_ratio, duration (3–16 s), resolution and, if you want a soundtrack, generate_audio.
Submit and collect the videoSend the request to receive a task_id, then poll the status endpoint or use callback_url.

Usage and billing

Vidu Q4 Reference to Video is billed per output second at the chosen resolution's rate. Reference images, reference audio and generate_audio do not change the price.

Usage	Rate	Details
540p	9 credits / second	$0.045 / second. A 5-second clip costs 45 credits.
720p	19 credits / second	$0.095 / second. The default; a 5-second clip costs 95 credits.
1080p	24 credits / second	$0.120 / second for Full HD delivery.
2k	38 credits / second	$0.190 / second for large-screen and editing headroom.
4k	78 credits / second	$0.390 / second. A 16-second 4K clip costs 1,248 credits.

Best Use Cases

Short dramas with recurring charactersReuse the same character images and voice clips across episodes to keep faces and voices consistent.
Ad spots from brand assetsCombine a product shot, a model and a location in one prompt for quick ad variations.
Dubbed character clipsPair a character image with a voice reference for talking mascots and story characters.
Vertical social contentRender 9:16 at 540p for drafts, then at 1080p for publishing.

Pro Tips

Number references by array order: the first item in reference_image_urls is [@reference_image_1].
Give each reference one job, such as the face, the outfit or the room, and state that job in the prompt.
Keep voice clips short and clean, without music or background noise.
Set aspect_ratio explicitly when the delivery format matters.

Notes

reference_image_urls is required and holds 1–12 URLs; reference_audio_urls holds up to 3.
To animate a single start frame instead, use Vidu Q4 Image to Video.
Tasks run asynchronously: a successful submission returns a task_id for polling or callback delivery.

Related Models

PixVerse V6 Max Text to VideoPixVerse V6 Max Text to Video turns a prompt into 1–15 second videos at 360p to 1080p, with eight aspect ratios and an optional native audio track for dialogue, effects and music. Describe subjects, actions and sound in one prompt, then pick the length and format for each placement.

PixVerse V6 Max Image to VideoPixVerse V6 Max Image to Video animates one JPEG, PNG or WebP image into a 1–15 second video at 360p to 1080p, with an optional native audio track. The image sets the subject and framing, and a prompt of up to 2,048 characters directs motion, camera and sound.

OmniHuman 2.0 Audio to VideoOmniHuman 2.0 Audio to Video turns one character image and 4–300 seconds of speech or music into a 720p video, with lips, expression and gestures following the audio. The image keeps the character's look and framing, while an optional prompt adds camera moves and actions.

FLUX 3 Max Text to VideoFLUX 3 Max Text to Video turns a written shot into a 5–20 second 720p or 1080p video with native audio and eight aspect ratios. It follows the camera moves, lighting and sound cues you describe, so one prompt returns picture and audio together.

FLUX 3 Max Image to VideoFLUX 3 Max Image to Video animates a start image into a 5–20 second 720p or 1080p clip with native audio, optionally landing on an end frame you supply. It keeps the composition, subject and palette of your images while adding the motion and sound in the prompt.

FLUX 3 Max Keyframes to VideoFLUX 3 Max Keyframes to Video turns 1–10 images pinned to exact frames into a single 5–20 second 720p or 1080p clip with native audio. Each image appears at the frame_index you set on a 24 fps timeline, so the story beats land where you planned them.

Kling 4.0 Text to VideoKling 4.0 Text to Video turns a prompt or multi-shot script into one 3–30 second 720p or 1080p video with stereo audio and five aspect ratios. It keeps scenes coherent across long takes and shot changes while following your camera, dialogue and sound directions.

Kling 4.0 Image to VideoKling 4.0 Image to Video animates a start image into a 3–30 second 720p or 1080p video with stereo audio, optionally finishing on an end frame you choose. It keeps the subject, framing and look of your image while adding the motion, camera work and sound in your prompt.

Kling 4.0 Reference to VideoKling 4.0 Reference to Video turns reference images, videos and reusable elements into a 3–30 second 720p or 1080p video with stereo audio, cited as @Image1, @Video1 or @Element1. It keeps characters, products and settings consistent with your references inside the new scene you describe.

Kling 4.0 Video EditKling 4.0 Video Edit transforms an existing 3–30 second video from a written instruction, restyling scenes, swapping objects or adding elements at 720p or 1080p. It keeps the original timing, people and camera path that you ask to preserve while applying the change across every frame.

Vidu Q4 Image to VideoVidu Q4 Image to Video turns one start image and an optional motion prompt into a 3–16 second clip at 540p up to 4K. Your image sets the opening frame, so subject, setting and aspect ratio carry through while the prompt directs movement and camera.

Gemini Omni 1.1 Flash Text-to-Video preview

Gemini Omni 1.1 Flash Text-to-VideoGemini Omni 1.1 Flash Text-to-Video. Create 4–10 second videos with native audio from text, directing camera, lighting, and sound.

Gemini Omni 1.1 Flash Image-to-Video preview

Gemini Omni 1.1 Flash Image-to-VideoGemini Omni 1.1 Flash Image-to-Video. Animate a start image with native audio and add an optional end frame to guide the closing shot.

Gemini Omni 1.1 Flash Reference-to-Video preview

Gemini Omni 1.1 Flash Reference-to-VideoGemini Omni 1.1 Flash Reference-to-Video. Use 1–7 images to guide characters, products, and style in new video scenes with sound.

Gemini Omni 1.1 Flash Video Edit preview

Gemini Omni 1.1 Flash Video EditGemini Omni 1.1 Flash Video Edit. Edit 3–10 second videos through natural language with up to 5 reference images for visual guidance.

MiniMax H3 Max Turbo Text to Video preview

MiniMax H3 Max Turbo Text to VideoMiniMax H3 Max Turbo Text to Video turns text into coherent 5–15 second videos with synchronized native stereo audio and fast generation. It follows physical motion while rendering subtle changes in light and shadow.

Vidu Q4 Reference to Video API FAQ

What is the Vidu Q4 Reference to Video API?

Vidu Q4 Reference to Video is a ShengShu Technology model for generating video from reference material. It builds 3–16 second clips at up to 4K from a prompt, 1–12 reference images and up to 3 voice clips, with five aspect ratios and optional generated audio. Prompt tags tie each reference to a role, keeping characters, products and places recognisable while the scene unfolds. You can call it programmatically or try it from the playground above.

How many reference images does Vidu Q4 Reference to Video accept?

Between 1 and 12 images in reference_image_urls. Use separate images for each character, product or location and refer to them in the prompt by number.

How do voice references work in Vidu Q4 Reference to Video?

Add up to 3 clips to reference_audio_urls and tag them as [@reference_audio_1] and so on next to the character who should speak. Short, clean MP3 clips of about 3–12 seconds work best.

How do I tag references in a Vidu Q4 Reference to Video prompt?

Write [@reference_image_1], [@reference_image_2] or [@reference_audio_1], numbered by the order of each array, at the point where that element should appear or speak.

Does generated audio cost extra on Vidu Q4 Reference to Video?

No. generate_audio, reference images and reference audio leave the rate unchanged; credits are resolution rate × duration, for example 95 credits for 5 seconds at 720p.

Which aspect ratios can Vidu Q4 Reference to Video output?

16:9, 9:16, 4:3, 3:4 and 1:1 through aspect_ratio. Leave it unset to use the model default.

How long can a Vidu Q4 Reference to Video clip be?

3 to 16 whole seconds, 5 by default, at 540p, 720p, 1080p, 2k or 4k.

When should I choose Vidu Q4 Reference to Video over Image to Video?

Choose Reference to Video when several characters, products or places must appear, when you need voice references, or when you want a fixed aspect ratio. Image to Video starts from one exact frame.