Vidu Q3 Mix 参考生视频 API

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

图片、视频和音频模型通过统一异步接口 POST /v1/tasks 调用，区别只在 input 字段（见下方 input 参数）。

模型概览

模型	vidu-q3-mix/reference-to-video
能力	参考图一致性生成（通用场景）
分辨率	720P / 1080P
时长	1-16 秒

1-7 张参考图锁定人物、商品和场景，生成 1-16 秒、720P 或 1080P 的视频，10 种画幅尺寸可选。

生产建议

调用建议

提示词按顺序引用素材：参考图 1、参考图 2……编号与 reference_image_urls 数组下标一一对应。
size 一次决定画幅与分辨率档位，10 个取值对应 5 种画幅 × 720P/1080P 两档；1:1 在 1080P 档下是 1808*1808。
先用 720P 打磨动作与构图，定稿再跑 1080P，可以省下不少费用。
使用 callback.url 接收任务成功或失败通知；查询响应从 data 读取任务对象，callback 正文直接读取任务对象。
产物 URL 有有效期，需要长期保存时请转存到自己的存储。

适用场景

多素材一致性

人物、场景、道具分别给参考图，合进同一个镜头。

reference_image_urls

原生竖屏短片

选 720*1280 直接输出竖屏，不靠裁切。

size

长一点的参考生视频

时长可到 16 秒，比多数同类接口更长。

duration

请求参数

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

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
# 把 YOUR_API_KEY 换成你的账号 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-q3-mix/reference-to-video",
  "input": {
    "prompt": "参考图 1 的毛毡猫头鹰玩偶停落在参考图 2 旧书店的木桌上，歪头眨眼，镜头缓慢推过书架",
    "reference_image_urls": [
      "https://example.com/owl.png",
      "https://example.com/bookshop.png"
    ],
    "size": "1280*720",
    "duration": 5
  }
}'

import requests, json

# 业务参数对象，字段随模型而定（见对应模型页）
payload = json.loads(r'''
{
  "model": "vidu-q3-mix/reference-to-video",
  "input": {
    "prompt": "参考图 1 的毛毡猫头鹰玩偶停落在参考图 2 旧书店的木桌上，歪头眨眼，镜头缓慢推过书架",
    "reference_image_urls": [
      "https://example.com/owl.png",
      "https://example.com/bookshop.png"
    ],
    "size": "1280*720",
    "duration": 5
  }
}
''')

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # 成功返回 { code, message, data: { taskId } }

// 提交异步任务，成功立即返回 taskId（不等待生成完成）
// 把 YOUR_API_KEY 换成你的账号 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-q3-mix/reference-to-video",
  "input": {
    "prompt": "参考图 1 的毛毡猫头鹰玩偶停落在参考图 2 旧书店的木桌上，歪头眨眼，镜头缓慢推过书架",
    "reference_image_urls": [
      "https://example.com/owl.png",
      "https://example.com/bookshop.png"
    ],
    "size": "1280*720",
    "duration": 5
  }
}),
});
console.log(await resp.json()); // 成功返回 { code, message, data: { taskId } }

model string 必填

模型 ID。

示例 vidu-q3-mix/reference-to-video

input object 必填

参考生视频参数。

prompt string 必填

描述视频内容，并按顺序引用素材，例如「参考图 1 的角色走进参考图 2 的场景」。支持中英文，最多 5000 字符。

reference_image_urls string[] 必填

参考图片 URL 数组，1-7 张，保持人物、商品和场景一致。JPEG/JPG/PNG/WEBP，单张不超过 50MB，宽高比 1:4-4:1，须为公网可访问的 HTTP(S) URL。

size enum 可选

输出画幅与分辨率档位，格式为「宽*高」。720P 档与 1080P 档各含 16:9、4:3、1:1、3:4、9:16 五种画幅，共 10 个取值；画幅由尺寸本身确定，无需另传比例参数。

默认 1280*720 可选值: 1280*7201280*9601280*1280960*1280720*12801920*10801920*14401808*18081440*19201080*1920

duration integer 可选

输出时长，1-16 秒的整数。

默认 5

audio boolean 可选

是否生成与画面匹配的背景音乐和音效。默认关闭，输出无声视频；不参与计价。

默认 false

watermark boolean 可选

是否添加水印。默认关闭；开启后在右下角标注「内容由 AI 生成」。

默认 false

seed integer 可选

随机数种子，0-2147483647。固定后同一组输入的结果更接近，但不保证完全一致。

callback object 可选

任务完成或失败后发送通知；查询响应从 data 读取任务对象，回调正文直接读取任务对象。

url string 必填

接收任务完成或失败通知的 HTTPS 地址。

示例 https://your-domain.com/hiapi/callback

when enum 可选

任务完成或失败时触发。

默认 final 可选值: final

获取结果

创建任务响应从 data.taskId 读取任务 ID。
等待 callback，或调用 GET /v1/tasks/:id 查询状态；轮询响应从 data 读取任务对象。
status=success 时，从 output 中读取 type=video 的视频 URL；callback body 直接读取 output。按实际输出秒数结算费用。

常见问题

参考图最多几张？

最多 7 张。提示词按顺序引用：参考图 1、参考图 2……编号与 reference_image_urls 数组顺序一致。

为什么只能选固定尺寸？

接口只接受 10 个枚举值：16:9、4:3、1:1、3:4、9:16 五种画幅各有 720P 与 1080P 两档。好处是画幅和分辨率一次选定，不用另传比例参数。

audio 和 watermark 会影响价格吗？

不影响。价格只由分辨率档位和实际输出秒数决定，两个开关都不参与计价。

和 Vidu Q4 Preview 参考生视频有什么区别？

Q4 Preview 支持参考音频锁定音色、参考图最多 15 张，分辨率和画幅是两个独立参数；Q3 Mix 只做图像参考，画幅与分辨率在 size 里一次选定，时长下限到 1 秒。