POST /v1/videos 提交一次请求,再轮询 GET /v1/videos/{video_id} 获取成品。本 H3 视频模式自带原生音频,也支持参考图片;图片可单独使用,或与参考视频一起使用。
准备工作
- 在 Viggle 控制台创建 API 密钥,并导出为
VIGGLE_API_KEY。 - 将参考视频保存为运行示例目录下的
reference.mp4。视频长度须为 0.5–600 秒,分辨率至少为 64×64 像素,且宽高均为偶数。 - cURL 示例需要安装
jq;Node 示例需要 Node.js 20+,并保存为.mjs文件;Python 示例需要通过pip install requests安装requests。
prompt 来描述期望的镜头。prompt 与 quality 均为必填;low 适合快速迭代,high 提供更高的保真度。
生成并轮询视频
响应
status 为 ready 时输出 video_url;遇到 failed、cancelled 或轮询超时则停止。若轮询超时,可使用同一 ID 继续调用获取视频。
打开输出的 URL 即可查看或下载视频。签名链接有效期为 1 小时,再次获取视频即可得到新的链接。
使用 URL 或参考图片
- 托管视频: 将
reference_video文件字段替换为reference_video_url,填写可公开访问的视频 URL。文件和 URL 两种方式合计最多提供 1 个参考视频。 - 添加图片: 在视频之外加入
reference_image文件或reference_image_url字段。可重复这些字段,图片总数最多为 4 张。 - 仅使用图片: 省略视频,提供至少 1 张参考图片,并保留
prompt和quality。
必须包含至少一个参考字段;全部省略会进入文本生成视频模式。参考字段不能与首尾帧字段或 Viggle-Animate 的驱动视频、角色图片字段混用。
duration_s 控制生成视频的长度(3–15 秒,默认 5),与参考视频的长度无关。生成费用见计费与保留期限。
从参考视频或图片生成视频
查看全部参数、参考图片示例和校验错误。
使用 Viggle-Animate
将驱动视频的动作应用到角色图片。

