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

# HappyHorse 视频 API 文档

> 查看 HappyHorse 视频 API 文档，包含文生视频、图生视频、参考生视频、视频编辑与任务查询接口，适合 AI 视频应用接入。

# HappyHorse 视频 API

这里是 **HappyHorse 视频 API** 总览页，你可以在这里快速了解 HappyHorse 提供的多种视频生成与编辑能力，并进入具体接口文档。

## HappyHorse 视频 API 可以做什么

HappyHorse 提供多种视频生成和编辑能力，满足不同场景需求：

* **文生视频**：通过文本提示词直接生成高质量视频
* **图生视频（基于首帧）**：基于单张首帧图像生成视频
* **参考生视频**：基于多张参考图像（1-9 张）生成视频，支持通过 character 标识引用不同角色
* **视频编辑**：基于现有视频和参考图像进行编辑，支持风格转换、局部替换等
* **任务查询**：查询异步视频生成任务的状态和结果

## 常用 HappyHorse 视频 API 接口

| 使用场景   | 接口                                                              | 说明            |
| :----- | :-------------------------------------------------------------- | :------------ |
| 文生视频   | [Generations API](/api/cn/happyhorse/generations)               | 基于文本提示词生成视频   |
| 图生视频   | [Image-to-Video API](/api/cn/happyhorse/image-to-video)         | 基于首帧图像生成视频    |
| 参考生视频  | [Reference-to-Video API](/api/cn/happyhorse/reference-to-video) | 基于多张参考图像生成视频  |
| 视频编辑   | [Video Edit API](/api/cn/happyhorse/video-edit)                 | 基于视频和参考图像进行编辑 |
| 查询任务结果 | [Fetch API](/api/cn/happyhorse/fetch)                           | 查询异步任务状态和结果   |

## 推荐接入流程

### 文生视频 / 图生视频 / 参考生视频 / 视频编辑

1. 根据需求选择合适的生成接口（文生视频、图生视频、参考生视频或视频编辑）
2. 调用对应的生成接口提交任务，获取 `task_id`
3. 使用 [Fetch API](/api/cn/happyhorse/fetch) 轮询查询任务状态
4. 当 `task_status` 为 `SUCCEEDED` 时，从返回结果中获取视频 URL

### 任务状态说明

* `PENDING`：任务排队中
* `RUNNING`：任务处理中
* `SUCCEEDED`：任务执行成功
* `FAILED`：任务执行失败
* `CANCELED`：任务已取消
* `UNKNOWN`：任务不存在或状态未知

## 为什么用 HappyHorse 视频 API

* **多种生成模式**：支持文生视频、图生视频、参考生视频、视频编辑等多种能力
* **高质量输出**：支持 720P/1080P 分辨率，多种宽高比选择
* **灵活控制**：支持时长控制、种子设置、水印开关等参数
* **统一网关**：使用统一的 API 网关和鉴权机制
* **完整生命周期**：提供完整的任务提交、查询、结果获取流程

## HappyHorse 视频 API 常见问题

### 哪个接口最适合新用户开始？

建议先看 [Generations API](/api/cn/happyhorse/generations)（文生视频），这是最基础也是最常用的接口。

### 图生视频和参考生视频有什么区别？

* **图生视频**：基于单张首帧图像生成视频，适合需要从特定画面开始的场景
* **参考生视频**：基于多张参考图像（1-9 张）生成视频，支持通过 character1、character2 等标识引用不同角色，适合需要多个角色或元素的复杂场景

### 视频编辑支持什么功能？

支持风格转换、局部替换等编辑功能。需要提供待编辑的视频（必选）和可选的参考图像（0-5 张），通过文本提示词描述编辑意图。

### 任务结果怎么查？

使用 [Fetch API](/api/cn/happyhorse/fetch) 查询异步任务的最终结果。需要注意：

* `task_id` 查询有效期为 24 小时
* 视频 URL 仅保留 24 小时，超时后会被自动清除，请及时保存生成的视频

### 生成的视频时长是多久？

* 文生视频 / 图生视频 / 参考生视频：3-15 秒（可自定义）
* 视频编辑：输出视频时长 3-15 秒（输入视频≤15 秒时保持一致，输入>15 秒时截取前 15 秒）

### 支持哪些分辨率和宽高比？

* **分辨率**：720P、1080P
* **宽高比**：16:9、9:16、3:4、4:3、1:1