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

HappyHorse 1.1 I2V API

POST /v1/tasks

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

模型概览

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

HappyHorse 1.1 图生视频 API，阿里巴巴出品。以一张首帧图片驱动生成短视频，尽量保持主体、风格与场景一致，自带原生音频，支持 720p / 1080p 与 3-15 秒时长。

生产建议

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

适用场景

首帧图驱动短片

用一张图片作为首帧生成视频，保留主体身份与画面风格。

image_urls
提示词引导运动

可选 prompt 控制镜头运动与风格走向，让画面动起来更可控。

image_urlsprompt
静图转动态

把海报、插画、产品图变成带原生音频的短视频，适合电商和社媒。

image_urls
按需选清晰度

720p / 1080p 两档，按预算与时长选档（按秒计费）。

resolutionduration

请求参数

model string 必填

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

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

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

image_urls string[] 必填

首帧图片 URL（仅 1 张）。JPEG/PNG/WEBP，短边 ≥ 300px，单张 ≤ 20MB。

prompt string 可选

可选文本提示词，用于引导生成视频的运动与风格。

resolution enum 可选

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

默认 1080p 可选值: 720p1080p
duration integer 可选

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

默认 5
callback object 可选

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

url string 必填

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

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

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

默认 final 可选值: final

用例示例

首帧缓慢推进

1080p / 5 秒，以上传图片为首帧，轻微运动。

请求体
{
  "model": "happyhorse-1.1/image-to-video",
  "input": {
    "image_urls": [
      "https://static.hiapi.ai/example/first-frame.jpg"
    ],
    "prompt": "以上传图片为首帧，缓慢推进镜头，轻微风吹动效果",
    "resolution": "1080p",
    "duration": 5
  }
}
主体自然转动

720p / 5 秒，成本更省，柔和光线。

请求体
{
  "model": "happyhorse-1.1/image-to-video",
  "input": {
    "image_urls": [
      "https://static.hiapi.ai/example/portrait.jpg"
    ],
    "prompt": "让画面主体自然转动，背景轻微虚化，柔和光线",
    "resolution": "720p",
    "duration": 5
  }
}
静态风景动态化

1080p / 8 秒，云层流动与光影变化，电影感。

请求体
{
  "model": "happyhorse-1.1/image-to-video",
  "input": {
    "image_urls": [
      "https://static.hiapi.ai/example/landscape.jpg"
    ],
    "prompt": "为静态风景加入云层流动与光影变化，电影感",
    "resolution": "1080p",
    "duration": 8
  }
}

获取结果

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

常见问题

图生视频需要传几张图片？

image_urls 只接受 1 张首帧图片（JPEG/PNG/WEBP，短边 ≥ 300px，≤ 20MB）。视频从这张首帧出发生成。

支持哪些分辨率和时长？

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

生成的视频带声音吗？

HappyHorse 1.1 自带原生音频，无需额外配置，生成画面的同时输出同步音频。

和文生视频、参考生视频有什么区别？

图生视频从一张首帧图片驱动；纯文本生成请用 happyhorse-1.1/text-to-video；需要最多 9 张参考图精准控制主体与风格请用 happyhorse-1.1/reference-to-video。

下一步