# Hailuo

> Create text, single-image, and first-and-last-frame videos with the Hailuo series through the UniAll video task API.

Canonical URL: https://docs.uniall.ai/models/video/hailuo
Locale: en

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

Updated: 2026-08-04

## Overview

UniAll provides three stable public Hailuo models through the OpenAI-compatible asynchronous video task API.

| Model | Text To Video | Single Image | First And Last Frame |
| --- | --- | --- | --- |
| `hailuo-02` | Supported | Supported | Supported |
| `hailuo-2.3` | Supported | Supported | Not supported |
| `hailuo-2.3-fast` | Not supported | Supported | Not supported |

All three models use the same create, query, and content-download endpoints. The request shape determines the generation mode.

## When To Use It

Use the Hailuo series when you need to:

- create a 6-second or 10-second video from a prompt;
- animate one publicly accessible source image;
- generate a first-and-last-frame transition with `hailuo-02`;
- choose between `768p` and `1080p` output.

The public Hailuo contract does not support audio, multiple reference images, reference videos, aspect-ratio controls, or video editing.

## Limits

- `duration` must be `6` or `10` seconds.
- `resolution` must be `768p` or `1080p`.
- `1080p` only supports a 6-second duration.
- Input images must be publicly accessible HTTP(S) URLs.
- Prompts can contain up to 2,000 characters.

## Endpoints

| Purpose | Method | Path |
| --- | --- | --- |
| Create a video task | `POST` | `/v1/videos` |
| Query a video task | `GET` | `/v1/videos/{task_id}` |
| Download the video | `GET` | `/v1/videos/{task_id}/content` |

## Authentication

Every request requires a UniAll Bearer token:

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

Task creation also requires:

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

## Request Body Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | `hailuo-02`, `hailuo-2.3`, or `hailuo-2.3-fast`. |
| `prompt` | string | Yes | Video description with a maximum length of 2,000 characters. |
| `image` | string | Conditional | Public HTTP(S) URL for single-image generation or the first frame. |
| `last_image` | string | Conditional | Public HTTP(S) URL for the last frame; only supported by `hailuo-02` and requires `image`. |
| `duration` | integer | Yes | `6` or `10`. |
| `resolution` | string | Yes | `768p` or `1080p`; `1080p` only supports 6 seconds. |
| `prompt_optimizer` | boolean | No | Whether to optimize the prompt before generation. |
| `fast_pretreatment` | boolean | No | Whether to use fast preprocessing; do not set it to `true` for first-and-last-frame generation. |
| `watermark` | boolean | No | Whether to add an AIGC watermark. |

Choose input fields according to the generation mode:

| Mode | Model | Input Fields |
| --- | --- | --- |
| Text to video | `hailuo-02` or `hailuo-2.3` | `prompt` |
| Single image | Any Hailuo model | `prompt` + `image` |
| First and last frame | `hailuo-02` | `prompt` + `image` + `last_image` |

Follow these validation rules:

- Do not pass `image` or `last_image` for text-to-video requests.
- `hailuo-2.3-fast` only supports single-image generation and therefore requires `image`.
- Do not pass `last_image` without `image`.
- Use `last_image` only with `hailuo-02`.
- Pass all supported parameters at the top level of the request body.
- Do not send audio, reference-image arrays, reference videos, aspect ratios, or video-editing fields.

## Request Examples

### Text To Video

```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
  }'
```

### Single Image To Video

```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
  }'
```

### First And Last Frame

```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
  }'
```

## Response Examples

### Task Created

Save the returned `id` for later queries:

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

## Task Status And Result

After creation, save `id` or `task_id`, then poll `GET /v1/videos/{task_id}` until the task reaches `completed` or `failed`. See [Video Generation Overview](/models/video/overview#video-task-lifecycle) for the shared polling interval, status fields, error contract, result URL, and authenticated download flow.

## Billing Notes

The selected model, `duration`, and `resolution` affect billing. A 10-second request is not available at `1080p`. Check the UniAll model page and consumption log for current pricing and final settlement.

## Common Errors

Requests are rejected when they:

- use a model that does not support the requested generation mode;
- pass a `duration` other than `6` or `10`;
- request a 10-second video at `1080p`;
- omit `image` for `hailuo-2.3-fast`;
- pass `last_image` without `image`, or use `last_image` with a model other than `hailuo-02`;
- use an image URL that the service cannot access publicly;
- request audio, reference videos, multiple reference images, aspect-ratio control, or video editing.

Set `watermark` to `false` to request output without an AIGC watermark. Final watermark behavior can also depend on platform availability and model policy. Contact UniAll support when a completed result still contains a watermark unexpectedly.

## Related Pages

- [Video Generation Overview](/models/video/overview)
- [Models](/models)