Vidu

Vidu Q3

vidu-q3-mix/reference-to-video

面向广告与社交短视频的参考图生视频模型，可约束主体外观与构图，适合快速出片与多版本迭代

vidu-q3-ad/reference-to-video vidu-q3-mix/reference-to-video

试用 vidu-q3-mix/reference-to-video

输入

作品灵感

查看全部作品

输出

video

填写参数并生成，结果会显示在这里。

价格

vidu-q3-mix/reference-to-video 每秒

规格	单价
1280*720	$0.1555
1280*960	$0.1555
1280*1280	$0.1555
960*1280	$0.1555
720*1280	$0.1555
1920*1080	$0.1865
1920*1440	$0.1865
1808*1808	$0.1865
1440*1920	$0.1865
1080*1920	$0.1865

定位简介

Vidu Q3 的参考图生视频线路：用 1 至 7 张参考图（人物、物体或风格）约束画面主体，配合提示词生成 1 至 16 秒的短视频，输出支持 720P 与 1080P 两档、五种画幅，可选生成与画面匹配的音频。适合需要在多镜头片段中保持角色或商品外观一致、并快速产出候选版本的开发者，用于广告素材、电商展示与角色短剧等短内容制作。

核心亮点

多图参考约束主体一致性——最多可传入 7 张参考图，并在提示词中以 Image1、Image2 顺序引用，分别约束人物、物品与整体风格。
可选音频与画面同步生成——开启 audio 后生成与画面匹配的声音，关闭时输出静音视频，按需决定是否需要后期配音。
时长与画幅可精细控制——时长 1 至 16 秒连续可调，画幅覆盖 16:9、4:3、1:1、3:4、9:16，竖屏与横屏素材无需二次裁切。
seed 可复现生成结果——固定种子即可对同一提示词与参考图组合重复出片，便于对比调参与版本回归。

能力说明

参考图生视频：以 1 至 7 张 JPG、PNG、WEBP 图片作为外观与构图依据驱动生成，单张最大 50MB，宽高比支持 1:4 至 4:1，便于沿用已有角色设定或商品图。

提示词与图像索引绑定：提示词最长 5000 字符，可同时描述场景、运动、镜头与声音，并按数组顺序通过 Image1、Image2 指定各参考图的作用。

双档分辨率输出：输出尺寸覆盖 720P 与 1080P 两档，每档含五种画幅，可按投放渠道直接选择成片规格。

音频与时长开关：audio 开关决定是否生成匹配声音，duration 在 1 至 16 秒之间取值，适配从短动图到完整短片镜头的不同需求。

水印与种子控制：可选的 AI 生成水印默认关闭，配合 seed 参数固定随机种子，方便批量试片时复现与追溯某个结果。

适用场景

电商与产品团队：多张商品图生成展示短片——以商品多角度图约束外观，产出数秒产品演示片段，用于详情页与投放素材。
广告创意团队：角色设定图驱动分镜——用角色与场景参考图生成 9:16 或 16:9 短镜头，作为提案与 A/B 测试的候选版本。
短剧与动漫创作者：角色一致性片段——固定角色参考图批量生成镜头，拼接成角色驱动的短片段用于概念验证。
需要声音的社交内容制作——开启音频生成带声音的竖屏短片，直接用于社交平台发布前的样片评估。

限制与选型建议

单次生成时长上限为 16 秒，长视频或复杂连续叙事需自行分镜多次生成后剪辑拼接。参考图需为公网可访问的 JPG、PNG、WEBP 文件，分辨率与画幅比例超出 1:4 至 4:1 的素材无法使用。音频开关默认关闭，需要声音时必须显式开启。若需求是单图驱动的常规图生视频，可参考同族其他线路；需要长片或更复杂叙事时，本线路的单片段定位并不合适。

近期更新

查看更新日志 →

模型上新新模型上线：vidu-q3-ad/reference-to-video
模型上新新模型上线：vidu-q3-mix/reference-to-video

提交生成任务

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

请求头

Authorizationstring必填

账号 API Key，所有请求必填。示例：Bearer YOUR_HIAPI_API_KEY。获取 API Key

Content-Typestring可选

请求体固定按 JSON 解析；如携带，仅接受 application/json（可带 charset），其他取值返回 415。示例：application/json。

Idempotency-Keystring可选

幂等键，最长 255 字节。同账户同键的重试只创建一次任务，重放返回首次 taskId。

幂等键

网络超时或客户端自动重试时，同键只创建一次任务、不会重复扣费（幂等范围 = API Key 所属账户）。建议用业务侧唯一标识做键（如 "order-42"）；同键重放返回首次 taskId，键在首次提交 24 小时后过期。详细的场景矩阵见统一异步接口介绍页。

请求体

modelstring必填

当前固定值：vidu-q3-mix/reference-to-video

routestring可选

当前固定值：default

inputobject必填

vidu-q3-mix/reference-to-video 和线路 default 的业务参数对象，见下方参数表。

seedinteger可选min 0max 2147483647

随机种子，用于复现生成结果，取 0 到 2147483647 之间的整数。

sizestring可选默认值: "1280*720"

输出画面尺寸，格式为 WIDTH*HEIGHT，默认 1280*720；分 720P 与 1080P 两档，每档均含多种宽高比，按秒计费的价格随档位不同。

可选项：1280*7201280*9601280*1280960*1280720*12801920*10801920*14401808*1808

显示全部（2 项）

1440*19201080*1920

audioboolean可选默认值: false

是否生成与画面匹配的声音，布尔值，默认 false，即输出无声视频。

promptstring必填minLength 1maxLength 5000

描述场景、运动、镜头与声音的提示词；参考图按数组顺序以 Image1、Image2 等索引在提示词中引用。

durationinteger必填默认值: 5min 1max 16

输出视频时长，单位为秒，取 1 到 16 之间的整数，默认 5。

watermarkboolean可选默认值: false

是否在画面右下角添加 AI 生成水印，布尔值，默认 false。

reference_image_urlsarray必填minItems 1maxItems 7

参考图数组，提供 1 到 7 张参考图（人物、物体或风格），元素为图片 URL，JPG/PNG/WEBP 格式、单张不超过 50MB、宽高比 1:4 至 4:1 且可公开访问。

Array [ string ]

callbackobject可选

终态通知配置；为空则不回调，由调用方自行查询。详见下方回调说明。

回调（Webhook）

创建任务时提供 callback.url，任务终态时 HiAPI 主动 POST 通知你的服务，可免去轮询。回调请求体与任务详情数据结构同构；签名校验、投递重试与幂等说明见统一异步接口介绍页的回调说明。

urlstring必填

callback 存在时必填；任务终态后向该 URL 发起 POST，须为合法 http(s) URL。

whenstring可选默认值: "final"

当前仅支持 final，即 success / fail 均回调。

可选项：final

storagestring可选默认值: "temp"

产物存储档位：temp（默认，保留约 7 天）或 persistent（长期保存，按大小计费）。余额不足或超出存储上限会静默降级为 temp；实际生效档位见任务详情响应。

可选项：temppersistent

请求示例

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "vidu-q3-mix/reference-to-video",
  "input": {
    "size": "1280*720",
    "audio": false,
    "prompt": "…",
    "duration": 5,
    "watermark": false,
    "reference_image_urls": "…"
  }
}'

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-q3-mix/reference-to-video",
    input: {
      "size": "1280*720",
      "audio": false,
      "prompt": "…",
      "duration": 5,
      "watermark": false,
      "reference_image_urls": "…"
    }
  }),
});
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-q3-mix/reference-to-video",
        "input": {
          "size": "1280*720",
          "audio": False,
          "prompt": "…",
          "duration": 5,
          "watermark": False,
          "reference_image_urls": "…"
        }
    },
)
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 https://api.hiapi.ai/v1/tasks/:id

响应字段

taskIdstring必填

任务 ID，前缀固定 tk-hiapi-。

modelstring必填

解析后的模型全名。用 route 参数提交的任务返回 base@线路（如 gpt-image-2/text-to-image@ext）；否则与创建时传入的模型名一致。

routestring可选

仅当任务用显式 route 参数提交时出现，回显提交时的原值。

statusstring必填

任务状态。

状态枚举

queued 已入队，尚未开始。 handling 处理中。 archiving 处理完成，产物准备中。 success 终态：完成，产物可用（返回 output）。 fail 终态：失败（返回 error）。提交后按 status 判断：success 或 fail 为终态，其余为非终态，建议按 1~3 秒间隔轮询直至终态。成功终态后从 output[].url 下载产物，并在 expireAt 前完成下载或转存；需要长期保留时在创建任务时使用 storage: "persistent"。

creatednumber必填

任务创建时间（Unix 秒）。

completednumber必填

进入终态的 Unix 秒；非终态固定为 0。

outputarray可选

仅 status == success 时出现。产物列表，始终为数组，同一任务可能同时返回多个 type（如 video + first_frame）。

Array [ object ]

数组元素

urlstring必填

资源 URL，可直接下载。

typestring必填

当前可能值：video、image、audio、first_frame、last_frame、thumbnail，后续可能会扩展。

expireAtnumber必填

资源可访问截止时间（Unix 秒）；过期前请完成下载或转存。

errorobject可选

仅 status == fail 时出现。

codestring必填

业务错误码。

messagestring必填

错误描述。

响应示例

成功

{
  "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
      }
    ]
  }
}

处理中（非终态）

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

失败

{
  "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"
    }
  }
}