> ## 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 (Hailuo) Video API and Pricing

> Call MiniMax H3 on LaoZhang API for text, first/last-frame, and reference-to-video tasks, poll and download the MP4, and see per-second 768P and 2K prices.

MiniMax H3 is MiniMax's omni-modal video model: one model takes text, images, video, and audio as input and returns video with its own music and sound effects. LaoZhang API bills it by video length, \$0.05 per second at 768P, and any standard token group can call it without a dedicated video group.

| Item | Details |
| - | - |
| Model ID | `MiniMax-H3` (case-sensitive) |
| Create a task | `POST /hailuo/v2/video_generation` |
| Get a task | `GET /hailuo/v2/query/video_generation/{task_id}`; download the MP4 from `task.content.url` when it succeeds |
| Token groups | `default`, `vip`, or `svip`, with the Usage first billing mode |
| Price | 768P \$0.05/s, 2K \$0.08/s, charged for the requested duration; see [Pricing](#pricing) |
| Output | 4–15 whole seconds, `768P` or `2K`, stereo soundtrack included |
| Retention | Video links stay available for 7 days |
| Route | Runs on MiniMax's open H3 model weights in an independent deployment, not through MiniMax's official API, so it has its own pricing |

> [!WARNING]
>
> MiniMax H3 is available only through the native `/hailuo/v2` endpoints above. Requests sent to `/v1/videos` or `/v1/video/generations` are rejected and not charged.

![MiniMax H3 text-to-video sample: an orange cat walking across a wet rooftop at dusk with city lights behind it](https://mintcdn.com/laozhangai-edd05f2c/McVdWQYpbAhpR0pV/images/samples/minimax-h3-en-t2v.jpg?fit=max\&auto=format\&n=McVdWQYpbAhpR0pV\&q=85\&s=30be48ac6cea982fc081d900634b5277)

Output of the text-to-video example below: 768P, 5 seconds, 16:9

## Create a token

In [Token management](https://api.laozhang.ai/token), add a token with these settings:

| Setting | Value |
| - | - |
| Group | `default`, `vip`, or `svip`; the price is the same in all three |
| Billing mode | Usage first (recommended) or Usage-based; Per-call tokens can't call this model |
| Tip | Use a separate token for video so you can match charges to tasks in the call logs |

You don't need a MiniMax account or a dedicated video group.

## Pricing

MiniMax H3 is billed by video length. Prices from October 24, 2026:

| Item | LaoZhang API | MiniMax official API |
| - | -: | -: |
| 768P output | \$0.05 / s | \$0.08 / s |
| 2K output | \$0.08 / s | \$0.13 / s |
| Reference video | Per second at the output resolution's rate | Per second at the output resolution's rate |
| Reference images (first 5 free) | \$0.03 each from the 6th | \$0.04 each from the 6th |
| Reference audio | Free | Free |

Official prices are from [MiniMax pay-as-you-go pricing](https://platform.minimax.io/docs/guides/pricing-paygo) (MiniMax-H3, checked October 24, 2026). Landscape, portrait, and square videos cost the same; only resolution and seconds matter.

How the billed seconds are counted:

* Output: the `duration` you request. Clips usually run 0.1–0.5 seconds longer than requested at no extra cost.
* Reference video: its length, rounded up to the next whole second; a 5.8-second clip counts as 6 seconds.
* Reference images: images beyond the first 5 in one task are charged individually, and first-frame and last-frame images count toward the total.

Example costs for a single video:

* 768P, 5-second text-to-video: 5 × \$0.05 = \$0.25
* 2K, 10-second text-to-video: 10 × \$0.08 = \$0.80
* 768P, 4 seconds with a 6-second reference video: (4 + 6) × \$0.05 = \$0.50

When you create a task, duration × rate is reserved from your balance, together with any images beyond the first five. For tasks with a reference video, the reference seconds are charged once the task finishes, so the call logs show a second settlement entry.

Failed tasks are fully refunded, and requests rejected at submission are not charged. Resubmitting creates a new task that is billed again, so keep a mapping from your business ID to the `task_id`. The [call logs](https://api.laozhang.ai/log) show the exact charge for every task.

## How it works

**1. Create a task**

Send `POST /hailuo/v2/video_generation` with a JSON body containing:

* `model`: `MiniMax-H3`
* `content`: one text item plus optional image, video, or audio inputs
* `resolution`, `duration`, and `ratio`

Save the `task_id` from the response.

**2. Poll the task**

Call `GET /hailuo/v2/query/video_generation/{task_id}` every 10 seconds and read `task.status`. A 4–5 second 768P video usually finishes in about a minute; 2K and reference-video tasks take longer. Set an overall client timeout of 30 minutes.

**3. Download the video**

When `task.status` is `succeeded`, download the MP4 from `task.content.url`. The link stays available for 7 days and doesn't need an `Authorization` header.

## Set up

The cURL examples use `jq` to read fields from responses (install it with `brew install jq` on macOS). Set your key and base URL first:

```bash theme={null}
export LAOZHANG_API_KEY="your-laozhang-api-key"
export BASE_URL="https://api.laozhang.ai"
```

## Generate a video from text

```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": "At dusk, an orange cat walks slowly across a rain-soaked rooftop as the city lights come on, slow tracking shot, cinematic lighting"
      }
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9"
  }' | tee h3-create.json

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

A successful request returns only the task ID:

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

Text-only requests need a fixed `ratio`; `adaptive` isn't accepted without an image.

## Animate from a first frame or first and last frames

Use `first_frame` to set the opening shot, and add `last_frame` to set the closing shot as well. With `ratio` set to `adaptive`, the output follows the first frame's aspect ratio:

```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": "The dog keeps running along the beach as the camera follows" },
      { "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"
  }'
```

Images can be public HTTPS URLs or Base64 data URLs such as `data:image/jpeg;base64,...`. For a first frame only, drop the `last_frame` item.

## Generate from reference images, video, and audio

References let you put a specific character or object in the scene, reuse the motion and camera work of a clip, or follow the rhythm of an audio track. Refer to them in the prompt by type and order: the first reference image is `<Picture 1>`, the first reference video is `<Video 1>`, and the first reference audio is `<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": "The character from <Picture 1> walks along a park path, with camera movement like <Video 1> and pacing that follows <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"
  }'
```

When combining references:

* Mix reference images, videos, and audio freely, but audio can't be the only reference; add at least one reference image or video.
* First and last frames can't be used in the same request as references.
* Video and audio inputs must be public HTTPS links the service can download directly.
* Reference video is billed per second; see [Pricing](#pricing).

## Poll and download

### Get the task

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

Run it every 10 seconds until `task.status` is `succeeded` or `failed`. A successful response:

```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` holds the billed seconds for the task: `input_seconds` is reference video, `output_seconds` is the generated video.

### Download the video

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

The link stays available for 7 days, so copy the file to your own storage soon after the task finishes.

## Minimal Python client

The script uses only the Python standard library. Set `LAOZHANG_API_KEY` before running it. It polls every 10 seconds with a 30-minute overall timeout and saves the result as `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  # seconds
TIMEOUT = 30 * 60  # 30-minute overall timeout


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).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": "At dusk, an orange cat walks slowly across a rain-soaked rooftop as the city lights come on"}],
        "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":
        # The download link needs no Authorization header. Send a User-Agent: some CDNs reject Python's default one.
        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("Saved h3-output.mp4")
        break
    if status == "failed":
        raise RuntimeError(f"Task failed (the charge was refunded): {json.dumps(task.get('error'))}")
    if time.monotonic() >= deadline:
        raise TimeoutError(f"Task {task_id} is still running after 30 minutes; keep polling the same task_id")
    time.sleep(POLL_INTERVAL)
```

## API reference

### Request basics

| Setting | Value |
| - | - |
| Base URL | `https://api.laozhang.ai` |
| Authentication | `Authorization: Bearer $LAOZHANG_API_KEY` |
| Request format | `application/json` |
| Polling interval | 10 seconds recommended |
| Client timeout | 30 minutes recommended |

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

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `model` | string | Yes | Always `MiniMax-H3` |
| `content` | array | Yes | Exactly one text item plus optional inputs; see the next table |
| `resolution` | string | Yes | `768P` or `2K` (uppercase) |
| `duration` | integer | Yes | Whole seconds from 4 to 15; strings and decimals are rejected |
| `ratio` | string | Yes | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, or `adaptive` |

`adaptive` follows the image's aspect ratio and can't be used for text-only or audio-only requests. At 16:9, 768P output is 1344×768 and 2K output is 2560×1440.

### `content[]` inputs

| `type` | `role` | Link field | Limit |
| - | - | - | - |
| `text` | — | `text`, up to 7,000 characters | 1 item |
| `image_url` | `first_frame`, `last_frame`, or `reference_image` | `image_url.url` | 9 images |
| `video_url` | `reference_video` | `video_url.url` | 3 clips, 15 seconds in total |
| `audio_url` | `reference_audio` | `audio_url.url` | 3 clips |

With a single image you can omit `role` and it's treated as the first frame. With two or more images, set `role` on each.

### Task status

| `task.status` | Final | What to do |
| - | - | - |
| `queued` | No | Waiting to start; keep polling and don't resubmit |
| `running` | No | Generating; keep polling |
| `succeeded` | Yes | Download the MP4 from `task.content.url` |
| `failed` | Yes | Read `task.error.message`; the charge has been refunded |

At busy times a task can stay `queued` for a while and starts automatically in submission order. A task that hasn't started after 30 minutes moves to `failed` and is refunded.

## Errors

| Response | Likely cause | Fix |
| - | - | - |
| 400 `分辨率必须为 768P 或 2K。` | `resolution` isn't `768P` or `2K`, or is lowercase such as `768p` | Use `768P` or `2K` |
| 400 `生成时长必须为 4 至 15 秒的整数。` | `duration` is out of range, a string, or a decimal | Send a whole number from 4 to 15 |
| 400 `参考音频不能单独使用` | The request has only text and reference audio | Add a reference image or video |
| 400 `MiniMax-H3 only supports POST /hailuo/v2/video_generation.` | The request went to `/v1/video/generations` | Use the create-task endpoint on this page |
| `failed` with `cannot download media URL` | An input link can't be fetched from the internet (404, hotlink protection, private address) | Resubmit with a directly downloadable HTTPS link |
| 503 `The video service is busy. Please retry later.` | The service is temporarily busy and no task was created | Retry shortly; this request isn't charged |
| `Current group ... has no available channels for model ...` | The token isn't in `default`, `vip`, or `svip`, or the model ID has the wrong case | Check the token group and the spelling `MiniMax-H3` |
| `... under billing mode [pay-per-request]` | The token uses the Per-call billing mode | Switch the token to Usage first or Usage-based |

Some validation messages are returned in Chinese, as shown above. In production, store the `task_id` from the create response and the final task details so you can reconcile charges or contact support ([hi@laozhang.ai](mailto:hi@laozhang.ai)).

## FAQ

### How much does a 5-second video cost?

\$0.25 at 768P and \$0.40 at 2K. Cost scales linearly with length, so 15 seconds at 768P is \$0.75. Reference video adds its seconds at the same rate, and each reference image beyond the first five adds \$0.03; see [Pricing](#pricing).

### Should I use 768P or 2K?

Iterate on the prompt and composition at 768P with 4–5 second clips, then render the final version at 2K or a longer duration. 2K costs \$0.03 more per second and takes longer to generate, so it's best kept for footage meant for large screens or further editing.

### Can I call MiniMax H3 through the OpenAI-style `/v1/videos` endpoint?

No. First and last frames, multiple reference images, reference video, and reference audio all depend on the `content[]` structure, so LaoZhang API exposes MiniMax H3 only on the native `/hailuo/v2` endpoints. Requests to `/v1/videos` or `/v1/video/generations` are rejected without charge.

### Do the videos have sound? Can I turn it off?

Every video comes with a stereo soundtrack whose music and effects follow the prompt and any reference audio. There's no parameter to disable it; strip the audio track after download if you don't need it.

### Can I resubmit after a timeout or failure?

Check the task first. A client-side timeout doesn't mean the task failed, so keep polling the same `task_id`; resubmitting creates a new task and bills it again. Only recreate the request after `task.status` is `failed`, and a failed task has already been refunded.

### How long are video links kept?

7 days. After that the link stops working and the task can't be downloaded again, so save the file when the task finishes.

## Related docs

* [Wan 2.7 and Wan 3.0 video generation API](https://docs.laozhang.ai/en/api-capabilities/wan-video-generation.md)
* [Seedance 2.0 video generation API](https://docs.laozhang.ai/en/api-capabilities/seedance2-video-generation.md)
* [Models and pricing](https://docs.laozhang.ai/en/models.md)
* [Call logs](https://docs.laozhang.ai/en/faq/call-logs.md)
* [MiniMax pay-as-you-go pricing](https://platform.minimax.io/docs/guides/pricing-paygo)


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