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

# MiniMax H3（海螺）视频生成 API：价格与接入

> 通过老张API调用 MiniMax H3 文生视频、首尾帧生视频和参考图、参考视频、参考音频生视频：提交异步任务、查询并下载带音轨的 MP4，以及 768P 和 2K 按秒计费的价格。

MiniMax H3 是 MiniMax 的全模态视频模型，同一个模型支持文字、图片、视频和音频输入，输出自带音乐和音效的视频。老张API按视频秒数计费，768P 每秒 \$0.05，用普通分组的令牌即可调用，不需要专属视频分组。

| 项目 | 内容 |
| - | - |
| 模型 ID | `MiniMax-H3`（区分大小写） |
| 创建任务 | `POST /hailuo/v2/video_generation` |
| 查询任务 | `GET /hailuo/v2/query/video_generation/{task_id}`，完成后从 `task.content.url` 下载 MP4 |
| 令牌分组 | `default`、`vip`、`svip`，计费模式选按量优先 |
| 价格 | 768P \$0.05/秒，2K \$0.08/秒，按请求时长计费，见[计费与价格](#计费与价格) |
| 规格 | 时长 4–15 秒整数，分辨率 `768P` 或 `2K`，输出带立体声音轨 |
| 结果保存 | 视频链接保留 7 天 |
| 线路 | 基于 MiniMax 开源的 H3 模型权重独立部署，不经 MiniMax 官方 API，因此单独定价 |

> [!WARNING]
>
> MiniMax H3 只支持上表的 `/hailuo/v2` 原生接口。`/v1/videos` 和 `/v1/video/generations` 不能调用这个模型，请求会被拒绝且不扣费。

![MiniMax H3 文生视频示例输出：黄昏雨后屋顶上的橘猫，远处城市灯光](https://mintcdn.com/laozhangai-edd05f2c/McVdWQYpbAhpR0pV/images/samples/minimax-h3-zh-t2v.jpg?fit=max\&auto=format\&n=McVdWQYpbAhpR0pV\&q=85\&s=7793858c3943a094ac62f4d880dc2450)

「文生视频」示例的输出截图：768P，5 秒，16:9

## 创建令牌

在[令牌管理](https://api2.laozhang.ai/token)新增令牌，按下面配置：

| 配置项 | 选择 |
| - | - |
| 分组 | `default`、`vip` 或 `svip`，三个分组价格相同 |
| 计费模式 | 按量优先（推荐）或按量计费；按次计费的令牌无法调用 |
| 建议 | 视频单独建一个令牌，便于在调用日志里按任务核对消费 |

不需要 MiniMax 账号，也不用单独开通视频分组。

## 计费与价格

MiniMax H3 按视频秒数计费，2026 年 10 月 24 日起的单价如下：

| 计费项 | 老张API | MiniMax 官方 API |
| - | -: | -: |
| 768P 输出 | \$0.05 / 秒 | \$0.08 / 秒 |
| 2K 输出 | \$0.08 / 秒 | \$0.13 / 秒 |
| 参考视频 | 按输出分辨率的每秒单价计 | 按输出分辨率的每秒单价计 |
| 参考图（前 5 张免费） | 第 6 张起 \$0.03 / 张 | 第 6 张起 \$0.04 / 张 |
| 参考音频 | 免费 | 免费 |

官方价取自 [MiniMax 按量计费价格](https://platform.minimax.io/docs/guides/pricing-paygo)（MiniMax-H3，2026 年 10 月 24 日核对）。横屏、竖屏和方形同价，只看分辨率和秒数。

计费时长按下面的规则计算：

* 输出：按请求里的 `duration` 计费，成片通常比请求时长多 0.1–0.5 秒，不另收费。
* 参考视频：按素材时长计费，不足 1 秒按 1 秒计，例如 5.8 秒的素材按 6 秒计。
* 参考图：一个任务里超过 5 张的部分按张计费，首帧、尾帧图也计入张数。

几个单个视频的费用示例：

* 768P、5 秒文生视频：5 × \$0.05 = \$0.25
* 2K、10 秒文生视频：10 × \$0.08 = \$0.80
* 768P、4 秒，带一段 6 秒参考视频：(4 + 6) × \$0.05 = \$0.50

创建任务时按「时长 × 单价」预扣，超过 5 张的参考图一起预扣。带参考视频的任务在完成后补扣参考视频的秒数，调用日志里会多一条结算记录。

失败的任务全额退回，提交阶段返回错误的请求不扣费。重复提交会创建新任务并再次计费，业务层请保存业务 ID 与 `task_id` 的对应关系。每个任务的实际扣费以[调用日志](https://api2.laozhang.ai/log)为准。

## 调用流程

**1. 创建任务**

调用 `POST /hailuo/v2/video_generation`，JSON 请求体包含：

* `model`：`MiniMax-H3`
* `content`：一条文本，以及可选的图片、视频、音频素材
* `resolution`、`duration`、`ratio`

保存响应中的 `task_id`。

**2. 轮询状态**

每 10 秒调用一次 `GET /hailuo/v2/query/video_generation/{task_id}`，读取 `task.status`。4–5 秒的 768P 视频通常 1 分钟左右完成，2K 和带参考视频的任务更久。客户端总超时建议 30 分钟。

**3. 下载结果**

`task.status` 为 `succeeded` 时，从 `task.content.url` 下载 MP4。链接保留 7 天，下载不需要 `Authorization` 请求头。

## 准备环境

下面的 cURL 示例用 `jq` 提取字段（macOS 可用 `brew install jq` 安装）。先设置密钥和 Base URL：

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的老张API密钥"
export BASE_URL="https://api.laozhang.ai"
```

## 文生视频

```bash theme={null}
curl -s -X POST "$BASE_URL/hailuo/v2/video_generation" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "黄昏时分，一只橘猫在雨后的屋顶上慢慢走过，远处城市灯光亮起，镜头缓慢跟随，电影感光影"
      }
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9"
  }' | tee h3-create.json

export TASK_ID=$(jq -r '.task_id' h3-create.json)
```

创建成功时只返回任务 ID：

```json theme={null}
{
  "task_id": "1792835118519344847"
}
```

只有文字时 `ratio` 必须是固定比例，不能用 `adaptive`。

## 首帧和首尾帧生视频

用 `first_frame` 指定开场画面，加上 `last_frame` 可以同时指定结束画面。`ratio` 传 `adaptive` 时，输出比例跟随首帧图片：

```bash theme={null}
curl -s -X POST "$BASE_URL/hailuo/v2/video_generation" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "model": "MiniMax-H3",
    "content": [
      { "type": "text", "text": "小狗沿着海边继续奔跑，镜头跟随" },
      { "type": "image_url", "role": "first_frame", "image_url": { "url": "https://example.com/start.jpg" } },
      { "type": "image_url", "role": "last_frame", "image_url": { "url": "https://example.com/end.jpg" } }
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "adaptive"
  }'
```

图片可以是公网 HTTPS 链接，也可以是 `data:image/jpeg;base64,...` 格式的 Base64 数据。只要首帧时去掉 `last_frame` 那一项。

## 参考素材生视频

参考素材让画面里出现指定的人物或物体、沿用参考视频的动作和运镜，或者跟随参考音频的节奏。提示词里按同类素材的顺序引用它们：第一张参考图是 `<Picture 1>`，第一段参考视频是 `<Video 1>`，第一段参考音频是 `<Audio 1>`。

```bash theme={null}
curl -s -X POST "$BASE_URL/hailuo/v2/video_generation" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "model": "MiniMax-H3",
    "content": [
      { "type": "text", "text": "<Picture 1> 中的角色在公园小路上行走，运镜参考 <Video 1>，节奏跟随 <Audio 1>" },
      { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://example.com/character.png" } },
      { "type": "video_url", "role": "reference_video", "video_url": { "url": "https://example.com/camera-move.mp4" } },
      { "type": "audio_url", "role": "reference_audio", "audio_url": { "url": "https://example.com/beat.mp3" } }
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9"
  }'
```

组合参考素材时注意：

* 参考图、参考视频、参考音频可以任意组合，但参考音频不能单独使用，至少还要有一张参考图或一段参考视频。
* 首帧、尾帧不能和参考素材放在同一个请求里。
* 视频和音频素材必须是公网 HTTPS 直链，服务端要能直接下载。
* 参考视频按秒计费，计算方式见[计费与价格](#计费与价格)。

## 查询和下载

### 查询任务

```bash theme={null}
curl -s "$BASE_URL/hailuo/v2/query/video_generation/$TASK_ID" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -o h3-task.json
jq -r '.task.status' h3-task.json
```

每 10 秒执行一次，直到 `task.status` 变为 `succeeded` 或 `failed`。成功响应：

```json theme={null}
{
  "task": {
    "id": "1792835118519344847",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1792835121,
    "updated_at": 1792835146,
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video",
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 0
    },
    "content": {
      "url": "https://media.laozhang.ai/videos/1792835118519344847-xxxxxxxxxxxxxxxx.mp4"
    }
  }
}
```

`usage` 是这个任务的计费秒数：`input_seconds` 是参考视频秒数，`output_seconds` 是输出秒数。

### 下载视频

```bash theme={null}
VIDEO_URL=$(jq -r '.task.content.url // empty' h3-task.json)
curl -L -o h3-output.mp4 "$VIDEO_URL"
```

链接保留 7 天，请及时下载并转存到自己的存储。

## Python 最小客户端

示例只用 Python 标准库，运行前先设置 `LAOZHANG_API_KEY` 环境变量。它每 10 秒查询一次，总超时 30 分钟，完成后把视频保存为 `h3-output.mp4`。

```python theme={null}
import json
import os
import time
import urllib.request
from urllib.error import HTTPError

BASE_URL = "https://api.laozhang.ai"
API_KEY = os.environ["LAOZHANG_API_KEY"]
POLL_INTERVAL = 10  # 秒
TIMEOUT = 30 * 60  # 总超时 30 分钟


def request(method, path, body=None):
    headers = {"Authorization": f"Bearer {API_KEY}"}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body, ensure_ascii=False).encode("utf-8")
    req = urllib.request.Request(BASE_URL + path, data=data, method=method, headers=headers)
    try:
        with urllib.request.urlopen(req, timeout=60) as resp:
            return json.loads(resp.read().decode("utf-8"))
    except HTTPError as exc:
        error_body = exc.read().decode("utf-8", errors="replace")
        raise RuntimeError(f"HTTP {exc.code}: {error_body}") from exc


created = request(
    "POST",
    "/hailuo/v2/video_generation",
    {
        "model": "MiniMax-H3",
        "content": [{"type": "text", "text": "黄昏时分，一只橘猫在雨后的屋顶上慢慢走过，远处城市灯光亮起"}],
        "resolution": "768P",
        "duration": 5,
        "ratio": "16:9",
    },
)
task_id = created["task_id"]
print("task_id:", task_id)

deadline = time.monotonic() + TIMEOUT
while True:
    task = request("GET", f"/hailuo/v2/query/video_generation/{task_id}")["task"]
    status = task["status"]
    print("status:", status)

    if status == "succeeded":
        # 下载链接不需要 Authorization；带上 User-Agent，部分 CDN 会拒绝 Python 默认的 UA。
        download = urllib.request.Request(task["content"]["url"], headers={"User-Agent": "h3-client/1.0"})
        with urllib.request.urlopen(download, timeout=300) as resp, open("h3-output.mp4", "wb") as f:
            f.write(resp.read())
        print("已保存 h3-output.mp4")
        break
    if status == "failed":
        raise RuntimeError(f"任务失败（费用已退回）：{json.dumps(task.get('error'), ensure_ascii=False)}")
    if time.monotonic() >= deadline:
        raise TimeoutError(f"任务 {task_id} 超过 30 分钟仍未完成，可以继续用同一个 task_id 查询")
    time.sleep(POLL_INTERVAL)
```

## API 参考

### 请求约定

| 配置项 | 值 |
| - | - |
| Base URL | `https://api.laozhang.ai` |
| 认证方式 | `Authorization: Bearer $LAOZHANG_API_KEY` |
| 请求格式 | `application/json` |
| 轮询间隔 | 建议 10 秒 |
| 客户端总超时 | 建议 30 分钟 |

```text theme={null}
POST https://api.laozhang.ai/hailuo/v2/video_generation
GET  https://api.laozhang.ai/hailuo/v2/query/video_generation/{task_id}
```

### 请求体

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | 固定为 `MiniMax-H3` |
| `content` | array | 是 | 恰好一条文本，加上可选的素材，见下表 |
| `resolution` | string | 是 | `768P` 或 `2K`（大写） |
| `duration` | integer | 是 | 4–15 的整数秒，不能传字符串或小数 |
| `ratio` | string | 是 | `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` 或 `adaptive` |

`ratio` 取 `adaptive` 时跟随图片比例，只有文字或只有音频的请求不能用。768P 下 16:9 输出 1344×768，2K 下 16:9 输出 2560×1440。

### `content[]` 素材

| `type` | `role` | 链接字段 | 数量上限 |
| - | - | - | - |
| `text` | — | `text`，最长 7000 字符 | 1 条 |
| `image_url` | `first_frame`、`last_frame` 或 `reference_image` | `image_url.url` | 9 张 |
| `video_url` | `reference_video` | `video_url.url` | 3 段，合计不超过 15 秒 |
| `audio_url` | `reference_audio` | `audio_url.url` | 3 段 |

只有一张图片时可以省略 `role`，按首帧处理；两张及以上必须写明 `role`。

### 任务状态

| `task.status` | 是否终态 | 客户端处理 |
| - | - | - |
| `queued` | 否 | 排队中，继续轮询，不要重新提交 |
| `running` | 否 | 生成中，继续轮询 |
| `succeeded` | 是 | 从 `task.content.url` 下载 MP4 |
| `failed` | 是 | 读取 `task.error.message`，费用已退回 |

高峰时段任务可能先停在 `queued`，空出生成资源后会按提交顺序自动开始。排队超过 30 分钟仍未开始的任务会转为 `failed` 并退回费用。

## 常见错误

| 现象 | 常见原因 | 处理方式 |
| - | - | - |
| 400 `分辨率必须为 768P 或 2K。` | `resolution` 传了其他值或小写 `768p` | 改为 `768P` 或 `2K` |
| 400 `生成时长必须为 4 至 15 秒的整数。` | `duration` 超出范围，或传了字符串、小数 | 传 4–15 的整数 |
| 400 `参考音频不能单独使用` | 请求里只有文本和参考音频 | 加一张参考图或一段参考视频 |
| 400 `MiniMax-H3 only supports POST /hailuo/v2/video_generation.` | 请求发到了 `/v1/video/generations` | 改用本页的创建任务端点 |
| `failed`，`cannot download media URL` | 素材链接无法从公网下载（404、防盗链、内网地址） | 换成可直接下载的 HTTPS 链接后重新提交 |
| 503 `The video service is busy. Please retry later.` | 服务暂时繁忙，请求未创建任务 | 稍等后重试，这次请求不扣费 |
| `Current group ... has no available channels for model ...` | 令牌分组不是 `default`、`vip`、`svip`，或模型名大小写写错 | 检查令牌分组和 `MiniMax-H3` 的拼写 |
| `... under billing mode [pay-per-request]` | 令牌的计费模式是按次计费 | 把令牌改为按量优先或按量计费 |

生产接入建议保存创建响应里的 `task_id` 和最终任务详情，便于核对扣费和联系支持团队（[hi@laozhang.ai](mailto:hi@laozhang.ai)）。

## 常见问题

### 一个 5 秒视频大约多少钱？

768P 是 \$0.25，2K 是 \$0.40，费用按秒线性增加，15 秒 768P 是 \$0.75。带参考视频时再加上参考视频秒数的费用，带超过 5 张参考图时每多一张加 \$0.03，规则见[计费与价格](#计费与价格)。

### 768P 和 2K 怎么选？

先用 768P 和 4–5 秒的短时长调提示词和构图，满意后再出 2K 或更长的正式版本。2K 每秒贵 \$0.03，生成时间也更长，适合需要大屏播放或二次剪辑的成片。

### 能用 OpenAI 格式的 `/v1/videos` 调用吗？

不能。MiniMax H3 的首尾帧、多参考图、参考视频和参考音频都依赖 `content[]` 结构，老张API只开放 `/hailuo/v2` 原生接口。发到 `/v1/videos` 或 `/v1/video/generations` 的请求会被拒绝，不会扣费。

### 视频有声音吗？能关掉吗？

每条视频都自带立体声音轨，配乐和音效由提示词和参考音频决定，目前没有关闭参数。不需要声音时，下载后自行去掉音轨即可。

### 超时或失败后可以直接重新提交吗？

先查任务状态。客户端等待超时不代表任务失败，继续用同一个 `task_id` 查询即可；重新提交会创建新任务并再次计费。只有 `task.status` 为 `failed` 时才需要修正请求后重新创建，失败任务的费用已经退回。

### 视频链接能保存多久？

7 天。过期后链接失效，同一个任务也无法重新下载，请在任务完成后及时转存。

## 相关文档

* [Wan 2.7 与 Wan 3.0 视频生成 API](https://docs.laozhang.ai/api-capabilities/wan-video-generation.md)
* [Seedance 2.0 视频生成 API](https://docs.laozhang.ai/api-capabilities/seedance2-video-generation.md)
* [模型与价格总表](https://docs.laozhang.ai/models.md)
* [调用日志](https://docs.laozhang.ai/faq/call-logs.md)
* [MiniMax 按量计费价格](https://platform.minimax.io/docs/guides/pricing-paygo)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.