Vidu

Vidu Q3

vidu-q3-mix/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

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

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

Input

Output

Fill in the parameters and run — results show up here.

Pricing

vidu-q3-mix/reference-to-video per second

Specifications	Unit Price
1280*720	$0.1555
1280*960	$0.1555
1280*1280	$0.1555
960*1280	$0.1555
720*1280	$0.1555
1920*1080	$0.1865
1920*1440	$0.1865
1808*1808	$0.1865
1440*1920	$0.1865
1080*1920	$0.1865

Overview

Vidu Q3's reference-image-to-video pipeline: use 1 to 7 reference images (people, objects, or styles) to constrain the main subject of the frame, and pair them with a prompt to generate short videos of 1 to 16 seconds. Output supports two tiers, 720P and 1080P, with five aspect ratios, and optionally generates audio that matches the visuals. It is suited for developers who need to keep character or product appearance consistent across multi-shot clips and quickly produce candidate versions, for short-form content such as ad assets, e-commerce showcases, and character-driven short dramas.

Key Highlights

Multi-image references constrain subject consistency — pass up to 7 reference images and cite them in the prompt in order as Image1, Image2, etc., each constraining people, objects, and overall style separately.
Optional audio generated in sync with the visuals — when audio is enabled, sound matching the visuals is generated; when disabled, a silent video is output, so you can decide case by case whether post-production dubbing is needed.
Fine control over duration and aspect ratio — duration is continuously adjustable from 1 to 16 seconds, and aspect ratios cover 16:9, 4:3, 1:1, 3:4, and 9:16, so vertical and horizontal assets require no secondary cropping.
Reproducible results with seed — fixing the seed lets you repeatedly render the same prompt and reference-image combination, making it easy to compare parameter tuning and do version regression.

Capabilities

Reference-image-to-video: generation is driven by 1 to 7 JPG, PNG, or WEBP images that serve as the basis for appearance and composition, with a maximum of 50MB per image and aspect ratios from 1:4 to 4:1, making it easy to reuse existing character designs or product images.

Prompt bound to image indices: prompts can be up to 5000 characters and can describe scene, motion, camera, and sound at the same time, while Image1, Image2, etc. specify each reference image's role in array order.

Dual-tier resolution output: output sizes cover two tiers, 720P and 1080P, each with five aspect ratios, so you can directly select the finished-video spec for the distribution channel.

Audio and duration controls: the audio switch determines whether matching sound is generated, and duration takes a value from 1 to 16 seconds, accommodating needs ranging from short animated clips to complete short-film shots.

Watermark and seed control: the optional AI-generated watermark is off by default, and the seed parameter fixes the random seed, making it convenient to reproduce and trace a given result during batch trial renders.

Use Cases

E-commerce and product teams: generate showcase clips from multiple product images — constrain appearance with multi-angle product images and produce several-second product demo clips for detail pages and ad assets.
Ad creative teams: storyboards driven by character design images — generate 9:16 or 16:9 short shots with character and scene reference images as candidate versions for pitches and A/B testing.
Short-drama and anime creators: character-consistent clips — batch-generate shots with fixed character reference images and stitch them into character-driven short clips for concept validation.
Social content production that needs sound — enable audio to generate vertical short clips with sound, used directly for sample evaluation before publishing on social platforms.

Limitations and Selection Advice

The maximum duration per generation is 16 seconds; long videos or complex continuous narratives require you to storyboard and generate multiple times, then edit and stitch them together. Reference images must be publicly accessible JPG, PNG, or WEBP files; assets whose resolution or aspect ratio falls outside 1:4 to 4:1 cannot be used. The audio switch is off by default, so you must explicitly enable it when sound is needed. If your need is conventional single-image-driven image-to-video, refer to other pipelines in the same family; when you need long films or more complex narratives, this pipeline's single-clip positioning is not suitable.

Create a generation task

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

Headers

AuthorizationstringRequired

Account API key. Required on every request. Example: Bearer YOUR_HIAPI_API_KEY. Get your API key

Content-TypestringOptional

The 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-KeystringOptional

Idempotency key, up to 255 bytes. Retries with the same key from the same account create the task only once; replays return the original taskId.

Idempotency key

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

modelstringRequired

Current fixed value: vidu-q3-mix/reference-to-video

routestringOptional

Current fixed value: default

inputobjectRequired

Business parameters for vidu-q3-mix/reference-to-video and route default — see the parameter table below.

seedintegerOptionalmin 0max 2147483647

Random seed for reproducing generation results; an integer between 0 and 2147483647.

sizestringOptionalDefault: "1280*720"

Output frame size in the format WIDTH*HEIGHT, default 1280*720; available in two tiers, 720P and 1080P, each including multiple aspect ratios; per-second pricing varies by tier.

Options:1280*7201280*9601280*1280960*1280720*12801920*10801920*14401808*1808

Show all (2)

1440*19201080*1920

audiobooleanOptionalDefault: false

Whether to generate audio matching the visuals; boolean, default false, meaning the output video has no sound.

promptstringRequiredminLength 1maxLength 5000

A prompt describing the scene, motion, camera, and sound; reference images are referenced in the prompt by index such as Image1, Image2, in array order.

durationintegerRequiredDefault: 5min 1max 16

Output video duration in seconds; an integer between 1 and 16, default 5.

watermarkbooleanOptionalDefault: false

Whether to add an AI-generated watermark in the bottom-right corner of the frame; boolean, default false.

reference_image_urlsarrayRequiredminItems 1maxItems 7

Array of reference images; provide 1 to 7 reference images (people, objects, or styles). Elements are image URLs in JPG/PNG/WEBP format, each no larger than 50MB, with an aspect ratio between 1:4 and 4:1, and publicly accessible.

Array [ string ]

callbackobjectOptional

Terminal-state notification config. When omitted, no callback is delivered — poll the task yourself. See the callback note below.

Callbacks (Webhook)

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.

urlstringRequired

Required 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.

Options:final

storagestringOptionalDefault: "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.

Options:temppersistent

Request 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-mix/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-mix/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-mix/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

GET https://api.hiapi.ai/v1/tasks/:id

Response fields

taskIdstringRequired

Task ID, always prefixed with tk-hiapi-.

modelstringRequired

Resolved 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.

routestringOptional

Present only when the task was submitted with an explicit route parameter; echoes the submitted value.

statusstringRequired

Task status.

Status values

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.

creatednumberRequired

Task creation time (Unix seconds).

completednumberRequired

Unix 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

urlstringRequired

Artifact URL, directly downloadable.

typestringRequired

Current possible values: video, image, audio, first_frame, last_frame, thumbnail; more may be added later.

expireAtnumberRequired

Unix seconds until which the artifact remains accessible; download or transfer before it expires.

errorobjectOptional

Present only when status == fail.

codestringRequired

Business error code.

messagestringRequired

Error 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"
    }
  }
}