Vidu
Vidu Q3
vidu-q3-ad/reference-to-video
A reference image-to-video model for advertising and short social videos that constrains subject appearance and composition, suitable for rapid production and multi-version iteration
Try vidu-q3-ad/reference-to-video
Input
Output
Pricing
vidu-q3-ad/reference-to-video per second
| Specifications | Unit Price |
|---|---|
| 1280*720 | $0.149 |
| 1280*960 | $0.149 |
| 1280*1280 | $0.149 |
| 960*1280 | $0.149 |
| 720*1280 | $0.149 |
| 1920*1080 | $0.180 |
| 1920*1440 | $0.180 |
| 1808*1808 | $0.180 |
| 1440*1920 | $0.180 |
| 1080*1920 | $0.180 |
Positioning Overview
Vidu Q3's reference-to-video route is designed for short video production that requires controllable visuals and stable subjects. Developers submit 1 to 7 reference images plus a prompt to generate a 3 to 15 second video. Reference images are referenced in the prompt as Image1, Image2 in array order, and are used to constrain characters, objects, or visual style. Output supports 720P and 1080P tiers with ten aspect ratios in total, can enable audio generated synchronously with the visuals, and also supports fixed seeds to reproduce results. It is suitable for teams that need rapid multi-version trial footage, such as ad creatives, product demos, and short character clips.
Core Highlights
- Multi-image references constrain subjects and style — Pass in up to 7 reference images at a time and reference them in order as Image1, Image2 in the prompt to constrain characters, objects, or visual style separately.
- Visuals and audio generated in one pass — When audio is enabled, matching sound is generated synchronously with the visuals; when disabled by default, a silent video is output for later custom dubbing.
- Duration and aspect ratio combine as needed — Duration can be 3 to 15 seconds; the 720P and 1080P tiers each include five aspect ratios: 16:9, 4:3, 1:1, 3:4, and 9:16.
- Fixed seeds for easy reproduction and iteration — Supports specifying a random seed from 0 to 2147483647; the same configuration can reproduce results, making it easy to compare the effects of prompt changes.
Capability Description
Multi-reference-image-driven generation: Accepts 1 to 7 publicly accessible JPG, PNG, or WEBP images, up to 50MB each, with aspect ratios from 1:4 to 4:1, used to lock in characters, object appearance, or overall style.
Prompt controls scene and camera movement: A prompt of up to 5000 characters can describe the scene, actions, camera movement, and sound, and uses the Image1, Image2 indices to point to specific reference images for per-image role assignment.
Optional audio generation: The audio switch controls whether matching audio is generated with the visuals; when off, a silent video is output for integration with your own dubbing or music workflow.
Resolution and aspect ratio selection: The size parameter provides 720P and 1080P tiers, each covering landscape, portrait, square, and two vertical ratios, adapting to the final-video specifications of different placements.
Duration and watermark control: duration takes values from 3 to 15 seconds; watermark optionally adds an AI-generated mark in the lower right corner; billing is based on output seconds.
Use Cases
- Brand and media-buying teams: multiple product images + selling-point copy — Produce short ad clips with specified aspect ratios for social platform placements and e-commerce detail page display assets.
- Character content creators: character design sheets + plot descriptions — Generate story short shots with consistent character appearance, used for short drama clips, anime-style concept validation, and storyboard previews.
- Creative teams: style reference images + proposal descriptions — Rapidly produce multiple trial versions for A/B comparison, use fixed seeds to control variables, and move to formal production after selection.
- Product demo production: product photos + usage scenario descriptions — Turn static product images into demo videos with camera movement for official websites, launch events, and training materials.
Limitations and Selection Advice
A single output is limited to 3 to 15 seconds and cannot directly cover long videos or continuous multi-shot narratives; the final video still requires manual editing and splicing. Reference images must be publicly accessible and no more than 50MB each; images in private storage need to be converted to accessible addresses first. Audio is an optional generation item; when dialogue or dubbing must align precisely with the visuals, silent output followed by separate production is more controllable. Currently only reference-image-driven generation is supported; pure text input is not accepted. For ideas without reference materials, please choose the text-to-video route.
Create a generation task
https://api.hiapi.ai/v1/tasks Headers
AuthorizationstringRequiredAccount API key. Required on every request. Example: Bearer YOUR_HIAPI_API_KEY. Get your API key
Content-TypestringOptionalThe request body is always parsed as JSON; when sent, only application/json (optionally with charset) is accepted — any other value returns 415. Example: application/json.
Idempotency-KeystringOptionalIdempotency key, up to 255 bytes. Retries with the same key from the same account create the task only once; replays return the original taskId.
On network timeouts or client retries, the same key creates the task only once — no double charges (scope: the API key's account). Use a business-unique identifier as the key (e.g. "order-42"); replays return the original taskId, and keys expire 24 hours after the first request. See the Unified Async API overview for the full scenario matrix.
Body
modelstringRequiredCurrent fixed value: vidu-q3-ad/reference-to-video
routestringOptionalCurrent fixed value: default
inputobjectRequired
Business parameters for vidu-q3-ad/reference-to-video and route default — see the parameter table below.
seedintegerOptionalmin 0max 2147483647Random seed used to reproduce generation results, value range 0 to 2147483647.
sizestringOptionalDefault: "1280*720"Output video resolution, in the format WIDTH*HEIGHT, available in two tiers, 720P and 1080P; each tier supports 16:9, 4:3, 1:1, 3:4, and 9:16; per-second pricing varies by tier. Default 1280*720.
1280*7201280*9601280*1280960*1280720*12801920*10801920*14401808*1808Show all (2)
1440*19201080*1920audiobooleanOptionalDefault: falseWhether to generate audio matching the visuals; when disabled, outputs a silent video. Default false.
promptstringRequiredminLength 1maxLength 5000Describe the scene, motion, camera, and sound; reference images are cited in the prompt by their array order as Image1, Image2, etc.
durationintegerRequiredDefault: 5min 3max 15Output video duration in seconds, value range 3 to 15. Default 5.
watermarkbooleanOptionalDefault: falseWhether to add an AI-generated watermark in the bottom-right corner; disabled by default. Default false.
reference_image_urlsarrayRequiredminItems 1maxItems 7Array of reference images, providing 1 to 7 images (people, objects, or styles); each must be JPG/PNG/WEBP, no larger than 50MB, with an aspect ratio between 1:4 and 4:1, and publicly accessible; cite them in the prompt as Image1, Image2, etc.
Array [ string ]
callbackobjectOptional
Terminal-state notification config. When omitted, no callback is delivered — poll the task yourself. See the callback note below.
Provide callback.url when creating a task and HiAPI POSTs to your service once the task reaches a terminal state — no polling needed. The callback payload mirrors the task detail structure; signature verification, delivery retries and idempotency are documented on the Unified Async API overview page.
urlstringRequiredRequired when callback is present. A POST is sent to this URL once the task reaches a terminal state; must be a valid http(s) URL.
whenstringOptionalDefault: "final"Only final is supported today — notified on both success and fail.
finalstoragestringOptionalDefault: "temp"Artifact storage tier: temp (default, retained about 7 days) or persistent (long-term, billed by size). Insufficient balance or exceeding the storage cap silently downgrades to temp; the effective tier is shown in the task detail response.
temppersistentRequest examples
# Submit an async task; returns a taskId immediately (no waiting for generation)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "vidu-q3-ad/reference-to-video",
"input": {
"size": "1280*720",
"audio": false,
"prompt": "…",
"duration": 5,
"watermark": false,
"reference_image_urls": "…"
}
}' const res = await fetch("https://api.hiapi.ai/v1/tasks", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "vidu-q3-ad/reference-to-video",
input: {
"size": "1280*720",
"audio": false,
"prompt": "…",
"duration": 5,
"watermark": false,
"reference_image_urls": "…"
}
}),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } } import os, requests
res = requests.post(
"https://api.hiapi.ai/v1/tasks",
headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
json={
"model": "vidu-q3-ad/reference-to-video",
"input": {
"size": "1280*720",
"audio": False,
"prompt": "…",
"duration": 5,
"watermark": False,
"reference_image_urls": "…"
}
},
)
print(res.json()) # { code, message, data: { taskId } } 200 OK
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
}
} 400 Bad Request
{
"code": 400,
"message": "invalid request",
"data": null,
"error_code": "INVALID_REQUEST"
} Get task detail
https://api.hiapi.ai/v1/tasks/:id Response fields
taskIdstringRequiredTask ID, always prefixed with tk-hiapi-.
modelstringRequiredResolved full model name. Tasks submitted with the route parameter return base@route (e.g. gpt-image-2/text-to-image@ext); otherwise identical to the name passed at creation.
routestringOptionalPresent only when the task was submitted with an explicit route parameter; echoes the submitted value.
statusstringRequiredTask status.
queued Queued, not started yet.
handling Being processed.
archiving Processing finished, artifacts being prepared.
success Terminal: completed, artifacts available (output returned).
fail Terminal: failed (error returned).
After submission, check status: success and fail are terminal, everything else is non-terminal. Poll every 1–3 seconds until terminal. On success, download artifacts from output[].url and transfer them before expireAt; pass storage: "persistent" at creation time when long-term retention is needed.
creatednumberRequiredTask creation time (Unix seconds).
completednumberRequiredUnix seconds when the task reached a terminal state; fixed to 0 while not terminal.
outputarrayOptional
Present only when status == success. Artifact list — always an array; a single task may return multiple types at once (e.g. video + first_frame).
Array [ object ]
Array items
urlstringRequiredArtifact URL, directly downloadable.
typestringRequiredCurrent possible values: video, image, audio, first_frame, last_frame, thumbnail; more may be added later.
expireAtnumberRequiredUnix seconds until which the artifact remains accessible; download or transfer before it expires.
errorobjectOptional
Present only when status == fail.
codestringRequiredBusiness error code.
messagestringRequiredError description.
Response examples
Success
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
"model": "happyhorse-1-0",
"status": "success",
"created": 1777282033,
"completed": 1777282099,
"output": [
{
"url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
"type": "video",
"expireAt": 1777886899
}
]
}
} Processing (non-terminal)
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "archiving",
"created": 1777282033,
"completed": 0
}
} Failed
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "fail",
"created": 1777282033,
"completed": 1777282099,
"error": {
"code": "TASK_FAILED",
"message": "task failed"
}
}
} Articles
View all articles →Related Models
View all models →Same Type
-
Veo 3.1 Lite Google $0.060 /second -
Kling 3.0 Turbo Kuaishou $0.130 /second -
HappyHorse 1.0 Alibaba $0.168 /second -
Creatify Boreal Creatify $0.015 /second -
Wan 3.0 Video Alibaba $0.040 /second -
FLUX 3 Video Black Forest Labs $0.090 /second -
Kandinsky 6.0 Pro $1.93 /video -
Wan 2.6 Flash Alibaba $0.043 /second -
Kling 3.0 Kuaishou $0.100 /second -
PixVerse V6 PixVerse $0.036 /second -
HappyHorse 1.1 Alibaba $0.160 /second -
Seedance 2.5 ByteDance $0.121 /second