> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qingbo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Hailuo 系列

> MiniMax 海螺视频 — Hailuo 2.3 / 2.3 Fast,15 种中括号运镜指令

MiniMax 海螺(Hailuo)视频生成系列。

**两档可选** — `minimax-hailuo-2.3`(2.3 主版,新增 15 种运镜指令)、`minimax-hailuo-2.3-fast`(2.3 加速档,更快更便宜,适合预览/批量)。

支持文生视频(T2V)与图生视频(I2V)。

## 定价

按 **分辨率 × 时长** 计费,单位 `$ / 秒`。

| 模型                        | 768p          | 1080p         |
| ------------------------- | ------------- | ------------- |
| `minimax-hailuo-2.3`      | `$0.0549` / 秒 | `$0.081` / 秒  |
| `minimax-hailuo-2.3-fast` | `$0.0279` / 秒 | `$0.0477` / 秒 |

实际费用 = 单价 / 秒 × `duration`。例:`minimax-hailuo-2.3` 1080p 6 秒 = `$0.081 × 6 = $0.486`。

## 调用示例

<CodeGroup>
  ```bash 文生视频(最简) theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "minimax-hailuo-2.3",
      "prompt": "一只柴犬穿宇航服在月球上行走,电影感光影",
      "duration": 6,
      "resolution": "1080p",
      "aspect_ratio": "16:9"
    }'
  ```

  ```bash 图生视频(I2V 首帧) theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "minimax-hailuo-2.3",
      "prompt": "人物缓缓走向镜头",
      "image_urls": ["https://cdn.example.com/portrait.jpg"],
      "duration": 6,
      "resolution": "1080p"
    }'
  ```

  ```bash 2.3 带运镜指令 theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "minimax-hailuo-2.3",
      "prompt": "[推进] 山间雾气缭绕的古寺,[变焦推近] 屋檐下的铜铃随风轻摆",
      "duration": 10,
      "resolution": "1080p",
      "aspect_ratio": "16:9"
    }'
  ```

  ```bash 加速档(2.3-fast) theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "minimax-hailuo-2.3-fast",
      "prompt": "城市夜景,霓虹灯沿街闪烁",
      "duration": 6,
      "resolution": "768p",
      "aspect_ratio": "16:9"
    }'
  ```
</CodeGroup>

<ResponseExample>
  ```json 提交成功 theme={"system"}
  {
    "task_id": "task-wave1775285160b950328499",
    "model": "minimax-hailuo-2.3",
    "action": "generate",
    "status": "queued",
    "created_at": 1775285160040,
    "progress": 0
  }
  ```
</ResponseExample>

提交后用 [`GET /v1/tasks/{task_id}`](/cn/api-reference/task/status) 轮询状态,详见 [任务系统](/cn/docs/task-system)。

## 可用模型

| 模型 ID                     | 分辨率          | 时长(秒)  | Actions  | 备注                      |
| ------------------------- | ------------ | ------ | -------- | ----------------------- |
| `minimax-hailuo-2.3`      | 768p / 1080p | 6 / 10 | generate | 2.3 主版,prompt ≤ 2000 字符 |
| `minimax-hailuo-2.3-fast` | 768p / 1080p | 6 / 10 | generate | 加速档,单价更低                |

## 通用参数

<ParamField body="model" type="string" required>
  模型 ID,可选值:

  * `minimax-hailuo-2.3`
  * `minimax-hailuo-2.3-fast`
</ParamField>

<ParamField body="action" type="string" default="generate">
  操作类型,固定为 `generate`。传入 `image_urls` 即自动走 **图生视频(I2V)**,否则为文生视频(T2V)
</ParamField>

<ParamField body="prompt" type="string" required>
  视频描述文本,最多 **2000 字符**;在文中以 `[指令]` 中括号嵌入运镜标签可触发对应镜头运动(详见下方 [运镜指令](#运镜指令-2-3-2-3-fast))
</ParamField>

<ParamField body="aspect_ratio" type="string" default="16:9">
  画面宽高比,可选值:

  * `16:9` — 横版宽屏
  * `9:16` — 竖版长屏
  * `1:1` — 正方形
</ParamField>

<ParamField body="resolution" type="string" default="768p">
  输出分辨率,模型支持范围见 [可用模型](#可用模型) 表。可选值:

  * `768p`
  * `1080p`
</ParamField>

<ParamField body="duration" type="integer" default="6">
  视频时长(秒)。支持 `6` / `10`
</ParamField>

<ParamField body="image_urls" type="string[]">
  参考图片 URL 数组,触发 **I2V** 模式;支持公网 URL 或 Base64
</ParamField>

<ParamField body="callback_url" type="string">
  Webhook 回调地址,任务终态时调用。详见 [回调机制](/cn/docs/sync-async#异步任务-webhook)
</ParamField>

<ParamField body="callback_events" type="string[]">
  订阅的回调事件类型,默认全部终态
</ParamField>

## 模型特定参数

两档均无额外特定参数,所有可选项见 [通用参数](#通用参数)。

## 运镜指令(2.3 / 2.3-fast)

Hailuo 2.3 系列独家亮点 — **在 `prompt` 中以 `[指令]` 中括号嵌入** 即可触发对应镜头运动;同一句可叠加多个标签,后端会按顺序解析。

| 类别     | 指令       | 效果             |
| ------ | -------- | -------------- |
| **位移** | `[左移]`   | 镜头水平向左平移       |
|        | `[右移]`   | 镜头水平向右平移       |
|        | `[上升]`   | 镜头垂直向上抬升       |
|        | `[下降]`   | 镜头垂直向下落下       |
| **推拉** | `[推进]`   | 镜头物理向前推进       |
|        | `[拉远]`   | 镜头物理向后拉远       |
| **摇镜** | `[左摇]`   | 机身固定向左摇头       |
|        | `[右摇]`   | 机身固定向右摇头       |
|        | `[上摇]`   | 机身固定向上仰        |
|        | `[下摇]`   | 机身固定向下俯        |
| **变焦** | `[变焦推近]` | 焦距变化模拟推近(机身不动) |
|        | `[变焦拉远]` | 焦距变化模拟拉远(机身不动) |
| **特殊** | `[晃动]`   | 手持感抖动          |
|        | `[跟随]`   | 跟随主体运动         |
|        | `[固定]`   | 完全静止机位         |

<Tip>
  **写法示例** — `"[推进] 古镇青石板路,[变焦推近] 雨水从屋檐滴落"` —— 镜头先向前推,再聚焦屋檐细节。
</Tip>

## 资源限制

| 项目                 | 限制                        |
| ------------------ | ------------------------- |
| 参考图片(`image_urls`) | URL 或 Base64,JPG/PNG/WEBP |
| Prompt 长度          | ≤ 2000 字符                 |
| 时长                 | 6 / 10 秒                  |
| 输出                 | MP4,链接 24 小时有效            |

## 相关文档

* [任务系统详解](/cn/docs/task-system) — 任务状态机 / 轮询节奏 / 异步推送
* [请求响应格式](/cn/docs/request-response) — 通用错误码 / Headers / 限流
* [认证](/cn/docs/authentication) — API Key 申请与使用