# MiniMax H3 (Hailuo) API: access, pricing and code

> Is there a MiniMax Hailuo API? Call the official MiniMax H3 API on Runway Dev with one key: price per second, inputs and code in curl, Node and Python.

Author: Runway · Published: 2026-11-09 · Updated: 2026-11-09 · Source: https://dev.runway.com/learn/minimax-h3-api

## Summary

There is a MiniMax Hailuo API, and Runway Dev gives you the official MiniMax H3 API from MiniMax, self-serve with an API key.\
\
MiniMax H3, often called Hailuo 3, generates video with sound from a prompt, from frames or from reference images, videos and audio, and works from a clip you send.\
\
This page covers access, pricing, inputs and code, and how your coding agent can build the integration for you.

## What is MiniMax H3?

MiniMax H3 is MiniMax's video generation model, the successor to its Hailuo models, and the one people mean when they search for Hailuo 3. It makes clips of 5 to 15 seconds from a prompt of up to 6,000 characters, at 768p or 2K, and it understands text, images, video and audio in one request: a still can set the first and last frame, and reference images, clips and sound can set a character, a camera move, a style or a voice.

![A white lighthouse on a rocky headland at dusk as waves break against the rocks below and its beam sweeps across the sea](https://d3phaj0sisr2ct.cloudfront.net/devportal/learn/minimax-h3-api-hero-lighthouse-cc361430.mp4 'One text-to-video request to MiniMax H3 at 2K, with its sound.')

```text
One continuous locked-off wide shot, with no cuts, of a white lighthouse on a rocky headland at dusk. Waves roll in and break against the rocks below, sending up spray, while the lighthouse beam sweeps slowly across the darkening sea. No people. Audio: waves crashing on the rocks and a steady wind.
```

MiniMax H3 frames landscape, portrait, square and wide 21:9 clips, or takes its shape from your inputs.

## What are the ways to use MiniMax H3 on Runway Dev?

MiniMax H3 runs on Runway Dev four ways, all from one account:

| Way in                                                                                                                 | Best for                                                                                          | What you need                                                   |
| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| [Playground](https://dev.runway.com/endpoints/text_to_video?modelId=hailuo3)                                           | Trying a prompt, then copying the request as code                                                 | A Runway Dev account                                            |
| [API](https://docs.dev.runwayml.com/guides/using-the-api/) and [SDKs](https://docs.dev.runwayml.com/api-details/sdks/) | Calling MiniMax H3 from your own code                                                             | An API key, plus the Node or Python SDK if you want one         |
| [Coding agent](https://dev.runway.com/learn/build-with-your-coding-agent)                                                                    | Having Claude Code, Codex or Cursor build the API integration into your product, tool or pipeline | The Runway Dev MCP and skills, and an API key for live calls    |
| [Workflows](https://dev.runway.com/workflows)                                                                                                | MiniMax H3 as one step with other models, run with one API call                                   | A workflow built in the Runway app and published as an endpoint |

MiniMax H3 is also available in [Model Router](https://dev.runway.com/model-routers), a saved config you send with the request instead of a model ID. You set what to optimize for (cost, quality or latency), a maximum cost per generation and the models allowed, and the router picks one for each request sent to `POST /v1/generate/video`.

## How do you get API access to MiniMax H3?

You get API access to MiniMax H3 with a Runway Dev account and an API key:

1. Create an account at https://dev.runway.com.
2. Create an API key in your project's dashboard.
3. Add credits to your project's balance.
4. Store the key in your environment as `RUNWAYML_API_SECRET`.
5. Send a request with `"model": "hailuo3"` and the `X-Runway-Version` header to one of its endpoints. The code below is ready to run.

## How much does the MiniMax H3 API cost?

The MiniMax H3 API on Runway Dev is billed per second of output, at a rate set by the resolution: 15 credits ($0.15) per second at 2K, with a lower rate at 768p. Reference images, keyframes and reference video add to it, as the table shows.

| Resolution | Credits | USD |
| --- | --- | --- |
| 768p | 10 credits per second | $0.10 per second |
| 2K | 15 credits per second | $0.15 per second |

- Minimum 5 seconds per generation.
- Each reference image or keyframe adds 2 credits ($0.02), and reference video is billed per second at the same rate as output.

Prices current as of November 10, 2026. 1 credit = $0.01.

![Mist drifts between green rice terraces on a hillside at sunrise as the camera glides forward over the water-filled paddies](https://d3phaj0sisr2ct.cloudfront.net/devportal/learn/minimax-h3-api-price-terraces-e335b0c7.mp4 'MiniMax H3 at 2K, its largest size: 15 credits ($0.15) per second at 2K.')

```text
One continuous slow aerial shot, with no cuts, gliding forward over green rice terraces on a hillside at sunrise, low mist drifting between the terraces and the water in the paddies catching the light. No people. Audio: birdsong and a light breeze.
```

How the billing works:

- **Output seconds are billed at the resolution's rate.** Sound adds nothing.
- **Inputs add to the price.** Each reference image or keyframe adds a fixed charge, and each second of reference video is billed at the output rate. Reference audio adds nothing.
- **`resolution` sets the rate.** MiniMax H3 defaults to 2K, so a request that leaves it out is billed at that rate.
- **A request rejected with a 400 costs nothing.** Fields and values are checked before a task is created, so a wrong one isn't billed.
- **A task that fails input moderation (`SAFETY.INPUT.*`) is still charged.** See [task failures](https://docs.dev.runwayml.com/errors/task-failures) for what each failure means.

Every rate is also listed on [dev.runway.com/pricing](https://dev.runway.com/pricing) and in the [docs pricing guide](https://docs.dev.runwayml.com/guides/pricing/).

## What inputs does MiniMax H3 accept?

MiniMax H3 accepts a prompt of up to 6,000 characters on every endpoint, a duration of 5 to 15 seconds and up to 9 images, 3 videos and 3 audio clips as references, with at most 12 reference files in one request. Each endpoint uses them differently.

On `POST /v1/text_to_video` you send a `promptText`, and optionally a `ratio`, a `resolution` and a `duration`. Add `references` to bring a character, an object or a style in from images, `referenceVideos` to borrow motion, camera work or style from clips, and `referenceAudio` to set a voice or a sound. Audio steers the clip only next to an image or video reference, never on its own.

On `POST /v1/image_to_video` the `promptImage` sets how the stills are used. A single URL is the first frame. A list with `position` set to `first`, and optionally `last`, gives the start and end of the clip. A list with no `position` on any image is a set of reference images, which can come with `referenceAudio`. The two modes don't mix in one request.

![A white goose in a small knitted red scarf standing side-on against a plain gray background](https://d3phaj0sisr2ct.cloudfront.net/devportal/learn/images/minimax-h3-api/goose-reference-eec54337.jpg 'Reference image')

![The white goose in its red scarf waddles along a cobblestone canal path toward the camera, stops and flaps its wings](https://d3phaj0sisr2ct.cloudfront.net/devportal/learn/minimax-h3-api-refs-goose-860a71e7.mp4 'The goose from the reference image, in the scene the prompt describes.')

```text
Wide shot of the white goose in the red scarf from the reference image waddling along a cobblestone path beside a canal in the morning, toward the camera, then stopping and flapping its wings once. Audio: webbed feet on the stones, a single honk and water lapping against the canal wall.
```

On `POST /v1/video_to_video` you send the clip to work from as `promptVideo` and say what to make of it in `promptText`. It can come with reference images, more reference videos and reference audio, within the same totals.

Here is every field, by endpoint:

### `POST /v1/image_to_video`

| Field | Accepts |
| --- | --- |
| `model` (required) | `hailuo3` |
| `promptImage` (required) | One image, or a list of up to 9 images, each with an optional `position` of `first` or `last` (a `last` frame needs a `first` one) |
| `promptText` (required) | Text, 1 to 6,000 characters |
| `resolution` | One of `768p`, `2k`, `768P` or `2K` |
| `duration` | Whole number from 5 to 15 |
| `ratio` | One of `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4` or `9:16` |
| `referenceAudio` | A list of up to 3 audio clips |

### `POST /v1/text_to_video`

| Field | Accepts |
| --- | --- |
| `model` (required) | `hailuo3` |
| `promptText` (required) | Text, 1 to 6,000 characters |
| `resolution` | One of `768p`, `2k`, `768P` or `2K` |
| `duration` | Whole number from 5 to 15 |
| `ratio` | One of `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4` or `9:16` |
| `references` | A list of up to 9 images |
| `referenceVideos` | A list of up to 3 videos |
| `referenceAudio` | A list of up to 3 audio clips |

### `POST /v1/video_to_video`

| Field | Accepts |
| --- | --- |
| `model` (required) | `hailuo3` |
| `promptVideo` (required) | One video |
| `promptText` (required) | Text, 1 to 6,000 characters |
| `resolution` | One of `768p`, `2k`, `768P` or `2K` |
| `duration` | Whole number from 5 to 15 |
| `ratio` | One of `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4` or `9:16` |
| `references` | A list of up to 9 images |
| `referenceVideos` | A list of up to 2 videos |
| `referenceAudio` | A list of up to 3 audio clips |

Images, videos and audio go in as an HTTPS URL, a `runway://` URI from an [upload](https://docs.dev.runwayml.com/assets/uploads) or a data URI; [inputs](https://docs.dev.runwayml.com/assets/inputs) lists sizes and formats. Each table shows what a field accepts on its own. Rules that combine fields are checked when the task is submitted, and the [API reference](https://docs.dev.runwayml.com/api/) has them in full.

A few rules change what you send:

- **`adaptive` needs a reference.** `ratio: adaptive` lets the clip take the shape of your inputs, so a text-only request has to name a ratio. Leaving `ratio` out uses 16:9.
- **Reference clips have a length window.** Each reference video or audio clip runs at least 2 seconds, and the clips of each kind run at most 15 seconds together, the `promptVideo` included.
- **Images have an aspect-ratio range.** MiniMax H3 pads stills that fall outside the range it renders, within limits. See [inputs](https://docs.dev.runwayml.com/assets/inputs) for formats and file sizes.
- **Unknown fields return a 400.** The request schema is strict, so a field name from another API, such as `aspect_ratio` or `first_frame_image`, is rejected rather than ignored.

## How do you use the MiniMax H3 API?

You use the MiniMax H3 API by sending `hailuo3` as the model to one of its endpoints. This example request, in curl, Node and Python, makes a clip with sound from text with `POST /v1/text_to_video`, and the other fields keep their defaults:

**curl**

```bash
curl -X POST https://api.dev.runwayml.com/v1/text_to_video \
  -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
  -H "X-Runway-Version: 2024-11-06" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo3",
    "promptText": "Wide shot of an empty desert road at sunset: a vintage red pickup truck drives toward the camera from the far end of the road, raising a trail of dust behind it, red rock cliffs on both sides. Audio: the engine growing louder and tires on gravel."
  }'

# The response carries the task id. Poll the task until it finishes:
curl https://api.dev.runwayml.com/v1/tasks/$TASK_ID \
  -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
  -H "X-Runway-Version: 2024-11-06"
```

**Node.js**

```javascript
import RunwayML, { TaskFailedError } from '@runwayml/sdk';

// Reads your API key from RUNWAYML_API_SECRET.
const client = new RunwayML();

try {
  const task = await client.textToVideo
    .create({
      model: 'hailuo3',
      promptText: 'Wide shot of an empty desert road at sunset: a vintage red pickup truck drives toward the camera from the far end of the road, raising a trail of dust behind it, red rock cliffs on both sides. Audio: the engine growing louder and tires on gravel.',
    })
    .waitForTaskOutput();
  console.log(task.output);
} catch (error) {
  if (error instanceof TaskFailedError) {
    console.error(error.taskDetails);
  } else {
    throw error;
  }
}
```

**Python**

```python
from runwayml import RunwayML, TaskFailedError

# Reads your API key from RUNWAYML_API_SECRET.
client = RunwayML()

try:
    task = client.text_to_video.create(
        model="hailuo3",
        prompt_text="Wide shot of an empty desert road at sunset: a vintage red pickup truck drives toward the camera from the far end of the road, raising a trail of dust behind it, red rock cliffs on both sides. Audio: the engine growing louder and tires on gravel.",
    ).wait_for_task_output()
    print(task.output)
except TaskFailedError as error:
    print(error.task_details)
```

![A vintage red pickup truck drives toward the camera down an empty desert road at sunset, raising a trail of dust between red rock cliffs](https://d3phaj0sisr2ct.cloudfront.net/devportal/learn/minimax-h3-api-code-truck-3e9101a8.mp4 'The request above, as MiniMax H3 returns it.')

Generation is asynchronous:

- **The create request returns a task ID right away**, and the video is made in the background.
- **Poll `GET /v1/tasks/{id}` with backoff** until the status is `SUCCEEDED`, `FAILED` or `CANCELLED`. `THROTTLED` means the task is waiting in a queue, not rejected.
- **Output URLs are temporary**, so download the video when the task succeeds. See [outputs](https://docs.dev.runwayml.com/assets/outputs).
- **The SDKs poll for you.** `waitForTaskOutput()` and `wait_for_task_output()` raise `TaskFailedError` with the task's details when it fails. They also stop waiting after a default timeout while the task keeps running, so for long clips at 2K pass a longer timeout or keep polling the task ID.
- **To use your own rules instead of one fixed model**, send a [Model Router](https://dev.runway.com/learn/choosing-the-right-model)'s `configId` to `POST /v1/generate/video` in place of the model. Add `dryRun` to see which model it picks without creating a task.

## Why does a MiniMax H3 API request fail?

A request to MiniMax H3 fails with a 400 when a field is wrong, and a task fails with a failure code that names the cause. The common ones:

- **A 400 on `ratio: adaptive`**: the request has no image or video reference. Name a ratio such as `16:9` for text-only requests.
- **A 400 on `promptImage`**: positioned frames and unpositioned reference images are mixed in one list, a `last` frame comes without a `first`, or keyframes are sent with `referenceAudio`.
- **A 400 on audio references**: `referenceAudio` is the only reference in the request. Add an image or a video reference.
- **A 400 on the number of references**: images, videos and audio together go past 12 files, or one kind goes past its own cap.
- **A reference clip rejected for its length**: each one has to run at least 2 seconds, and the clips of each kind at most 15 seconds together.
- **`SAFETY.INPUT.*`**: content moderation rejected an input. The task is charged and shouldn't be retried as is: change the inputs first.
- **`INTERNAL.BAD_OUTPUT.01`**: the output failed a quality check, often because of logos, watermarks or text in an input image. Remove them and retry.
- **`ASSET.INVALID`**: an input's dimensions, length or format are outside what the model takes. Check it against [inputs](https://docs.dev.runwayml.com/assets/inputs) and fix it before retrying.
- **`THIRD_PARTY.UNAVAILABLE`**: the model's provider didn't return the video, because of an outage or load. Wait, then retry.

## What does Runway Dev add when you call MiniMax H3?

Runway Dev serves MiniMax H3 next to [Runway's own models and other labs' models](https://dev.runway.com/models/catalog), behind one API key and one credit balance: you build with a single key and pay a single bill, instead of an account, a key and an invoice per lab.

A coding agent can do the MiniMax H3 integration for you on Runway Dev, end to end. Connect the [Runway Dev MCP](https://docs.dev.runwayml.com/guides/mcp/) and the agent works from your live account: the models your project can call with their current prices and input limits, your credit balance and the record behind any task. It writes the integration against what the API accepts today, and when a task fails it looks up the reason and fixes it. The [Runway Dev skills](https://github.com/runwayml/skills) show the agent how to integrate with the official SDKs and how to build with models, Model Routers, Recipes and Workflows.

With [Workflows](https://dev.runway.com/workflows), MiniMax H3 becomes one step of a larger pipeline: chain it with [Runway's own models and other labs' models](https://dev.runway.com/models/catalog), for images, video and audio, and run the whole pipeline with a single API call. Workflows don't need to be built by a developer. A creative or marketing teammate builds and tests one visually in the [Runway app](https://app.runwayml.com/workflows) ([how Workflows work](https://help.runwayml.com/hc/en-us/articles/45763528999699-Introduction-to-Workflows)), then [publishes it as an endpoint](https://help.runwayml.com/hc/en-us/articles/50682960972947-Publishing-a-Workflow-as-an-Endpoint) that your code calls. When the team updates the workflow, your code keeps calling the same endpoint.

## FAQ

**Is there a MiniMax Hailuo API?**

There is a MiniMax Hailuo API, from two places. MiniMax sells API access to its video models, MiniMax H3 included, on its own [developer platform](https://platform.minimax.io/docs/guides/video-generation), which we checked on November 9, 2026. Runway Dev serves the official MiniMax H3 model through its API, and [MiniMax H3 Max](https://dev.runway.com/learn/minimax-h3-max-api), on the same key and credit balance as every other model on Runway Dev.

**Is the MiniMax H3 API on Runway Dev the official model?**

Runway Dev's MiniMax H3 API runs the official MiniMax H3 model from MiniMax. You call it with your Runway Dev API key and the model ID `hailuo3`, like every other model on Runway Dev.

**Do I need a MiniMax account to use the MiniMax H3 API?**

You don't need a MiniMax account to use the MiniMax H3 API on Runway Dev: a Runway Dev account and API key are all you need, and MiniMax H3 is paid from the same credit balance as every other model. To have a coding agent write the integration, connect the Runway Dev MCP and install the Runway Dev skills: the agent builds it from your live account, with the prices and input limits your project has today.

**What does MiniMax H3 cost per second at 768p and 2K?**

On Runway Dev, MiniMax H3 costs 15 credits ($0.15) per second at 2K and 10 credits ($0.10) per second at 768p. Reference images, keyframes and reference video add to the price. Prices are current as of November 10, 2026.

**What is the MiniMax H3 model ID on Runway Dev?**

The MiniMax H3 model ID on Runway Dev is `hailuo3`. You send it as `model` to any of `POST /v1/image_to_video`, `POST /v1/text_to_video` and `POST /v1/video_to_video`.

**What is the difference between MiniMax H3 and MiniMax H3 Max?**

MiniMax H3 takes text, frames and reference images, videos and audio, works from a clip you send and renders up to 2K. [MiniMax H3 Max](https://dev.runway.com/learn/minimax-h3-max-api) works from a prompt or from a first and last frame at up to 768p, and returns a clip in seconds rather than minutes.

**Does MiniMax H3 generate audio through the API?**

MiniMax H3 generates sound with the picture, in the same pass: the sound effects and ambient sound of the scene you describe. It has no field to turn it off, and the rate is the same either way.

**Can MiniMax H3 do image to video and video to video through the API?**

MiniMax H3 takes image-to-video, text-to-video and video-to-video through the API: send `promptImage` to `POST /v1/image_to_video` for a first and last frame or reference images, and `promptVideo` to `POST /v1/video_to_video` to work from a clip you have.

**Can I use MiniMax H3 without writing code?**

You can use MiniMax H3 on Runway Dev without writing code yourself. The playground sends a request from a form and gives it back as code, and a coding agent connected to the Runway Dev MCP writes the integration for you. A creative or marketing teammate can also build a workflow around MiniMax H3 in the Runway app and publish it as an endpoint your app calls.

**Does the same Runway Dev API key work for MiniMax H3 and other models?**

One Runway Dev API key calls MiniMax H3 and every other model your project can use, Runway's own and other labs', with the same SDKs, task flow and credit balance. Switching models means changing the `model` field, or the rules of a Model Router.

**Why did my MiniMax H3 request fail with `SAFETY.INPUT.TEXT`?**

`SAFETY.INPUT.TEXT` means content moderation rejected an input of your request; the suffix hints at the prompt but may not match. The task is charged and shouldn't be retried as is, so change the prompt or inputs before you send it again.

**Can I switch from MiniMax H3 to another video model without changing my code?**

A Model Router lets you change models without touching your code. Send its `configId` to `POST /v1/generate/video`, and change the models it may use, its priority or its cost cap in the router.