Vidu

Vidu Q4 Preview

vidu-q4-preview/image-to-video

The first publicly available preview of the Vidu Q4 series, focused on character performance and native audio, supporting reference guidance from up to 15 images and 3 audio clips, and outputting video at up to 4K

vidu-q4-preview/image-to-video vidu-q4-preview/reference-to-video

Try vidu-q4-preview/image-to-video

Input

Showcases

View all showcases

Output

video

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

Pricing

vidu-q4-preview/image-to-video per second

Specifications	Unit Price
540P	$0.0515
720P	$0.109
1080P	$0.1375
2K	$0.2175
4K	$0.446

Positioning Overview

vidu-q4-preview/image-to-video is the first preview release in the Vidu Q4 series, generating video with native audio starting from a first-frame image. The model supports durations from 3 to 16 seconds and output resolutions from 540p to 4K, with the aspect ratio following the first-frame image; motion, camera movement, and sound can be described via prompts. It suits developers who need character performance, cinematic language, and synchronized sound effects, for narrative short films, advertising pre-visualization, or multi-option pitches.

Key Highlights

First-frame driven with native synchronized audio — The first-frame image locks in the composition and aspect ratio, and dialogue and sound effects are produced by default at generation time; audio output can also be turned off to produce a silent video.
A single generation covers 3–16 seconds and 4K output — Duration and resolution parameters are adjustable within the same pipeline, from 540p to 4K as needed, reducing the need to stitch together long shots from segments.
The Q4 preview focuses on expressive performance — Officially positioned as a comprehensive upgrade in character performance, cinematic language, and visual effects, suited to shots that demand continuity of motion and emotion.

Capabilities

First frame to video with sound: Pass in a single first-frame image to generate video, with the aspect ratio following the image; native audio is on by default, yielding dialogue and sound effects together, and turning it off produces a silent video.

Adjustable duration and resolution: A single generation can be set to any whole number of seconds between 3 and 16, and resolution supports five tiers—540p, 720p, 1080p, 2K, and 4K—so usage can be planned by output specification.

Prompts control motion and sound: Prompts can be up to 20,000 characters and can describe motion, camera movement, and sound, guiding both the visual dynamics and the audio content.

Clear image input limits: The first-frame image supports JPG, JPEG, PNG, and WEBP, up to 50MB, with an aspect ratio between 1:4 and 4:1, making it easy to validate assets before integration.

Use Cases

Narrative short films for independent creators and small studios — Use a key frame as the first frame together with prompts to generate short clips with dialogue and sound effects that go straight into the editing workflow.
Shot pre-visualization for ads and brand films — Drive generation from product images or storyboard frames at multiple resolutions, so clients can confirm camera position, pacing, and sound direction before formal production begins.
Multi-option pitches for narrative shots — Adjust prompts and duration parameters against the same first frame to batch-output different performance or camera-movement options for internal selection.

Limitations and Selection Advice

This model is a Preview release, and the official documentation states that its capabilities and features will continue to change; it is not recommended as the sole dependency of a long-term, stable production pipeline. A single generation is capped at 16 seconds, so longer shots require segmented generation and stitching; input starts from a single first-frame image, and multiple reference assets cannot be mixed within one pipeline. If reference images or audio references are needed to maintain character and voice consistency, the reference-to-video pipeline in the same series should be used instead. When there is a hard requirement for multi-shot coherent storytelling or very long videos, other models that support longer durations or stronger consistency control should be evaluated.

Frequently asked questions

View all FAQs →

Can I set the output aspect ratio?

No. The frame follows the first-frame image completely: landscape in, landscape out; portrait in, portrait out — so prepare a portrait frame when you want 9:16. The first frame's ratio must sit between 1:4 and 4:1; extreme slivers are rejected on submit.
What does the audio switch do?

Native audio is on by default and generates dialogue, ambience and effects in sync with the picture. Turn it off for a silent, picture-only clip — useful for looping backgrounds, your own soundtrack or burned-in captions. The switch does not change the price.
How do duration and billing relate?

Billing is the submitted whole-second duration times the per-second rate of the resolution you picked; the audio switch and the number of images are not priced. Higher tiers carry a higher rate — 4K is roughly 8.7 times the 540p rate — and the pricing page lists the current amounts.
What is each resolution tier good for?

540p for testing prompts and camera moves (and for small looping backgrounds), 720p for most social and web use, 1080p for regular paid placements, 2K for large screens and TV, and 4K for exhibition, cinema-grade picture or shots you plan to crop in post. Draft low, render the keepers high.

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-q4-preview/image-to-video

routestringOptional

Current fixed value: default

inputobjectRequired

Business parameters for vidu-q4-preview/image-to-video and route default — see the parameter table below.

audiobooleanOptionalDefault: true

Controls whether to generate native audio synchronized with the video (dialogue and sound effects); boolean, set to false to output a silent video, defaults to true.

promptstringOptionalmaxLength 20000

Optional. A prompt describing the visual motion, camera movement, and sound, up to 20000 characters.

durationintegerOptionalDefault: 5min 3max 16

Video duration in seconds, an integer between 3 and 16, default 5.

image_urlstringRequiredminLength 1

The address of the image to use as the first frame of the video; the output video preserves the aspect ratio of this image; supports JPG, JPEG, PNG, WEBP, size no more than 50MB, aspect ratio must be between 1:4 and 4:1.

resolutionstringOptionalDefault: "720p"

The resolution of the output video, default 720p.

Options:540p720p1080p2k4k

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-q4-preview/image-to-video",
  "input": {
    "audio": true,
    "duration": 5,
    "image_url": "…",
    "resolution": "720p"
  }
}'

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-q4-preview/image-to-video",
    input: {
      "audio": true,
      "duration": 5,
      "image_url": "…",
      "resolution": "720p"
    }
  }),
});
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-q4-preview/image-to-video",
        "input": {
          "audio": True,
          "duration": 5,
          "image_url": "…",
          "resolution": "720p"
        }
    },
)
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"
    }
  }
}