HappyHorse Video

HappyHorse Video 使用异步视频任务接口。客户端先创建任务，再通过任务查询接口轮询状态和结果。

接口地址

能力	方法	路径
创建视频任务	POST	/v1/video/generations
查询视频任务	GET	/v1/video/generations/{task_id}

请求需要携带 API Key：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

支持模型

模型	场景	素材要求
happyhorse-1.0-t2v	文生视频	只需要 prompt
happyhorse-1.0-i2v	图生视频	需要一张首帧图片
happyhorse-1.0-r2v	参考图生成视频	需要一张或多张参考图片
happyhorse-1.0-video-edit	视频编辑	需要源视频 URL

请求参数

参数	类型	必填	说明
model	string	是	HappyHorse 模型名称
prompt	string	是	视频生成或编辑描述
duration	number	否	视频时长，单位秒；不传时默认 5
seconds	string	否	视频时长字符串；与 duration 二选一即可
size	string	否	可用尺寸或画幅，例如 1920x1080、1080x1920、1:1、16:9
image	string	否	单张图片 URL，常用于图生视频或参考图
images	string[]	否	多张图片 URL，常用于参考图生成或视频编辑辅助素材
input_reference	string	否	参考素材 URL；可以是图片，也可以是视频
metadata	object	否	HappyHorse 扩展参数

metadata 字段

字段	类型	说明
resolution	string	输出清晰度，可传 720P 或 1080P
ratio	string	输出画幅，例如 16:9、9:16、1:1、4:3、3:4
watermark	boolean	是否添加水印
seed	number	随机种子
audio_setting	string	音频设置，例如 origin
image_url	string	单张图片 URL
image_urls	string[]	多张图片 URL
video_url	string	源视频 URL，视频编辑时使用
video_urls	string[]	源视频 URL 数组，默认使用第一条
media	object[]	直接指定素材列表，适合高级场景

media 项支持：

{
  "type": "first_frame",
  "url": "https://example.com/first-frame.png"
}

常用 type：

type	说明
first_frame	首帧图片
reference_image	参考图片
video	源视频

文生视频

curl -X POST https://cubicspaces.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "happyhorse-1.0-t2v",
    "prompt": "A cinematic aerial shot of a futuristic cubic city at sunrise, slow camera push-in, realistic lighting",
    "duration": 5,
    "size": "1920x1080",
    "metadata": {
      "resolution": "1080P",
      "ratio": "16:9",
      "watermark": false
    }
  }'

图生视频

curl -X POST https://cubicspaces.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "happyhorse-1.0-i2v",
    "prompt": "Animate the product from the first frame with a slow clockwise rotation, keep the original composition and product shape stable",
    "image": "https://example.com/first-frame.png",
    "duration": 5,
    "metadata": {
      "resolution": "1080P",
      "watermark": false
    }
  }'

也可以使用：

{
  "input_reference": "https://example.com/first-frame.png"
}

或：

{
  "metadata": {
    "image_url": "https://example.com/first-frame.png"
  }
}

参考图生成视频

curl -X POST https://cubicspaces.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "happyhorse-1.0-r2v",
    "prompt": "Use the reference images to generate a short product showcase video, maintain the product identity and lighting consistency",
    "images": [
      "https://example.com/ref-1.png",
      "https://example.com/ref-2.png"
    ],
    "duration": 6,
    "metadata": {
      "resolution": "1080P",
      "ratio": "16:9",
      "watermark": false
    }
  }'

视频编辑

curl -X POST https://cubicspaces.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "happyhorse-1.0-video-edit",
    "prompt": "Replace the background with a clean studio scene while preserving the person, motion path, and timing of the source video",
    "metadata": {
      "video_url": "https://example.com/source.mp4",
      "resolution": "720P",
      "watermark": false
    }
  }'

源视频也可以放在 input_reference：

{
  "input_reference": "https://example.com/source.mp4"
}

创建任务返回

创建成功后会返回视频任务对象：

{
  "id": "video_xxx",
  "task_id": "video_xxx",
  "object": "video",
  "model": "happyhorse-1.0-t2v",
  "status": "queued",
  "progress": 0,
  "created_at": 1770000000
}

id 和 task_id 都可用于后续查询。

查询任务

curl https://cubicspaces.cloud/v1/video/generations/video_xxx \
  -H "Authorization: Bearer YOUR_API_KEY"

查询返回

{
  "id": "video_xxx",
  "task_id": "video_xxx",
  "object": "video",
  "model": "happyhorse-1.0-t2v",
  "status": "completed",
  "progress": 100,
  "created_at": 1770000000,
  "completed_at": 1770000120,
  "metadata": {
    "url": "https://example.com/output.mp4"
  }
}

状态值

status	说明
queued	已排队
in_progress	生成中
completed	已完成
failed	失败

完成后从 metadata.url 读取视频地址。