# 创建 Happy Horse 视频任务

> 使用统一的 happy-horse 模型创建文生、图生、多参考图和视频编辑任务。

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

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

更新时间：2026-08-10

## 概览

所有能力都使用唯一公共模型 `happy-horse`。通过 `operation` 选择文生、图生、多参考图或视频编辑，通过 `resolution` 选择输出档位。

不要使用已删除的旧档位模型名。旧名字与当前公共契约不兼容。

## 接口

```http
POST /v1/videos
```

兼容的创建路径：

```http
POST /v1/videos/generations
POST /v1/video/generations
```

新接入建议使用 `/v1/videos`。

## 鉴权

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

## 能力矩阵

| `operation` | 提示词 | 图片输入 | 视频输入 | 分辨率 | `duration` | `aspect_ratio` |
| --- | --- | --- | --- | --- | --- | --- |
| `text_to_video` | 必填 | 不接受 | 不接受 | `720p`、`1080p` | 可选，默认 `5` | 可选，默认 `16:9` |
| `image_to_video` | 可选 | 恰好 1 张 | 不接受 | `720p`、`1080p` | 可选，默认 `5` | 不支持 |
| `reference_to_video` | 必填 | 1 至 9 张 | 不接受 | `720p`、`1080p` | 可选，默认 `5` | 可选，默认 `16:9` |
| `edit_video` | 必填 | 0 至 5 张 | 恰好 1 个 | `720p`、`1080p` | 不支持 | 不支持 |

## 请求体参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 固定为 `happy-horse`。 |
| `operation` | string | 是 | `text_to_video`、`image_to_video`、`reference_to_video` 或 `edit_video`。 |
| `resolution` | string | 是 | 所有操作均支持 `720p` 或 `1080p`。 |
| `prompt` | string | 条件必填 | 除 `image_to_video` 外均必填，最长 `2500` 字符。 |
| `duration` | integer | 否 | 仅生成使用，范围 `3` 至 `15`，默认 `5`；编辑请求不能传。 |
| `aspect_ratio` | string | 否 | 仅文生和多参考图生视频使用；图生和编辑请求不能传。 |
| `image` | string | 条件必填 | `image_to_video` 推荐使用的单张 HTTP(S) 图片字段。 |
| `images` | string[] | 条件必填 | `reference_to_video` 使用的 1 至 9 张 HTTP(S) 图片。 |
| `reference_image_urls` | string[] | 否 | 多参考图的别名；视频编辑也可使用，最多 5 张。 |
| `video` | string | 条件必填 | `edit_video` 使用的单个 HTTP(S) 源视频。 |
| `seed` | integer | 否 | 随机种子，范围 `0` 至 `2147483647`。 |
| `watermark` | boolean | 否 | 是否添加水印，默认 `false`。 |
| `audio_setting` | string | 否 | 仅编辑使用：`auto` 或 `origin`，默认 `auto`。 |

文生和多参考图生视频支持以下 `aspect_ratio`：

- `16:9`
- `9:16`
- `1:1`
- `4:3`
- `3:4`
- `4:5`
- `5:4`
- `9:21`
- `21:9`

`size` 和 `enable_safety_checker` 不属于 Happy Horse 公共参数，传入会被拒绝。

公共 HappyHorse 1.0 契约不开放 `480p`。把 `resolution` 设为 `480p` 的请求会在
任务创建前被拒绝。

## 输入规则

| 模式 | 可用素材字段 |
| --- | --- |
| 文生视频 | 不传图片或视频字段 |
| 图生视频 | 使用 `image`，或通过受支持的图片别名传入恰好 1 张图片 |
| 多参考图生视频 | 使用 `images` 或 `reference_image_urls`，传入 1 至 9 个 URL |
| 视频编辑 | 使用 `video`，并可选传入最多 5 个 `reference_image_urls` |

所有媒体输入都必须是完整、可公开访问的 HTTP 或 HTTPS URL。当前模型契约不接受文件上传、裸 Base64 或 Data URL。

## 请求示例

### 文生视频

```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, realistic movement and soft rim light.",
    "duration": 7,
    "aspect_ratio": "21:9",
    "seed": 12345,
    "watermark": false
  }'
```

### 图生视频

输出构图跟随源图片，因此不要传 `aspect_ratio`。

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "image_to_video",
    "resolution": "720p",
    "image": "https://example.com/source-frame.png",
    "prompt": "The subject walks forward naturally while the camera slowly pushes in.",
    "duration": 5,
    "seed": 67890,
    "watermark": false
  }'
```

`image_to_video` 可以省略提示词。

### 多参考图生视频

提示词可以使用 `character1` 至 `character9`，按数组顺序指代参考图。

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "reference_to_video",
    "resolution": "720p",
    "prompt": "character1 drives character2 across the lunar surface while both identities remain consistent.",
    "reference_image_urls": [
      "https://example.com/character.png",
      "https://example.com/vehicle.png"
    ],
    "duration": 8,
    "aspect_ratio": "16:9",
    "seed": 24680,
    "watermark": false
  }'
```

### 视频编辑

编辑时长跟随源视频，不能传 `duration` 或 `aspect_ratio`。

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "edit_video",
    "resolution": "1080p",
    "prompt": "Replace the jacket with the referenced red jacket while preserving identity, motion, camera movement, and background.",
    "video": "https://example.com/source-video.mp4",
    "reference_image_urls": [
      "https://example.com/red-jacket.png"
    ],
    "audio_setting": "origin",
    "seed": 13579,
    "watermark": false
  }'
```

使用 `audio_setting: "origin"` 保留原音频；使用 `auto` 让服务自动决定音频处理方式。

## `extra_body` 兼容

推荐把公共参数直接放在请求体顶层。兼容客户端也可以把 `operation`、`resolution`、`seed`、`watermark` 和 `audio_setting` 放入 `extra_body`。不要在顶层和 `extra_body` 中传入互相冲突的值。

```json
{
  "model": "happy-horse",
  "prompt": "Turn the room into a warm wooden studio.",
  "video": "https://example.com/source-video.mp4",
  "extra_body": {
    "operation": "edit_video",
    "resolution": "720p",
    "audio_setting": "auto",
    "watermark": false
  }
}
```

## 响应示例

### 任务已受理

```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#视频任务生命周期)。

视频编辑等最终结算操作应在任务完成后再次读取 `billing_contract`。

## 素材限制

### 图生视频源图片

- 格式：JPEG、JPG、PNG、BMP 或 WebP。
- 最小尺寸：`300px`。
- 画面比例：`1:2.5` 至 `2.5:1`。
- 最大文件：`10MB`。

### 多参考图

- 格式：JPEG、JPG、PNG 或 WebP。
- 数量：1 至 9 张。
- 最短边至少 `400px`，建议 720p 以上。
- 每张最大 `10MB`。

### 视频编辑源素材

- 格式：MP4 或 MOV，推荐 H.264。
- 输入时长：3 至 60 秒；编辑服务最多处理 15 秒。
- 尺寸：长边不超过 `2160px`，短边不小于 `320px`。
- 画面比例：`1:2.5` 至 `2.5:1`。
- 帧率：大于 `8fps`。
- 最大文件：`100MB`。

编辑参考图支持 JPEG、JPG、PNG 或 WebP，尺寸至少 `300px`，每张最大 `10MB`。

## 计费说明

- 文生、图生和多参考图生成按请求的输出时长与分辨率档位结算。
- 视频编辑根据实际输入和输出视频时长进行最终结算，最终费用可能与提交时预估不同。
- `resolution` 是服务档位，不保证每种画幅或源图片都对应一个固定像素尺寸。
- 最终金额以 UniAI 当前价格页和任务结算记录为准。

## 常见错误

| 错误 | 原因 | 处理方式 |
| --- | --- | --- |
| 模型名无效 | 使用了已删除的旧档位模型名 | 把 `model` 改为 `happy-horse` |
| 缺少参数 | 未传 `operation` 或 `resolution` | 显式传入两个参数 |
| 参数不支持 | 传入了 `size` 或 `enable_safety_checker` | 删除不支持的字段 |
| 素材数量不正确 | 当前操作收到错误数量的图片或视频 | 按能力矩阵调整素材 |
| 分辨率不正确 | `resolution` 为 `480p` 或其他不支持的值 | 使用 `720p` 或 `1080p` |
| 编辑参数不正确 | 编辑请求包含 `duration` 或 `aspect_ratio` | 删除不支持字段 |
| 素材下载失败 | URL 私有、过期、重定向异常或无法访问 | 使用稳定的公开 HTTPS URL |

## 相关页面

- [Happy Horse 视频生成](/models/video/happy-horse)
- [视频生成概览](/models/video/overview)