How to Use the Vidu Q4 Preview Image-to-Video API

Q: Can I send a first frame and a last frame?

No. This mode takes one image_url. For blending several reference images, use the reference-to-video model in the same family.

Q: Is a silent clip cheaper?

No. audio does not affect billing, so a silent render costs the same as one with sound.

TL;DR

What it is: Vidu Q4 Preview image-to-video is live on HiAPI. Upload one first frame, describe the motion, and get a 3–16 second clip at up to 4K, with native audio on by default. Open the model page to try it; new accounts get 200 credits on sign-up.
What it costs: the submitted integer seconds × the per-second rate for the resolution you pick. That is $0.0515/sec at 540p, $0.109 at 720p, $0.1375 at 1080p, $0.2175 at 2K and $0.446 at 4K. A 5-second 720p clip is $0.545; a 5-second 4K clip is $2.23. The audio switch does not change the price.
Fastest path: upload a first frame on the model page and run it at 720p for 5 seconds. For your own product, POST https://api.hiapi.ai/v1/tasks with model set to vidu-q4-preview/image-to-video.

What Vidu Q4 Preview is, and what changed from Q3 Mix

The input is one image. That frame fixes composition, camera position, lighting and aspect ratio; the model adds motion and sound and returns an MP4.

Against Q3 Mix's reference-to-video, Q4's image-to-video makes four concrete moves:

One frame carries the whole shot, 3–16 seconds. There is no reference set to assemble. A single still covers the full clip, and duration is entered in whole seconds, defaulting to 5.
Up to 4K. You can choose 540p, 720p, 1080p, 2K or 4K. Q3 Mix's reference-to-video tops out at 1080P; Q4's image-to-video goes to 4K.
Native audio is on by default. audio defaults to true, so ambience, dialogue and sound effects written into the prompt are generated with the picture. Set it to false for a silent file; the price stays the same.
A narrow schema. There are only five fields: image_url, prompt, duration, resolution and audio. There is no aspect_ratio, and sending one returns a 400. The frame decides the shape.

This seaplane clip is one first frame at 5 seconds and 720p. The push-in, the propeller spin-up and the ripples are all in the prompt:

The pilot waves, the seaplane engine starts and the propeller spins up, gentle ripples spread across the misty lake as the camera slowly pushes in, golden morning light

Generate with this prompt → The link fills the text prompt only. After it opens, upload your own first frame, then set resolution to 720p and duration to 5 seconds to match this clip.

Try it online in 5 steps

Open the Vidu Q4 Preview image-to-video model page. A new account starts with 200 credits.
Upload the first frame: JPG, JPEG, PNG or WEBP, up to 50MB. This frame becomes second zero, so pick the composition you want to keep.
Write only what should be added: the action, the camera move and the sound. Do not re-describe what is already in the picture.
Set duration to a whole number from 3 to 16. Start at 5. Choose 720p for the first pass and leave audio on.
Submit, download the result, and decide whether the final version deserves a higher resolution.

The 200 sign-up credits are about $0.10, not enough for a 3-second 540p clip. Add $10 for the first real batch.

Connect through the API in 4 steps

Create an API key in the console.
POST https://api.hiapi.ai/v1/tasks with model set to vidu-q4-preview/image-to-video and the fields inside input.
Take the returned taskId and poll GET /v1/tasks/{taskId}, or attach a callback at the top level of the request body.
When status reads success, download the MP4 from output[0].url.

A curl you can run

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vidu-q4-preview/image-to-video",
    "input": {
      "image_url": "https://your-cdn.com/first-frame.jpg",
      "prompt": "The pilot waves, the seaplane engine starts and the propeller spins up, gentle ripples spread across the misty lake as the camera slowly pushes in, golden morning light",
      "duration": 5,
      "resolution": "720p",
      "audio": true
    }
  }'

The task ID comes back in data.taskId. Query it with the same Bearer key:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

data.status moves through queued, handling, archiving, success or fail. archiving means the file is still being packaged, not that the job failed.

Python: submit, poll and download

import time
import requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

payload = {
    "model": "vidu-q4-preview/image-to-video",
    "input": {
        "image_url": "https://your-cdn.com/first-frame.jpg",
        "prompt": "The pilot waves, the seaplane engine starts and the propeller spins up, gentle ripples spread across the misty lake as the camera slowly pushes in, golden morning light",
        "duration": 5,
        "resolution": "720p",
        "audio": True,
    },
}

task_id = requests.post(BASE, headers=HEADERS, json=payload, timeout=30).json()["data"]["taskId"]

while True:
    data = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(5)

if data["status"] == "success":
    with open("vidu-q4.mp4", "wb") as f:
        f.write(requests.get(data["output"][0]["url"], timeout=120).content)
    print("saved vidu-q4.mp4")
else:
    print(data.get("error"))

Video jobs usually take tens of seconds to a few minutes. A 5-second poll interval is fine; cap the wait at 10–15 minutes.

First frame, aspect ratio, audio, resolution and duration

The first frame sets the aspect ratio. There is no aspect_ratio field; the output inherits the frame's proportions anywhere from 1:4 to 4:1. For a vertical clip, crop the first frame to 9:16 before uploading. A 4:7 source returns a 4:7 video.

Audio is part of the default output. This barista clip is 5 seconds at 720p; the prompt names the cafe murmur and the espresso machine hiss:

The barista sets the milk pitcher down on the counter, the latte art in the cup settles into a leaf pattern and steam rises from it; she lifts her eyes to the camera and smiles. Cafe murmur and the hiss of the espresso machine. Slow handheld push-in, warm morning light through the window.

Generate with this prompt → The prompt is pre-filled; upload the vertical first frame and keep 720p.

Set audio to false for a silent file at the same price. Do that when you plan to score the clip yourself.

Choose resolution by stage. Explore at 540p or 720p, then render the final at 2K or 4K. 4K is $0.446 per second, about 8.7 times the 540p rate. A 16-second 4K clip is $7.136; the same 16 seconds at 720p is $1.744. $10 covers roughly 38 five-second 540p clips, 18 at 720p, or 4 at 4K.

Duration is billed in whole seconds. duration accepts integers from 3 to 16 and defaults to 5. The bill is submitted integer seconds × the per-second rate; there is no rounding to another tier.

Three things to handle before launch

Callback plus polling as a fallback. Put "callback": {"url": "https://yourapp.com/hook", "when": "final"} at the top level. Both success and failure notify at the terminal state. Deliveries can repeat, so deduplicate by taskId and keep a scheduled lookup as backup.
Do not re-POST on a timeout. Every submission creates a new task and bill. Store the taskId and query the same one after a network error.
Write duration and resolution explicitly. The defaults are 5 seconds and 720p; leave them out and the job runs and bills at those values. Do not send aspect_ratio or reference_image_urls to this mode; both belong to other schemas and return a 400.
Copy the output promptly. The url in output carries an expireAt timestamp. Move the file into your own storage on receipt.

FAQ

Can I send a first frame and a last frame? No. This mode takes one image_url. For blending several reference images, use the reference-to-video model in the same family.

Can I choose 16:9 or 9:16? No. The output follows the first frame. Crop the frame to the target ratio before uploading.

Is a silent clip cheaper? No. audio does not affect billing, so a silent render costs the same as one with sound.

How is one clip priced? Submitted integer seconds × the resolution rate. Five seconds at 720p is $0.545; ten seconds at 1080p is $1.375; sixteen seconds at 4K is $7.136.

Make your first clip

Copy the seaplane prompt, open the Vidu Q4 Preview image-to-video model page, upload a first frame, and run 5 seconds at 720p for $0.545. When the motion looks right, switch resolution to 2k or 4k for the final. The full field list is in the API documentation.