Vidu Q3 Mix 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-mix/reference-to-video
Capability	Reference-image consistency for general scenes
Resolution	720P / 1080P
Duration	1-16 seconds

1-7 reference images lock characters, products and scenes into a 1-16 second video at 720P or 1080P, across 10 frame sizes.

Production guidance

Calling the API

Reference inputs by order: reference image 1, reference image 2 ... the numbers map one to one onto the reference_image_urls array.
size settles the frame and the resolution tier together across 10 values (5 frames times 720P/1080P); the 1:1 value at 1080P is 1808*1808.
Refine motion and composition at 720P first and re-run the final take at 1080P to keep charges down.
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

Composing several assets

Character, setting and prop each from their own reference, combined by one prompt.

reference_image_urls

Native portrait clips

Choose 720*1280 for a vertical render rather than a crop.

size

Longer reference clips

Length reaches 16 seconds, beyond most comparable endpoints.

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-mix/reference-to-video",
  "input": {
    "prompt": "The felt owl plush from reference image 1 perches on the wooden table of the old bookshop in reference image 2, blinking, camera pushing slowly past the shelves",
    "reference_image_urls": [
      "https://example.com/owl.png",
      "https://example.com/bookshop.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-mix/reference-to-video",
  "input": {
    "prompt": "The felt owl plush from reference image 1 perches on the wooden table of the old bookshop in reference image 2, blinking, camera pushing slowly past the shelves",
    "reference_image_urls": [
      "https://example.com/owl.png",
      "https://example.com/bookshop.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-mix/reference-to-video",
  "input": {
    "prompt": "The felt owl plush from reference image 1 perches on the wooden table of the old bookshop in reference image 2, blinking, camera pushing slowly past the shelves",
    "reference_image_urls": [
      "https://example.com/owl.png",
      "https://example.com/bookshop.png"
    ],
    "size": "1280*720",
    "duration": 5
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

model string required

Model ID.

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

input object required

Reference-to-video parameters.

prompt string required

Describe the video and reference inputs by order, e.g. "the character from reference image 1 walks into the scene from reference image 2". Chinese or English, up to 5000 characters.

reference_image_urls string[] required

Array of 1-7 reference image URLs keeping characters, products and scenes consistent. 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. The frame comes from the size itself, so no separate ratio parameter is needed.

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

duration integer optional

Output duration in seconds. Accepts integers from 1 to 16.

default 5

audio boolean optional

Generate background music and effects 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 brings runs from the same inputs closer together without guaranteeing an identical result.

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

How many reference images at most?

Up to 7. Reference inputs by order in the prompt: reference image 1, reference image 2 ... matching the order of the reference_image_urls array.

Why are only fixed sizes available?

The API accepts 10 enumerated values: the 16:9, 4:3, 1:1, 3:4 and 9:16 frames, each at the 720P and 1080P tiers. That settles the frame and the resolution tier at once with no separate ratio parameter.

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.

How is it different from Vidu Q4 Preview reference-to-video?

Q4 Preview supports voice references and up to 15 reference images, and splits resolution from frame into two parameters; Q3 Mix takes image references only, settles frame and resolution in size, and reaches down to a 1-second clip.