# 海螺 Hailuo 3 视频 API：分辨率、时长、画幅与报错

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

MiniMax 的海螺视频生成模型，共两款，通过 OfoxAI 视频接口 `POST /v1/videos` 调用。任务以异步方式执行：创建任务后获得任务 ID，再通过该 ID 查询结果。

## 模型选择

**要点**:需要 2K 输出时选用 Hailuo 3；需要 480p 时选用 Hailuo 3 Max。两款均不支持 720p 与 1080p。

| 模型 | 分辨率（默认） | 时长 | 画幅 |
|---|---|---|---|
| Hailuo 3 | `768p` `2k`（`768p`） | 4–15 秒 | `21:9` `16:9` `4:3` `1:1` `3:4` `9:16` `adaptive` |
| Hailuo 3 Max | `480p` `768p`（`768p`） | 5–15 秒 | 同上 |

两款均支持文生视频、图生视频与视频参考，并可生成同步音轨（`generate_audio` 默认为 `true`）。`adaptive` 表示沿用输入图片的比例。

**模型 ID（调用时原样复制）**

- Hailuo 3: `minimax/hailuo-3` — 768p、2K
- Hailuo 3 Max: `minimax/hailuo-3-max` — 480p、768p，最短 5 秒

上表与 [Models API](https://ofox.ai/zh/docs/api/openai/models) 返回的 `video_attributes` 一致；模型能力如有调整，以接口返回为准。按秒计费，实际费用以任务结果中的 `usage.video_cost` 为准，价格请参阅[模型页](https://ofox.ai/zh/models/minimax/hailuo-3)。

## 调用示例
以下示例只展示创建任务的请求。创建后查询状态、下载结果的完整流程见 [Video API · 快速开始](https://ofox.ai/zh/docs/api/videos#quickstart)。

**文生视频**

仅传 `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": "宽银幕镜头：沙漠公路上一辆复古汽车驶向落日",
    "duration": 6,
    "resolution": "768p",
    "aspect_ratio": "21:9"
  }'
```

**图生视频**

`frame_images` 传入 1 张 `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": "画面中的人物转身走向远处",
    "duration": 5,
    "frame_images": [
      { "type": "image_url", "image_url": { "url": "https://example.com/first.jpg" }, "frame_type": "first_frame" }
    ]
  }'
```

**视频参考**

`input_references` 传入 1 段视频作为参考。以视频为输入时，计费秒数可能包含输入视频的时长。

```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": "保持镜头运动，将画面改为水墨动画风格",
    "duration": 5,
    "input_references": [
      { "type": "video_url", "video_url": { "url": "https://example.com/source.mp4" } }
    ]
  }'
```

- `frame_images` 与 `input_references` 不可同时传入，同时传入返回 `400 references_conflict`。
- 不需要音轨时传入 `"generate_audio": false`。
- 字段结构的完整说明见[创建视频任务](https://ofox.ai/zh/docs/api/videos/create)。

## 分辨率写法
海螺的分辨率档位与其他系列不同，为 `768p` 与 `2k`（小写 k）。传入其他系列常用的 `720p`、`1080p` 将返回 400。

## 常见报错

**要点**:参数校验错误在创建时即返回，不会创建任务，也不产生费用。报错信息中会列出允许的取值。

| HTTP · code | 报错原文 | 原因 | 处理方法 |
|---|---|---|---|
| 400 `unsupported_parameter` | `resolution "1080p" not supported; allowed: [768p 2k]` | 海螺不支持 1080p | Hailuo 3 请使用 `768p` 或 `2k` |
| 400 `unsupported_parameter` | `duration 4 out of range [5, 15]` | Hailuo 3 Max 最短为 5 秒 | 改为 5 秒及以上，或改用 Hailuo 3 |
| 400 `references_conflict` | `frame_images and input_references are mutually exclusive` | 同时传入了两种素材字段 | 两者只能选择其一 |
| 404 `model_not_found` | `model not found` | 模型 ID 拼写错误 | 从本页复制模型 ID |

完整错误码见 [Video API 错误码](https://ofox.ai/zh/docs/api/videos/errors)。

## 官方文档
- [MiniMax 开放平台文档](https://platform.minimaxi.com/docs/guides/video-generation)
- [OfoxAI · 创建视频任务](https://ofox.ai/zh/docs/api/videos/create)

## 常见问题

**海螺 Hailuo 3 支持 1080p 吗？**

不支持。Hailuo 3 的分辨率是 768p 和 2k，Hailuo 3 Max 是 480p 和 768p。传 720p 或 1080p 会返回 400 resolution not supported。

**Hailuo 3 Max 报错 duration 4 out of range [5, 15]？**

Hailuo 3 Max 单个任务最短 5 秒，最长 15 秒。需要 4 秒的视频请使用 Hailuo 3。

**海螺视频支持 21:9 吗？**

支持。Hailuo 3 和 Hailuo 3 Max 都支持 21:9、16:9、4:3、1:1、3:4、9:16 和 adaptive。