跳转到内容
HiAPI Docs
HiAPI
在线试用 获取 API Key
中文
English 中文

HappyHorse 1.1 R2V API

POST /v1/tasks

所有模型都通过 统一异步接口 POST /v1/tasks 调用，区别只在 input 字段（见下方 input 参数）。

模型概览

模型名称 happyhorse-1.1/reference-to-video
类型 视频生成（参考生视频）
接口 POST /v1/tasks
价格 见 HiAPI 定价

HappyHorse 1.1 参考生视频 API，阿里巴巴出品。用最多 9 张参考图生成短视频，在提示词中以 [Image 1]、[Image 2] 引用对应参考图，保持主体、场景与风格的跨镜头一致性，自带原生音频。

生产建议

生产环境建议
  • 生产环境建议在请求体顶层传 callback.url，让 HiAPI 在任务进入终态时主动通知你的服务，减少无效轮询。
  • GET /v1/tasks/:id 更适合本地调试、低频任务，或作为回调失败后的补偿查询。
  • callback.when 当前建议固定为 final；success 和 fail 都可能触发终态通知，你的服务端需要按 taskId 做幂等处理。

适用场景

多参考图精准控制

最多 9 张参考图，精准控制主体、服化道与风格。

reference_image
提示词指定引用对象

用 [Image N] 在提示词中点名某张参考图，组合出新场景。

promptreference_image
跨镜头一致性

保持角色与风格在多镜头中稳定，适合系列短片与连续叙事。

reference_image
横竖屏多比例

9 种画面比例，一套素材适配横屏与竖屏投放。

aspect_ratio

请求参数

model string 必填

固定填 happyhorse-1.1/reference-to-video。

示例 happyhorse-1.1/reference-to-video
input object 必填

业务参数对象；HappyHorse 1.1 R2V 的模型专属配置都放在这里。

prompt string 必填

文本提示词。在提示词中用 [Image 1]、[Image 2] 按 reference_image 的顺序引用对应参考图。

reference_image string[] 必填

1-9 张参考图 URL。JPEG/PNG/WEBP，短边 ≥ 400px，单张 ≤ 20MB。

resolution enum 可选

输出视频分辨率，分辨率越高价格越高。

默认 1080p 可选值: 720p1080p
aspect_ratio enum 可选

输出视频的画面比例。

默认 16:9 可选值: 16:99:163:44:34:55:41:19:2121:9
duration integer 可选

视频时长（秒），范围 3-15，价格随时长增加。

默认 5
callback object 可选

可选回调配置；设置后任务进入终态时 HiAPI 会主动通知你的服务，减少轮询。

url string 必填

传入 callback 时必填；接收任务终态通知的 HTTPS 地址。

示例 https://your-domain.com/hiapi/callback
when enum 可选

回调触发时机；当前建议固定为 final。

默认 final 可选值: final

用例示例

角色入场景

1080p / 16:9 / 5 秒，2 张参考图，电影感运镜。

请求体
{
  "model": "happyhorse-1.1/reference-to-video",
  "input": {
    "prompt": "[Image 1] 中的角色走在 [Image 2] 的场景风格里，电影感运镜",
    "reference_image": [
      "https://static.hiapi.ai/example/ref-1.jpg",
      "https://static.hiapi.ai/example/ref-2.jpg"
    ],
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
}
保持人物造型

720p / 9:16 / 5 秒，竖屏，成本更省。

请求体
{
  "model": "happyhorse-1.1/reference-to-video",
  "input": {
    "prompt": "保持 [Image 1] 的人物造型，在 [Image 2] 的氛围中缓步前行",
    "reference_image": [
      "https://static.hiapi.ai/example/char.jpg",
      "https://static.hiapi.ai/example/mood.jpg"
    ],
    "resolution": "720p",
    "aspect_ratio": "9:16",
    "duration": 5
  }
}
主体风格融合

1080p / 16:9 / 8 秒，更长时长，连贯短片。

请求体
{
  "model": "happyhorse-1.1/reference-to-video",
  "input": {
    "prompt": "融合 [Image 1] 主体与 [Image 2] 风格，生成连贯短片",
    "reference_image": [
      "https://static.hiapi.ai/example/subject.jpg",
      "https://static.hiapi.ai/example/style.jpg"
    ],
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8
  }
}

获取结果

  1. 提交成功后立即返回 taskId（不等待生成完成）。
  2. 生产环境优先等待 callback.url 收到终态通知；本地调试时可轮询 GET /v1/tasks/:id。
  3. status=success 后，从返回的 output[].url 下载生成的视频。
  4. 如果 status=fail，按返回的错误信息修正请求，不要盲目重试同一个无效请求。

常见问题

参考生视频最多支持几张参考图？

reference_image 支持 1-9 张参考图（JPEG/PNG/WEBP，短边 ≥ 400px，≤ 20MB）。在 prompt 中用 [Image 1]…[Image N] 引用对应参考图。

怎么在提示词里引用参考图？

在 prompt 里用 [Image 1]、[Image 2] 等标记，序号对应 reference_image 数组的顺序，模型据此把对应参考图用进画面。

支持哪些分辨率和时长？

分辨率 720p / 1080p，时长 3-15 秒（默认 5 秒）。按分辨率与时长（按秒）计费，1080p 单价高于 720p，实时价格见价格页。 查看价格

和图生视频有什么区别？

图生视频只用 1 张首帧图片驱动；参考生视频用最多 9 张参考图做主体与风格控制，更适合多主体组合和系列一致性。纯文本生成请用 happyhorse-1.1/text-to-video。

下一步