Vidu Q3 Ad Reference to Video API

POST Base URL: https://api.hiapi.ai /v1/tasks

Image, video, and audio models are called through theUnified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).

Model summary

Model	vidu-q3-ad/reference-to-video
Capability	Reference-image consistency for advertising
Resolution	720P / 1080P
Duration	3-15 seconds

Reference-to-video built for product ads: a product shot becomes a 3-15 second ad clip at 720P or 1080P with camera work, shot cutting and sound generated.

Production guidance

Calling the API

Ad clips are short, so saying what the product is, what action the viewer sees and how the camera moves is enough — stacked adjectives tend to pull the shot apart.
size settles the frame and the resolution tier together across 10 values (5 frames times 720P/1080P).
duration runs 3-15; the model may adjust the actual length to keep shots coherent, so reserve against the value you set and reconcile against the actual seconds.
Use callback.url for task notifications; read the task object from data in query responses and directly from the callback body.
Artifact URLs expire; copy files you need to keep into persistent storage.

Best suited for

E-commerce and feed ads

One product shot yields ad variants at different camera moves and lengths.

reference_image_urlssize

Brand-register footage

Shallow depth of field and a warm neutral grade from the same endpoint.

prompt

The shortest slot

The three-second floor matches feed and splash placements.

duration

Request parameters

POST https://api.hiapi.ai/v1/tasks

# Create an async task — returns taskId immediately (generation runs async)
# Replace YOUR_API_KEY with your account API key
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "vidu-q3-ad/reference-to-video",
  "input": {
    "prompt": "A product ad shot of the titanium smartwatch from reference image 1: it rotates slowly on a dark reflective pedestal while a hard strip of light sweeps across the brushed case, camera holding a low hero angle",
    "reference_image_urls": [
      "https://example.com/watch.png"
    ],
    "size": "1280*720",
    "duration": 5
  }
}'

import requests, json

# Business params — fields vary by model (see the model page)
payload = json.loads(r'''
{
  "model": "vidu-q3-ad/reference-to-video",
  "input": {
    "prompt": "A product ad shot of the titanium smartwatch from reference image 1: it rotates slowly on a dark reflective pedestal while a hard strip of light sweeps across the brushed case, camera holding a low hero angle",
    "reference_image_urls": [
      "https://example.com/watch.png"
    ],
    "size": "1280*720",
    "duration": 5
  }
}
''')

# Create an async task — returns taskId immediately (generation runs async)
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # Returns { code, message, data: { taskId } }

// Create an async task — returns taskId immediately (generation runs async)
// Replace YOUR_API_KEY with your account API key
const resp = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "vidu-q3-ad/reference-to-video",
  "input": {
    "prompt": "A product ad shot of the titanium smartwatch from reference image 1: it rotates slowly on a dark reflective pedestal while a hard strip of light sweeps across the brushed case, camera holding a low hero angle",
    "reference_image_urls": [
      "https://example.com/watch.png"
    ],
    "size": "1280*720",
    "duration": 5
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

model string required

Model ID.

example vidu-q3-ad/reference-to-video

input object required

Reference-to-video parameters.

prompt string required

Describe the ad and reference inputs by order, e.g. "a product ad shot of the item in reference image 1". Chinese or English, up to 5000 characters.

reference_image_urls string[] required

Array of 1-7 product reference image URLs. JPEG/JPG/PNG/WEBP, up to 50MB each, aspect ratio 1:4-4:1, and must be a public HTTP(S) URL.

size enum optional

Output frame and resolution tier, written as WIDTH*HEIGHT. The 720P and 1080P tiers each carry the 16:9, 4:3, 1:1, 3:4 and 9:16 frames — ten values in all.

default 1280*720 enum: 1280*7201280*9601280*1280960*1280720*12801920*10801920*14401808*18081440*19201080*1920

duration integer optional

Output duration in seconds, an integer from 3 to 15. When the number of shots is clearly above or below this value the model may adjust the actual length to keep the story whole; billing settles on the actual output seconds.

default 5

audio boolean optional

Generate sound effects and music matched to the picture. Off by default for a silent video, and not priced.

default false

watermark boolean optional

Add a watermark. Off by default; when on, an "AI generated" mark appears in the bottom right corner.

default false

seed integer optional

Random seed from 0 to 2147483647. Fixing it makes prompt-by-prompt comparisons easier.

callback object optional

Sends a notification when the task succeeds or fails; read the task object from data in query responses and directly from the callback body.

url string required

HTTPS URL that receives task success or failure notifications.

example https://your-domain.com/hiapi/callback

when enum optional

Triggers when the task succeeds or fails.

default final enum: final

Getting the result

Read data.taskId from the create-task response.
Wait for the callback or query GET /v1/tasks/:id; polling puts the task under data.
When status=success, read the video URL from output type=video; a callback reads output directly. Charges settle on the actual output seconds.

FAQ

The output came out at a different length than duration. Which one am I billed for?

The actual output. The documentation states that when the number of shots is clearly above or below duration the model may adjust the length to keep the story whole, so the clip can run longer or shorter than requested.

How is it different from Vidu Q3 Mix?

The parameter shape is identical; they differ in the length range (Ad is 3-15 seconds, Mix is 1-16) and in intent — Ad targets advertising with marketing-oriented shot cutting, camera work and sound, at a slightly lower per-second rate.

How many reference images at most?

Up to 7, in JPEG, JPG, PNG or WEBP, up to 50MB each and between 1:4 and 4:1 in ratio. For ads a common pattern is one hero product shot plus one or two in-use shots.

Do audio and watermark change the price?

No. The rate depends only on the resolution tier and the actual output seconds, and neither switch is priced.