# Hailuo 3 video API: resolution, duration, aspect ratio, and errors

Source: https://ofox.ai/docs/develop/models/hailuo

MiniMax's Hailuo video generation models, two in total, called through the OfoxAI video endpoint `POST /v1/videos`. Tasks run asynchronously: creating a task returns a task ID, which you then use to query the result.

## Choosing a model

**Key point**:Choose Hailuo 3 when you need 2K output; choose Hailuo 3 Max when you need 480p. Neither supports 720p or 1080p.

| Model | Resolutions (default) | Duration | Aspect ratios |
|---|---|---|---|
| Hailuo 3 | `768p` `2k` (`768p`) | 4–15 s | `21:9` `16:9` `4:3` `1:1` `3:4` `9:16` `adaptive` |
| Hailuo 3 Max | `480p` `768p` (`768p`) | 5–15 s | Same as above |

Both support text-to-video, image-to-video, and video reference, and can generate a synchronized audio track (`generate_audio` defaults to `true`). `adaptive` keeps the input image's aspect ratio.

**Model IDs (copy them exactly)**

- Hailuo 3: `minimax/hailuo-3` — 768p, 2K
- Hailuo 3 Max: `minimax/hailuo-3-max` — 480p, 768p; 5 s minimum

The table above matches the `video_attributes` returned by the [Models API](https://ofox.ai/docs/api/openai/models); if model capabilities change, the API response takes precedence. Billing is per second, and the actual charge is `usage.video_cost` in the task result. For prices, see the [model page](https://ofox.ai/models/minimax/hailuo-3).

## Examples
The examples below show only the request that creates the task. For the full flow of querying status and downloading the result after creation, see [Video API · Quickstart](https://ofox.ai/docs/api/videos#quickstart).

**Text to video**

Send only `prompt`.

```bash filename="Terminal"
curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/hailuo-3",
    "prompt": "Widescreen shot: a vintage car drives toward the setting sun on a desert highway",
    "duration": 6,
    "resolution": "768p",
    "aspect_ratio": "21:9"
  }'
```

**Image to video**

Pass one `first_frame` in `frame_images`; the video uses that image as its first frame.

```bash filename="Terminal"
curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/hailuo-3",
    "prompt": "The person in the frame turns and walks into the distance",
    "duration": 5,
    "frame_images": [
      { "type": "image_url", "image_url": { "url": "https://example.com/first.jpg" }, "frame_type": "first_frame" }
    ]
  }'
```

**Video reference**

Pass one video in `input_references` as a reference. When video is used as input, billed seconds may include the input video's duration.

```bash filename="Terminal"
curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/hailuo-3",
    "prompt": "Keep the camera movement and restyle the footage as ink-wash animation",
    "duration": 5,
    "input_references": [
      { "type": "video_url", "video_url": { "url": "https://example.com/source.mp4" } }
    ]
  }'
```

- `frame_images` and `input_references` cannot be sent together; sending both returns `400 references_conflict`.
- Pass `"generate_audio": false` when you do not need an audio track.
- For the full field structure, see [Create video task](https://ofox.ai/docs/api/videos/create).

## Resolution values
Hailuo's resolution tiers differ from other families: `768p` and `2k` (lowercase k). Passing `720p` or `1080p`, common in other families, returns 400.

## Common errors

**Key point**:Parameter validation errors are returned at creation time; no task is created and nothing is charged. The error message lists the allowed values.

| HTTP · code | Error message | Cause | Fix |
|---|---|---|---|
| 400 `unsupported_parameter` | `resolution "1080p" not supported; allowed: [768p 2k]` | Hailuo does not support 1080p | For Hailuo 3, use `768p` or `2k` |
| 400 `unsupported_parameter` | `duration 4 out of range [5, 15]` | Hailuo 3 Max has a 5-second minimum | Use 5 seconds or more, or switch to Hailuo 3 |
| 400 `references_conflict` | `frame_images and input_references are mutually exclusive` | Both input fields were sent | Use only one of them |
| 404 `model_not_found` | `model not found` | Model ID misspelled | Copy the model ID from this page |

For the full list of error codes, see [Video API error codes](https://ofox.ai/docs/api/videos/errors).

## Official docs
- [MiniMax Open Platform documentation](https://platform.minimaxi.com/docs/guides/video-generation)
- [OfoxAI · Create video task](https://ofox.ai/docs/api/videos/create)

## FAQ

**Does Hailuo 3 support 1080p?**

No. Hailuo 3 supports 768p and 2k, and Hailuo 3 Max supports 480p and 768p. Passing 720p or 1080p returns 400 resolution not supported.

**Hailuo 3 Max returns duration 4 out of range [5, 15]?**

Hailuo 3 Max generates a minimum of 5 seconds and a maximum of 15 seconds per task. For a 4-second video, use Hailuo 3.

**Does Hailuo support 21:9?**

Yes. Both Hailuo 3 and Hailuo 3 Max support 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, and adaptive.