# Hailuo

> 通过 UniAI 视频任务接口调用 Hailuo 系列，创建文生、单图和首尾帧视频。

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

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

更新时间：2026-08-04

## 概览

UniAI 通过 OpenAI 兼容的异步视频任务接口提供三个稳定的 Hailuo 公共模型。

| 模型 | 文生视频 | 单图生视频 | 首尾帧生视频 |
| --- | --- | --- | --- |
| `hailuo-02` | 支持 | 支持 | 支持 |
| `hailuo-2.3` | 支持 | 支持 | 不支持 |
| `hailuo-2.3-fast` | 不支持 | 支持 | 不支持 |

三个模型统一使用创建、查询和内容下载接口，请求字段组合决定生成模式。

## 适用场景

Hailuo 系列适合以下任务：

- 根据提示词生成 6 秒或 10 秒视频；
- 让一张可公开访问的图片动起来；
- 使用 `hailuo-02` 生成首尾帧过渡视频；
- 选择 `768p` 或 `1080p` 输出。

Hailuo 公共契约不支持音频、多参考图、参考视频、画幅比例控制或视频编辑。

## 公共限制

- `duration` 必须是 `6` 或 `10` 秒。
- `resolution` 必须是 `768p` 或 `1080p`。
- `1080p` 只支持生成 6 秒视频。
- 输入图片必须是公开可访问的 HTTP(S) URL。
- 提示词最长 2,000 个字符。

## 接口

| 用途 | 方法 | 路径 |
| --- | --- | --- |
| 创建视频任务 | `POST` | `/v1/videos` |
| 查询视频任务 | `GET` | `/v1/videos/{task_id}` |
| 下载视频文件 | `GET` | `/v1/videos/{task_id}/content` |

## 鉴权

所有请求均使用 UniAI Bearer Token：

```http
Authorization: Bearer sk-***
```

创建任务时还需发送：

```http
Content-Type: application/json
```

## 请求体参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `hailuo-02`、`hailuo-2.3` 或 `hailuo-2.3-fast`。 |
| `prompt` | string | 是 | 视频内容描述，最长 2,000 个字符。 |
| `image` | string | 条件必填 | 单图生视频的输入图或首尾帧模式的首帧，必须是公开 HTTP(S) URL。 |
| `last_image` | string | 条件必填 | 尾帧图片的公开 HTTP(S) URL；仅 `hailuo-02` 支持，且必须与 `image` 一起传入。 |
| `duration` | integer | 是 | `6` 或 `10`。 |
| `resolution` | string | 是 | `768p` 或 `1080p`；`1080p` 只支持 6 秒。 |
| `prompt_optimizer` | boolean | 否 | 是否在生成前优化提示词。 |
| `fast_pretreatment` | boolean | 否 | 是否使用快速预处理；首尾帧模式不要传 `true`。 |
| `watermark` | boolean | 否 | 是否添加 AIGC 水印。 |

根据生成模式选择输入字段：

| 模式 | 模型 | 输入字段 |
| --- | --- | --- |
| 文生视频 | `hailuo-02` 或 `hailuo-2.3` | `prompt` |
| 单图生视频 | 任意 Hailuo 模型 | `prompt` + `image` |
| 首尾帧生视频 | `hailuo-02` | `prompt` + `image` + `last_image` |

字段约束：

- 文生视频不要传入 `image` 或 `last_image`。
- `hailuo-2.3-fast` 只支持单图生视频，因此必须传入 `image`。
- `last_image` 不能单独使用，必须与 `image` 一起传入。
- `last_image` 只能与 `hailuo-02` 配合使用。
- 所有支持的公共参数都直接放在请求体顶层。
- 不要传入音频、多参考图数组、参考视频、画幅比例或视频编辑字段。

## 请求示例

### 文生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-2.3",
    "prompt": "A cinematic train passes through a snowy mountain canyon while morning mist drifts slowly and the camera moves forward.",
    "duration": 6,
    "resolution": "1080p",
    "prompt_optimizer": true,
    "watermark": false
  }'
```

### 单图生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-2.3-fast",
    "prompt": "The person naturally raises their head and looks at the camera while face and clothing remain consistent.",
    "image": "https://example.com/source.png",
    "duration": 6,
    "resolution": "768p",
    "fast_pretreatment": true,
    "watermark": false
  }'
```

### 首尾帧生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-02",
    "prompt": "Transition naturally from day to night while the building structure remains stable and the motion stays smooth.",
    "image": "https://example.com/first.png",
    "last_image": "https://example.com/last.png",
    "duration": 6,
    "resolution": "1080p",
    "prompt_optimizer": true,
    "watermark": false
  }'
```

## 响应示例

### 任务创建成功

请保存返回的 `id`，用于后续查询：

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video",
  "model": "hailuo-2.3",
  "status": "queued",
  "progress": 0,
  "created_at": 1785772800
}
```

## 任务状态与结果

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

## 计费说明

所选模型、`duration` 和 `resolution` 会影响计费；`1080p` 不支持 10 秒请求。当前价格和最终扣费以 UniAI 模型页与消费日志为准。

## 常见错误

以下请求会被拒绝：

- 模型不支持当前生成模式；
- `duration` 不是 `6` 或 `10`；
- `1080p` 请求了 10 秒视频；
- `hailuo-2.3-fast` 缺少 `image`；
- 单独传入 `last_image`，或对 `hailuo-02` 以外的模型传入 `last_image`；
- 图片 URL 无法由服务端公开访问；
- 请求音频、参考视频、多参考图、画幅比例控制或视频编辑能力。

传入 `watermark: false` 表示请求关闭 AIGC 水印。最终水印行为还可能受平台可用性与模型策略影响；如果完成结果仍出现非预期水印，请联系 UniAI 支持。

## 相关页面

- [视频生成概览](/models/video/overview)
- [模型列表](/models)