Vidu Q3 Ad 参考生视频 API

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

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

模型概览

模型	vidu-q3-ad/reference-to-video
能力	参考图一致性生成（广告向）
分辨率	720P / 1080P
时长	3-15 秒

面向商品广告的参考生视频：商品图生成 3-15 秒、720P 或 1080P 的广告镜头，运镜、切镜和音效直出。

生产建议

调用建议

广告成片短，提示词写清商品是什么、观众看到什么动作、镜头怎么走即可，无需堆砌形容词。
size 一次决定画幅与分辨率档位，10 个取值对应 5 种画幅 × 720P/1080P 两档。
duration 为 3-15 秒；模型可能为保住分镜完整性调整实际时长，预留费用按设定值估，结算以实际秒数为准。
使用 callback.url 接收任务成功或失败通知；查询响应从 data 读取任务对象，callback 正文直接读取任务对象。
产物 URL 有有效期，需要长期保存时请转存到自己的存储。

适用场景

电商与信息流广告

一张商品图批量产出不同运镜与时长的广告版本。

reference_image_urlssize

品牌质感镜头

浅景深、暖中性调色，同一接口出品牌调性素材。

prompt

最短广告位

3 秒下限对应信息流与开屏的常见位置。

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-ad/reference-to-video",
  "input": {
    "prompt": "参考图 1 的钛金属智能手表的商品广告镜头：手表在深色反光台座上缓慢旋转，一道硬边条光自左向右扫过拉丝表壳，镜头保持低角度",
    "reference_image_urls": [
      "https://example.com/watch.png"
    ],
    "size": "1280*720",
    "duration": 5
  }
}'

import requests, json

# 业务参数对象，字段随模型而定（见对应模型页）
payload = json.loads(r'''
{
  "model": "vidu-q3-ad/reference-to-video",
  "input": {
    "prompt": "参考图 1 的钛金属智能手表的商品广告镜头：手表在深色反光台座上缓慢旋转，一道硬边条光自左向右扫过拉丝表壳，镜头保持低角度",
    "reference_image_urls": [
      "https://example.com/watch.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-ad/reference-to-video",
  "input": {
    "prompt": "参考图 1 的钛金属智能手表的商品广告镜头：手表在深色反光台座上缓慢旋转，一道硬边条光自左向右扫过拉丝表壳，镜头保持低角度",
    "reference_image_urls": [
      "https://example.com/watch.png"
    ],
    "size": "1280*720",
    "duration": 5
  }
}),
});
console.log(await resp.json()); // 成功返回 { code, message, data: { taskId } }

model string 必填

模型 ID。

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

input object 必填

参考生视频参数。

prompt string 必填

描述广告内容，并按顺序引用素材，例如「参考图 1 的商品的广告镜头」。支持中英文，最多 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 可选

输出时长，3-15 秒的整数。分镜数量明显多于或少于该值时，模型可能自动调整实际时长以保住故事完整性；计费按实际输出秒数结算。

默认 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。按实际输出秒数结算费用。

常见问题

实际输出时长和设定值不一样，按哪个计费？

按实际输出秒数。文档明确说明：分镜数量明显多于或少于 duration 时，模型可能自动调整时长以保证故事完整性，实际时长可能多于或少于设定值。

和 Vidu Q3 Mix 有什么区别？

参数形状完全一致，区别在时长区间（Ad 为 3-15 秒，Mix 为 1-16 秒）和优化方向：Ad 面向广告场景，加入了营销向的智能切镜、运镜和音效处理，每秒单价也略低。

参考图最多几张？

最多 7 张，格式为 JPEG/JPG/PNG/WEBP，单张不超过 50MB，宽高比 1:4-4:1。广告场景常见做法是一张商品主图加一到两张使用场景图。

audio 和 watermark 会影响价格吗？

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