HappyHorse

1. 概述

HappyHorse 是本平台提供的 AI 视频生成模型，支持四种生成模式：

模型名称	能力	说明
`happyhorse-1.0-t2v`	文生视频 (Text-to-Video)	根据文本提示词生成视频
`happyhorse-1.0-i2v`	图生视频 (Image-to-Video)	根据首帧图 + 文本提示词生成视频
`happyhorse-1.0-r2v`	参考图生视频 (Reference-to-Video)	根据 1-9 张参考图 + 文本提示词生成视频
`happyhorse-1.0-video-edit`	视频编辑 (Video Edit)	对输入视频按提示词进行编辑，支持附加 0-5 张参考图

生成任务为异步流程：提交任务 → 拿到 task_id → 轮询查询结果。

2. 接口地址

方法	路径	作用
POST	`/v1/video/generations`	提交视频生成任务
GET	`/v1/video/generations/{task_id}`	查询任务状态 / 获取视频 URL

环境地址：

环境	Base URL
测试环境	`http://116.62.234.39:3000`
生产环境	`https://api.tkhub.ai`

下文示例统一以 $BASE_URL 表示，实际调用请替换为对应环境地址。

3. 认证

所有请求均需携带 API Key：

Authorization: Bearer <YOUR_API_KEY>

4. 提交任务

4.1 请求参数

字段	类型	必填	说明
`model`	string	是	可选值：`happyhorse-1.0-t2v` / `happyhorse-1.0-i2v` / `happyhorse-1.0-r2v` / `happyhorse-1.0-video-edit`
`prompt`	string	T2V / R2V / EDIT 必填；I2V 可选	文本提示词，最大 2500 字符（超长自动截断，不能为纯空格）
`image`	string	I2V 必填	首帧图 URL。R2V / EDIT 场景请使用 `metadata.referenceImageUrls`
`images`	string[]	R2V / EDIT 可选	多图输入数组，与 `metadata.referenceImageUrls` 等价，二选一即可
`aspect_ratio`	string	可选	画面比例（T2V 默认 `16:9`；R2V 可选）：`16:9` / `9:16` / `1:1` / `4:3` / `3:4`
`resolution`	string	可选	分辨率，`1080P` 或 `720P`；默认 `1080P`（EDIT 按输入视频自动适配）
`duration`	int	可选	视频时长（秒），范围 3-15；默认 `5`（EDIT 以输入视频实际时长为准）
`metadata`	object	视情况	扩展参数对象，见 4.2 / 4.4；EDIT 必须通过 `metadata.referenceVideoUrls[0]` 指定输入视频 URL

4.2 metadata 扩展参数

metadata 字段用于传递扩展参数：

字段	类型	默认	说明
`seed`	int	随机	随机数种子，范围 `[0, 2147483647]`，用于控制生成结果的确定性
`watermark`	bool	`true`	是否添加水印
`ratio`	string	-	画面比例，等价于顶层 `aspect_ratio`

4.3 素材要求

I2V 首帧图（image）

像素：宽高均 ≥ 300px，无上限
比例：长宽比介于 1:2.5 ~ 2.5:1
格式：JPEG / JPG / PNG / BMP / WEBP
大小：≤ 10MB

R2V 参考图（metadata.referenceImageUrls 或 images，1-9 张）

数量：1 ≤ N ≤ 9
像素：短边 ≥ 400px
比例：短/长边比 ≥ 0.4
格式：JPEG / JPG / PNG / BMP / WEBP
大小：≤ 10MB / 张

EDIT 输入视频（metadata.referenceVideoUrls[0]，必填）

时长：3 ~ 60 秒
分辨率：480P 及以上
比例：1:8 ~ 8:1
格式：MP4 / MOV
大小：≤ 100MB
帧率：> 8 fps

EDIT 参考图（metadata.referenceImageUrls 或 images，可选 0-5 张）：要求同 R2V 参考图。

4.4 metadata 多媒体字段

本平台所有视频模型采用统一的 metadata 多媒体命名约定。HappyHorse 各模型支持的字段如下：

metadata 字段	类型	适用模型	说明
`first_image`	string	I2V	首帧图 URL，等价于顶层 `image`
`referenceImageUrls`	string[]	R2V / EDIT	参考图 URL 数组；R2V 必填 1-9 张，EDIT 可选 0-5 张
`referenceVideoUrls`	string[]	EDIT（必填）	参考视频 URL 数组，取首个作为输入视频

说明：如需多张参考图场景，请使用 happyhorse-1.0-r2v；如需对已有视频进行编辑，请使用 happyhorse-1.0-video-edit。

5. 请求示例

5.1 文生视频（T2V）

curl -X POST $BASE_URL/v1/video/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-t2v",
    "prompt": "一个小女孩在樱花树下翩翩起舞，阳光穿过花瓣，电影质感",
    "aspect_ratio": "16:9",
    "resolution": "1080P",
    "duration": 5,
    "metadata": {
      "seed": 42,
      "watermark": false
    }
  }'

5.2 图生视频（I2V）

curl -X POST $BASE_URL/v1/video/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-i2v",
    "prompt": "让图片中的场景动起来，镜头缓慢推进",
    "image": "https://example.com/first_frame.png",
    "resolution": "1080P",
    "duration": 5,
    "metadata": {
      "seed": 42
    }
  }'

5.3 参考图生视频（R2V）

curl -X POST $BASE_URL/v1/video/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-r2v",
    "prompt": "将三张人物站在同一个樱花树下合照，镜头缓慢推近",
    "resolution": "1080P",
    "duration": 5,
    "metadata": {
      "referenceImageUrls": [
        "https://example.com/ref1.png",
        "https://example.com/ref2.png",
        "https://example.com/ref3.png"
      ],
      "seed": 42
    }
  }'

5.4 视频编辑（EDIT）

curl -X POST $BASE_URL/v1/video/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-video-edit",
    "prompt": "将视频中的天空改为星空，在左上角加入一轮满月",
    "metadata": {
      "referenceVideoUrls": [
        "https://example.com/input.mp4"
      ],
      "referenceImageUrls": [
        "https://example.com/moon.png"
      ],
      "seed": 42
    }
  }'

5.5 提交响应

{
  "id": "task_01HXXXXXXXXXXXXXXX",
  "task_id": "task_01HXXXXXXXXXXXXXXX",
  "model": "happyhorse-1.0-t2v",
  "status": "queued",
  "created_at": 1761552000
}

请保存 task_id，用于后续查询。

6. 查询任务

6.1 请求

curl -X GET $BASE_URL/v1/video/generations/task_01HXXXXXXXXXXXXXXX \
  -H "Authorization: Bearer $API_KEY"

6.2 成功响应

{
  "id": "task_01HXXXXXXXXXXXXXXX",
  "task_id": "task_01HXXXXXXXXXXXXXXX",
  "model": "happyhorse-1.0-t2v",
  "status": "completed",
  "progress": "100%",
  "created_at": 1761552000,
  "completed_at": 1761552120,
  "metadata": {
    "url": "https://cdn.example.com/videos/xxx.mp4?Expires=..."
  }
}

视频下载地址位于 metadata.url
URL 带有过期时间，建议尽快下载或转存到自有存储

6.3 失败响应

{
  "id": "task_01HXXXXXXXXXXXXXXX",
  "task_id": "task_01HXXXXXXXXXXXXXXX",
  "status": "failed",
  "error": {
    "code": "InvalidParameter",
    "message": "error description"
  }
}

任务失败不会产生任何费用。

7. 任务状态

status	说明	终态
`queued`	已提交，排队中	否
`in_progress`	正在生成	否
`completed`	生成完成，可从 `metadata.url` 下载视频	是
`failed`	生成失败（见 `error` 字段）	是

建议轮询策略：

间隔 ≥ 10 秒
超时建议 ≥ 5 分钟
命中终态（completed / failed）后停止轮询

8. 错误码

HTTP	code	说明
400	`InvalidParameter`	请求参数错误（如 prompt 为空、图片格式不支持）
401	`Unauthorized`	API Key 无效或未提供
403	`Forbidden`	无权限调用该模型
429	`RateLimitExceeded`	触发频率限制
500	`InternalError`	服务内部错误
503	`ServiceUnavailable`	服务暂不可用，建议稍后重试

9. 计费说明

计费单位：按次（每个成功任务计费一次）
影响因素：duration（时长）× resolution（分辨率）
任务失败或取消不计费
具体价格请查看平台「模型价格」页面

10. 常见问题

Q1：I2V 提示 “image is required” 怎么办？ A：调用 happyhorse-1.0-i2v 必须提供 image 字段（或等价的 metadata.first_image）。 Q2：视频下载链接什么时候过期？ A：链接通常有若干小时的有效期。建议在获取到 completed 状态后立即下载，或转存到自有存储。 Q3：能否取消正在进行的任务？ A：当前不支持取消，任务一旦提交将执行至完成或失败。 Q4：可以通过 metadata 传任意字段吗？ A：可以，未识别的字段会被忽略，不会影响调用，但不允许通过 metadata 覆写 model。 Q4+：如何传入多张参考图或对已有视频做编辑？ A：多张参考图请使用 happyhorse-1.0-r2v，通过 metadata.referenceImageUrls 或顶层 images 传入 1-9 张；基于视频编辑请使用 happyhorse-1.0-video-edit，通过 metadata.referenceVideoUrls[0] 指定输入视频，metadata.referenceImageUrls 可选传 0-5 张附加参考图。 Q5：prompt 支持哪些语言？ A：支持中英文。中文在场景描写上效果更佳。 Q6：生成视频的默认时长是多久？ A：未指定 duration 时默认 5 秒，最长可指定 15 秒。

11. 快速接入清单

获取 API Key
准备调用环境，确认可访问测试或生产环境 Base URL
选择模型：T2V / I2V / R2V / EDIT
R2V / EDIT 通过 metadata.referenceImageUrls / metadata.referenceVideoUrls 传入多媒体素材
提交任务，保存 task_id
按 10 秒间隔轮询查询
在 status = completed 时从 metadata.url 下载视频

概览

标准接口

特殊接口

帮助中心

隐私条款

1. 概述

2. 接口地址

3. 认证

4. 提交任务

4.1 请求参数

4.2 metadata 扩展参数

4.3 素材要求

4.4 metadata 多媒体字段

5. 请求示例

5.1 文生视频（T2V）

5.2 图生视频（I2V）

5.3 参考图生视频（R2V）

5.4 视频编辑（EDIT）

5.5 提交响应

6. 查询任务

6.1 请求

6.2 成功响应

6.3 失败响应

7. 任务状态

8. 错误码

9. 计费说明

10. 常见问题

11. 快速接入清单

概览

标准接口

特殊接口

帮助中心

隐私条款

Documentation Index

​1. 概述

​2. 接口地址

​3. 认证

​4. 提交任务

​4.1 请求参数

​4.2 metadata 扩展参数

​4.3 素材要求

​4.4 metadata 多媒体字段

​5. 请求示例

​5.1 文生视频（T2V）

​5.2 图生视频（I2V）

​5.3 参考图生视频（R2V）

​5.4 视频编辑（EDIT）

​5.5 提交响应

​6. 查询任务

​6.1 请求

​6.2 成功响应

​6.3 失败响应

​7. 任务状态

​8. 错误码

​9. 计费说明

​10. 常见问题

​11. 快速接入清单

1. 概述

2. 接口地址

3. 认证

4. 提交任务

4.1 请求参数

4.2 metadata 扩展参数

4.3 素材要求

4.4 metadata 多媒体字段

5. 请求示例

5.1 文生视频（T2V）

5.2 图生视频（I2V）

5.3 参考图生视频（R2V）

5.4 视频编辑（EDIT）

5.5 提交响应

6. 查询任务

6.1 请求

6.2 成功响应

6.3 失败响应

7. 任务状态

8. 错误码

9. 计费说明

10. 常见问题

11. 快速接入清单