Home/Explore/Vidu/Q3/Reference To Video

Vidu Q3 Reference to Video API

vidu/q3/reference-to-video

Vidu Q3 Reference-to-Video Mix generates multi-entity consistent videos from 1-4 reference images with text prompt guidance. Supports 360p to 1080p resolutions, up to 16 seconds duration, multiple aspect ratios, and optional audio generation. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Reference to Video
Input

Idle

$0.154per run·~64 / $10

Related Models

README

Vidu Q3 Reference-to-Video

Vidu Q3 Reference-to-Video generates cinematic video guided by multiple reference images and a text prompt. Upload one or more reference images to establish character identity, style, or scene elements — the model produces a cohesive, motion-consistent video that blends all provided references into a new scene.

Why Choose This?

  • Multi-image reference generation Upload multiple reference images to combine characters, styles, or visual elements from different sources into a single coherent video.

  • Character-consistent output The model preserves the identity, appearance, and style of subjects from your reference images throughout the generated clip.

  • Optional audio generation Enable generate_audio to produce synchronized ambient sound and atmosphere alongside the video.

  • Flexible resolution options Generate at 720p or 1080p.

  • Reproducible results Use the seed parameter to lock in a specific output for exact reproduction.

  • Prompt Enhancer Built-in tool to automatically improve your scene descriptions for richer output.

Parameters

ParameterRequiredDescription
promptYesText description of the scene, action, and atmosphere.
imagesYes1 to 7 reference images. Click Add Item to include additional images.
aspect_ratioNoOutput aspect ratio. Default: 16:9.
resolutionNoOutput resolution: 720p (default) or 1080p.
durationNoClip length in seconds, 3 to 16. Default: 5.
generate_audioNoWhether to generate synchronized audio for the video. Default: enabled.
seedNoRandom seed for reproducible results.

How to Use

  1. Write your prompt — describe the scene, characters, camera movement, and atmosphere. Use the Prompt Enhancer for better results.
  2. Upload your reference images — provide one or more images via URL or drag-and-drop. Click Add Item to add more.
  3. Select aspect ratio — choose the format that fits your target platform.
  4. Select resolution — 720p, or 1080p for the sharpest output.
  5. Set duration — choose a clip length from 3 to 16 seconds.
  6. Enable audio (optional) — generate_audio is enabled by default; disable it if you only need video.
  7. Set seed (optional) — fix the seed to reproduce a specific result in future runs.
  8. Submit — generate, preview, and download your video.

Pricing

Price depends on the clip duration (3 to 16 seconds) and the resolution (720p or 1080p).

Duration720p1080p
3 s$0.462$0.558
5 s (default)$0.77$0.93
10 s$1.54$1.86
16 s$2.464$2.976

Billing Rules

  • Billing is per second of generated video, so the price grows in proportion to the duration.
  • The rate depends on the resolution. Per second of video, for a 10 s clip divided by 10 s:
ResolutionPer second (10 s clip ÷ 10 s)
720p$0.154
1080p$0.186
  • A run with default settings (5 s, 720p) costs $0.77 per run.
  • Duration: 3 to 16 seconds

Best Use Cases

  • Character-Driven Storytelling — Place consistent characters from reference images into entirely new scenes.
  • Social Media Content — Produce short-form video clips with consistent visual identity from reference photos.
  • Marketing & Brand Video — Generate new scenes featuring consistent brand characters or products from reference imagery.
  • Creative Concepting — Rapidly prototype multi-character or multi-element scenes for pitching and storyboarding.
  • Style-Consistent Series — Maintain a unified visual style across multiple video generations using the same reference set.

Pro Tips

  • Use clear, well-lit reference images with distinct subjects for the most accurate identity preservation.
  • The more reference images you provide, the richer the model's understanding of your intended style and characters.
  • Disable generate_audio if you plan to add your own soundtrack in post-production.
  • Fix the seed once you find a result you like to iterate consistently across resolution and duration changes.
  • Use short 720p clips to test your prompt and reference combination before committing to longer or 1080p renders.

Notes

  • Both prompt and images are required fields; all other parameters are optional.
  • generate_audio is enabled by default — disable it explicitly if you do not need audio.
  • Ensure image URLs are publicly accessible if using links rather than direct uploads.
  • Please ensure your content complies with Vidu's usage policies.

Related Models

Note:This website uses AI models provided by third parties. Documentation prices are for reference and may be outdated. The Generate button shows an estimate; the final task charge prevails.

Q3 Reference To Video API — Quick start

Grab a WaveSpeedAI API key, then call POST https://api.wavespeed.ai/api/v3/vidu/q3/reference-to-video with your input as JSON. The endpoint returns a prediction id. Start polling the result endpoint around every 2 seconds, increase the interval for long-running tasks, and stop on any terminal status. On completed, read output values from data.outputs. Examples for Q3 Reference To Video below.

HTTP example
set -euo pipefail

: "${WAVESPEED_API_KEY:?Set WAVESPEED_API_KEY}"

REQUEST_BODY=$(cat <<'JSON'
{
    "prompt": "A cinematic shot of a city at sunset, soft golden light",
    "images": [
        "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
    ],
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/vidu/q3/reference-to-video" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY" \
  -d "$REQUEST_BODY")

TASK=$(printf '%s' "$SUBMIT_RESPONSE" | jq 'if has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "$TASK" | jq -r '.id')
if [ -z "$PREDICTION_ID" ] || [ "$PREDICTION_ID" = "null" ]; then
  printf 'Submission response did not contain a prediction id
' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/$PREDICTION_ID/result"

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body "$RESULT_URL" \
    -H "Authorization: Bearer $WAVESPEED_API_KEY")
  RESULT=$(printf '%s' "$RESPONSE" | jq 'if has("data") then .data else . end')
  STATUS=$(printf '%s' "$RESULT" | jq -r '.status')
  case "$STATUS" in
    completed) printf '%s\n' "$RESULT" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted) printf '%s\n' "$RESULT" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done
Node.js example
const submitUrl = "https://api.wavespeed.ai/api/v3/vidu/q3/reference-to-video";
const apiKey = process.env.WAVESPEED_API_KEY;
if (!apiKey) throw new Error('Set WAVESPEED_API_KEY');

async function requestJson(url, options = {}) {
  const response = await fetch(url, options);
  if (!response.ok) throw new Error(await response.text());
  return response.json();
}

// 1. Submit the prediction.
const body = await requestJson(submitUrl, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
        "prompt": "A cinematic shot of a city at sunset, soft golden light",
        "images": [
                "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
        ],
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "duration": 5,
        "generate_audio": true
}),
});
const task = body.data ?? body;
if (!task.id) throw new Error("Submission response did not contain a prediction id");
const resultUrl = `https://api.wavespeed.ai/api/v3/predictions/${task.id}/result`;

// 2. Poll until the prediction finishes.
while (true) {
  const resultBody = await requestJson(resultUrl, {
    headers: { "Authorization": `Bearer ${apiKey}` },
  });
  const result = resultBody.data ?? resultBody;
  if (result.status === "completed") {
    console.log(result.outputs);
    break;
  }
  if (["failed", "cancelled", "timeout", "deleted"].includes(result.status)) throw new Error(JSON.stringify(result));
  await new Promise(resolve => setTimeout(resolve, 2000));
}
Python example
import json
import os
import time
from urllib.request import Request, urlopen

api_key = os.environ["WAVESPEED_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
payload = {
    "prompt": "A cinematic shot of a city at sunset, soft golden light",
    "images": [
        "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
    ],
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": True
}

def request_json(url, data=None):
    request = Request(url, data=data, headers=headers, method="POST" if data else "GET")
    with urlopen(request) as response:
        return json.load(response)

# 1. Submit the prediction.
body = request_json("https://api.wavespeed.ai/api/v3/vidu/q3/reference-to-video", json.dumps(payload).encode())
task = body.get("data", body)
if not task.get("id"):
    raise RuntimeError("Submission response did not contain a prediction id")
result_url = f"https://api.wavespeed.ai/api/v3/predictions/{task['id']}/result"

# 2. Poll until the prediction finishes.
while True:
    result_body = request_json(result_url)
    result = result_body.get("data", result_body)
    status = result.get("status")
    if status == "completed":
        print(result.get("outputs", []))
        break
    if status in {"failed", "cancelled", "timeout", "deleted"}:
        raise RuntimeError(result)
    time.sleep(2)

Q3 Reference To Video API — Frequently asked questions

What is the Q3 Reference To Video API?

Q3 Reference To Video is a Vidu model for reference-guided video generation, exposed as a REST API on WaveSpeedAI. Vidu Q3 Reference-to-Video Mix generates multi-entity consistent videos from 1-4 reference images with text prompt guidance. Supports 360p to 1080p resolutions, up to 16 seconds duration, multiple aspect ratios, and optional audio generation. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing. You can call it programmatically or try it from the playground above.

How do I call the Q3 Reference To Video API?

POST your input parameters to the model's REST endpoint (shown in the API tab of this playground) with your WaveSpeedAI API key in the Authorization header. Submission returns a prediction ID. Poll the result endpoint starting around every 2 seconds, increase the interval for long-running tasks, and stop on any terminal status. The playground generates Python, JavaScript, and cURL examples for submitting requests and polling results. Full request/response shape is documented at https://wavespeed.ai/docs/docs-api/vidu/q3/reference-to-video.

How much does Q3 Reference To Video cost per run or per second?

Q3 Reference To Video starts at $0.154 per run or per second. That figure is the base price — the final charge scales with the parameters you set in the form (output size, length, count, references, or whatever knobs this model exposes), so a higher-quality or larger output costs more than a minimal one. The exact cost for your current input is shown live next to the Generate button before you submit, and the actual per-call charge is recorded on the prediction afterwards.

What inputs does Q3 Reference To Video accept?

Key inputs: `prompt`, `images`, `aspect_ratio`, `resolution`, `duration`, `seed`. The full JSON schema (types, defaults, allowed values) is rendered above the Generate button and mirrored in the API reference at https://wavespeed.ai/docs/docs-api/vidu/q3/reference-to-video.

How long does Q3 Reference To Video take to generate?

Reported generation time on WaveSpeedAI is around 142 seconds per request. This is an estimate, not a latency guarantee; queue time and input settings can change the total wait. live status is visible in the prediction record.

Can I use Q3 Reference To Video outputs commercially?

Commercial usage rights depend on the model's license, set by its provider (Vidu). Check the provider's applicable terms and WaveSpeedAI's Terms of Service before commercial use.

llms.txt — vidu/q3/reference-to-video for AI agents and LLMs