> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tkhub.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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：

```text theme={null}
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）

```bash theme={null}
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）

```bash theme={null}
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）

```bash theme={null}
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）

```bash theme={null}
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 提交响应

```json theme={null}
{
  "id": "task_01HXXXXXXXXXXXXXXX",
  "task_id": "task_01HXXXXXXXXXXXXXXX",
  "model": "happyhorse-1.0-t2v",
  "status": "queued",
  "created_at": 1761552000
}
```

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

***

## 6. 查询任务

### 6.1 请求

```bash theme={null}
curl -X GET $BASE_URL/v1/video/generations/task_01HXXXXXXXXXXXXXXX \
  -H "Authorization: Bearer $API_KEY"
```

### 6.2 成功响应

```json theme={null}
{
  "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 失败响应

```json theme={null}
{
  "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` 下载视频