Vidu Q4 Preview 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-q4-preview/reference-to-video
Capability	Reference images + voice references for consistency
Resolution	540p / 720p / 1080p / 2K / 4K
Duration	3-16 seconds

1-15 reference images plus up to 3 voice references keep characters, scenes and voices consistent in a 3-16 second video up to 4K.

Production guidance

Calling the API

Reference inputs by order: reference image 1, reference audio 1.
Reference audio is MP3 only, 3-12 seconds per clip; keep audio on for talking characters.
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

Character consistency

The same character stays consistent in new scenes and actions.

reference_image_urls

Talking characters

Lock a voice with reference audio; the character speaks the lines.

reference_audio_urls

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-q4-preview/reference-to-video",
  "input": {
    "prompt": "The blue bear from reference image 1 walks to the snowy cabin of reference image 2 and speaks in the voice of reference audio 1, then waves at the camera",
    "reference_image_urls": [
      "https://example.com/bear.png",
      "https://example.com/house.png"
    ],
    "reference_audio_urls": [
      "https://example.com/voice.mp3"
    ],
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}'

import requests, json

# Business params — fields vary by model (see the model page)
payload = json.loads(r'''
{
  "model": "vidu-q4-preview/reference-to-video",
  "input": {
    "prompt": "The blue bear from reference image 1 walks to the snowy cabin of reference image 2 and speaks in the voice of reference audio 1, then waves at the camera",
    "reference_image_urls": [
      "https://example.com/bear.png",
      "https://example.com/house.png"
    ],
    "reference_audio_urls": [
      "https://example.com/voice.mp3"
    ],
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}
''')

# 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-q4-preview/reference-to-video",
  "input": {
    "prompt": "The blue bear from reference image 1 walks to the snowy cabin of reference image 2 and speaks in the voice of reference audio 1, then waves at the camera",
    "reference_image_urls": [
      "https://example.com/bear.png",
      "https://example.com/house.png"
    ],
    "reference_audio_urls": [
      "https://example.com/voice.mp3"
    ],
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

model string required

Model ID.

example vidu-q4-preview/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 in reference image 1 ... speaks in the voice of reference audio 1". Up to 20,000 characters.

reference_image_urls string[] required

Array of 1-15 reference image URLs keeping characters, scenes and objects consistent. JPG/JPEG/PNG/WEBP, up to 50MB each; at least 128×128, aspect ratio 1:4-4:1.

reference_audio_urls string[] optional

Array of up to 3 voice references. MP3 only, 3-12 seconds and up to 50MB each.

duration integer optional

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

default 5

resolution enum optional

Output resolution.

default 720p enum: 540p720p1080p2k4k

audio boolean optional

Generate dialogue and sound effects synchronized with the picture.

default true

aspect_ratio enum optional

Output aspect ratio.

default 16:9 enum: 16:99:161:14:33:4

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.

FAQ

How many reference images at most?

Up to 15. Reference inputs by order in the prompt: reference image 1, reference image 2 ... reference audio 1.

What are the reference audio requirements?

MP3 only, 3-12 seconds and up to 50MB per clip, up to 3 clips.

Does turning audio off change the price?

No. Billing is per second, driven by resolution and duration; the audio switch is not priced.

Difference from image-to-video?

Image-to-video takes one first frame and follows its ratio; reference-to-video takes 1-15 images plus up to 3 voice references, with the frame set by aspect_ratio.