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

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.

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:

MiniMax H3 is also available in Model Router, 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.

• 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.

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 for what each failure means.

Every rate is also listed on dev.runway.com/pricing and in the docs pricing guide.

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.

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

POST /v1/text_to_video

POST /v1/video_to_video

Images, videos and audio go in as an HTTPS URL, a runway:// URI from an upload or a data URI; 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 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 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

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

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

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)

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.
• 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’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 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, 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 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 show the agent how to integrate with the official SDKs and how to build with models, Model Routers, Recipes and Workflows.

With Workflows, MiniMax H3 becomes one step of a larger pipeline: chain it with Runway’s own models and other labs’ models, 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 (how Workflows work), then publishes it 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, which we checked on November 9, 2026. Runway Dev serves the official MiniMax H3 model through its API, and MiniMax H3 Max, 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 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.