# Happy Horse

> 通过 UniAI 使用统一的 Happy Horse 模型创建文生、图生、多参考图和视频编辑任务。

Canonical URL: https://docs.uniai.tv/models/video/happy-horse
Locale: zh-CN

本页示例中的 `{BASE_URL}` 表示 `https://api.uniai.tv`。

更新时间：2026-08-10

## 概览

UniAI 只对外提供一个稳定的 Happy Horse 公共模型：`happy-horse`。当前公共契约开放 Happy Horse 1.0 的能力，生成方式和输出档位都通过请求参数选择，不再拆分成多个模型名。

| 能力 | `operation` | 必需素材 | 分辨率 |
| --- | --- | --- | --- |
| 文生视频 | `text_to_video` | 无 | `720p`、`1080p` |
| 图生视频 | `image_to_video` | 恰好 1 张图片 | `720p`、`1080p` |
| 多参考图生视频 | `reference_to_video` | 1 至 9 张图片 | `720p`、`1080p` |
| 视频编辑 | `edit_video` | 恰好 1 个视频，可选 0 至 5 张图片 | `720p`、`1080p` |

历史档位模型名不再兼容。所有请求都必须使用 `model: "happy-horse"`，并同时传入 `operation` 和 `resolution`。

公共 HappyHorse 1.0 契约不开放 `480p`，使用该分辨率的请求会在任务创建前被拒绝。

## 适用场景

使用 `happy-horse` 可以：

- 根据文字提示词生成视频；
- 让一张源图片动起来并尽量保持原始构图；
- 通过多张参考图保持人物、商品或视觉风格一致；
- 编辑已有视频，并选择保留原音频或自动处理音频。

## 接口

新接入统一使用以下接口：

| 用途 | 方法 | 路径 |
| --- | --- | --- |
| 创建视频任务 | `POST` | `/v1/videos` |
| 查询视频任务 | `GET` | `/v1/videos/{task_id}` |
| 获取完成后的视频 | `GET` | `/v1/videos/{task_id}/content` |

兼容的 `/v1/videos/generations` 和 `/v1/video/generations` 创建、查询路径仍可使用。新客户端建议统一使用 `/v1/videos`。

## 鉴权

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 快速请求示例

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "text_to_video",
    "resolution": "1080p",
    "prompt": "A white horse runs across a misty grassland at sunrise, cinematic camera movement.",
    "duration": 7,
    "aspect_ratio": "16:9",
    "seed": 12345,
    "watermark": false
  }'
```

创建响应会同时返回 `id` 和兼容字段 `task_id`。保存其中任意一个值，用于后续轮询。

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "happy-horse",
  "status": "queued",
  "progress": 0,
  "created_at": 1785801600,
  "video_url": null
}
```

## 任务状态与结果

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/models/video/overview#视频任务生命周期)。

## 计费说明

- 生成任务按操作类型、选择的分辨率档位和生成时长计费。
- 视频编辑根据实际输入和输出视频时长进行最终结算，因此最终费用可能与提交时预估不同。
- `resolution` 选择的是公共服务档位，不保证每种画幅和源图片都对应同一个固定像素尺寸；对像素尺寸有严格要求时应检查成品媒体信息。
- 最终价格以 UniAI 当前价格页和任务结算记录为准。

## 常见错误

- 使用已删除的旧档位模型名，而不是 `happy-horse`。
- 缺少必填的 `operation` 或 `resolution`。
- 传入 `resolution: "480p"`；应使用 `720p` 或 `1080p`。
- 传入 `size`；Happy Horse 只使用 `resolution`，并会拒绝 `size`。
- `edit_video` 请求传入 `duration` 或 `aspect_ratio`。
- `image_to_video` 请求传入 `aspect_ratio`；图生视频画面比例跟随源图片。
- 媒体 URL 是私有地址、已过期或无法从公网访问。

## 相关页面

- [创建 Happy Horse 任务](/models/video/happy-horse/create-task)
- [视频生成概览](/models/video/overview)