Vidu Q4 Preview 图生视频 API 怎么用

TL;DR

它是什么：Vidu Q4 Preview 图生视频已在 HiAPI 上线，打开模型页上传一张首帧、写一句动作，就能得到 3–16 秒、最高 4K 的成片，原生音频默认开启。新用户注册送 200 积分。
多少钱：按提交的整数秒 × 所选分辨率单价计费，540p $0.0515/秒、720p $0.109/秒、1080p $0.1375/秒、2K $0.2175/秒、4K $0.446/秒。5 秒 720p 是 $0.545，5 秒 4K 是 $2.23，audio 开关不参与计价。
最快怎么调：模型页传首帧、选 720p 和 5 秒直接跑；接进产品走 POST https://api.hiapi.ai/v1/tasks，model 填 vidu-q4-preview/image-to-video。

Vidu Q4 Preview 是什么？比 Q3 Mix 多了什么

它的输入只有一张首帧。构图、机位、光线和画幅都由这张图定下来，模型负责往后补动作、镜头运动和声音，输出一条 MP4。

和 Q3 Mix 的参考生视频相比，Q4 的图生视频有三个实在的变化：

一张首帧跑到 3–16 秒。 不用准备多张参考图，单张图就能撑完整条镜头；时长按整数秒填写，默认 5 秒。
最高 4K。 540p、720p、1080p、2K、4K 五档可选，Q3 Mix 的参考生视频上限是 1080P，Q4 把图生视频推到了 4K。
原生音频默认开。 audio 默认 true，提示词里写的环境声、对白和音效会一起生成；设成 false 才输出无声视频，价格不变。
参数面很窄。 只有 image_url、prompt、duration、resolution、audio 五个字段。没有 aspect_ratio，传了会返回 400；画幅只跟首帧走。

下面这条水上飞机就是单张首帧跑出来的 5 秒 720p 成片，镜头推近、螺旋桨起转和水面涟漪都在提示词里：

飞行员挥手，水上飞机引擎点着、螺旋桨转起来，水面泛起涟漪，镜头缓慢推进，金色晨光。

用这个提示词生成 → 链接只预填文字提示词，打开后还要自己上传首帧，并把分辨率设为 720p、时长设为 5 秒。

在线试用：5 步出第一条

打开 Vidu Q4 Preview 图生视频模型页，登录后新账号有 200 积分。
上传首帧，支持 JPG/JPEG/PNG/WEBP，单张不超过 50MB。想清楚这一帧是不是你想要的第 0 秒。
在提示词框里只写要新增的动作、镜头和声音，不用重复描述画面里已经有的东西。
时长选 3–16 的整数秒，先用 5；分辨率先选 720p。音频保持开启。
提交，成片出来后直接下载，再决定要不要用高分辨率重跑。

200 积分约合 $0.10，不够一条 3 秒 540p 的成片，建议先充 $10 跑第一档。

API 接入：4 步跑通

在控制台创建 API Key。
POST https://api.hiapi.ai/v1/tasks，model 写 vidu-q4-preview/image-to-video，字段放进 input。
拿到 taskId 后轮询 GET /v1/tasks/{taskId}，或在请求体顶层配置 callback。
status 变成 success 后，从 output[0].url 下载 MP4。

可运行的 curl

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": "飞行员挥手，水上飞机引擎点着、螺旋桨转起来，水面泛起涟漪，镜头缓慢推进，金色晨光。",
      "duration": 5,
      "resolution": "720p",
      "audio": true
    }
  }'

任务 ID 在 data.taskId 里，查询时带上同一个 Bearer Key：

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

data.status 会经过 queued、handling、archiving、success 或 fail。archiving 还在处理，不是失败。

Python 版：创建、轮询、下载

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": "飞行员挥手，水上飞机引擎点着、螺旋桨转起来，水面泛起涟漪，镜头缓慢推进，金色晨光。",
        "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"))

视频任务通常要几十秒到几分钟，5 秒的轮询间隔足够，超时上限建议放在 10–15 分钟。

首帧、画幅、音频、分辨率怎么配

首帧决定画幅。 没有 aspect_ratio 这个字段，成片比例完全沿用首帧，宽高比范围 1:4–4:1。要做竖版就先把首帧裁成 9:16 再上传；传一张 4:7 的竖图，成片也会是 4:7。

音频默认就有。 咖啡师这条 5 秒 720p 成片的提示词里写了咖啡馆低语和咖啡机蒸汽声，音频会一起生成：

咖啡师放下奶缸，杯中拉花定型成叶形，热气升起；她抬头看向镜头微笑。背景是咖啡馆的低语与咖啡机蒸汽声。缓慢手持推近，温暖晨光透过窗户。

用这个提示词生成 → 打开后同样要上传这张竖版首帧，分辨率选 720p。

把 audio 设成 false 就是无声视频，价格不变。需要纯画面、后期单独配乐时再关。

分辨率按阶段选。 试方向用 540p 或 720p，定稿再上 2K / 4K。4K 每秒 $0.446，约为 540p 的 8.7 倍；一条 16 秒 4K 是 $7.136，同样 16 秒 720p 是 $1.744。$10 大约能跑 38 条 5 秒 540p、18 条 5 秒 720p、4 条 5 秒 4K。

时长按整数秒算钱。 duration 只接受 3–16 的整数，默认 5；账单按你提交的整数秒乘以每秒单价。16 秒就是 16 秒的钱，不会向上取整到别的档位。

上线前注意 3 件事

回调加轮询兜底。 请求体顶层加 "callback": {"url": "https://yourapp.com/hook", "when": "final"}，成功和失败都会通知；回调可能重复投递，按 taskId 去重，并保留一个定时查询做补偿。
超时不要重新 POST。 每次提交都会新建任务并按秒计费。把 taskId 存下来，网络抖动时查同一个 ID，而不是再发一次。
显式写 duration 和 resolution。 默认值是 5 秒和 720p；不写就会按默认值出片计费。图生视频不要带 aspect_ratio 或 reference_image_urls，这两个字段属于别的模式，传了直接 400。
产物链接会过期。 output 里的 url 带 expireAt，拿到就转存到自己的存储。