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

> ## Agent Instructions
> Authenticate every request with your API key in the `X-API-Key` header or `Authorization: Bearer`. Keys start with `sk-nunchux-`.
> Image generation is synchronous: the image is in the response.
> Video generation is asynchronous: submit the job, poll its task until it reaches a terminal status, then download the output promptly, because output URLs expire.

# MiniMax H3 Fast

> Generate a video clip with its own soundtrack from a prompt, from a first and last frame, or from reference images, clips and audio. The clip is in the response.

# MiniMax H3 Fast

MiniMax H3 Fast is MiniMax H3 on the Nunchux engine. It generates a video clip and its soundtrack together, in one request. The request is synchronous. There is no task to poll.

Two model IDs serve it. They share one request shape, and the `refs` list carries the inputs:

| Model | Model ID | Task | Inputs in `refs` |
| - | - | - | - |
| MiniMax H3 Fast | `nunchux-minimax-h3-fast-fl2va` | Text-to-video, or a clip that starts or ends on your frames | None, or a first frame, a last frame, or both |
| MiniMax H3 Fast | `nunchux-minimax-h3-fast-ref2va` | Reference-to-video | Reference images, reference clips and audio tracks |

Both models have the Radical Speed and Radical Value tiers. A clip is 4 to 15 seconds long, with a short edge of 480 or 768 pixels.

For MiniMax's own H3 API, with its asynchronous task flow and 2K output, see [MiniMax H3](https://docs.nunchux.ai/partner-models/minimax.md).

## Endpoint

```text theme={"system"}
POST https://api.nunchux.com/v1/videos/generations
```

The older path `/v1/video/generations` still works, with the same result and the same billing, but it is deprecated. Use `/v1/videos/generations` in new code.

## Request

Every request must include your API key and a JSON content type. See [Authentication](https://docs.nunchux.ai/authentication.md).

**X-API-Key** `string` *required*

Your API key.

**Content-Type** `string` *required*

Must be `application/json`.

**model** `string` *required*

The model that generates the clip.

Options: `nunchux-minimax-h3-fast-fl2va`, `nunchux-minimax-h3-fast-ref2va`

**prompt** `string` *required*

A text description of the clip. Describe the shot, what changes during the clip, and the sound. With references, name them by their order: Image 1, Video 1, Audio 1.

**tier** `string` (default: radical\_speed)

The balance of speed and cost. See [Performance tiers](https://docs.nunchux.ai/performance-tiers.md).

Options: `radical_speed`, `radical_value`

**duration** `number` (default: 5.1667)

The clip length in seconds. Range: 4 to 15. The model renders at 24 frames per second on a fixed frame grid, so the clip can run up to two-thirds of a second longer than your value. A request for 4 seconds returns a 4.46 second clip. The response gives the length of the clip.

**refs** `array`

The input media, in order. Each item names its role and a public `https` URL. On `nunchux-minimax-h3-fast-fl2va`, send no `refs` for text-to-video. See [Inputs](#inputs) for the roles each model takes.

**Item properties**

**role** `string` *required*

What the input is for.

Options: `first_frame`, `last_frame`, `reference_image`, `reference_video`, `reference_audio`

**url** `string` *required*

A public `https` URL of the file. An `http` URL returns a 400.

**extra** `object`

The shape of the clip.

**properties**

**short\_edge** `integer` (default: 768)

The short edge of the clip in pixels. 768 costs more per second than 480.

Options: `480`, `768`

**aspect\_ratio** `string` (default: 16:9)

The shape of the clip. The long edge follows the ratio, rounded to a multiple of 32, and the clip stays under about one megapixel. At 16:9, 480 gives 864x480 and 768 gives 1344x768. At 21:9, 768 gives 1536x672.

Options: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`

**prompt\_expansion** `string` (default: off)

With any mode other than `off`, the prompt is rewritten into a detailed shot description before the clip renders. The rewriter sees your frames, images and clips. `fast` adds a few seconds. `standard`, `balanced` and `quality` give fuller rewrites and take longer. The response returns the rewritten prompt as `revised_prompt`.

Options: `off`, `fast`, `standard`, `balanced`, `quality`

**seed** `integer`

The random seed. When you do not send a seed, the model selects one and returns it in the response. The same seed with the same parameters gives the same result.

**content\_moderation** `boolean` (default: true)

Whether Nunchux's content filter checks this request. Only accounts approved to turn moderation off may send `false`. Others get a 403. See [Content moderation](https://docs.nunchux.ai/content-moderation.md).

**n** `integer` (default: 1)

The number of clips to generate. Only 1 is supported.

**response\_format** `string` (default: b64\_json)

The format of the returned clip.

Options: `b64_json`, `url`

In `url` format, Nunchux keeps the generated clip for 7 days, so that it appears in your request history. Then Nunchux deletes it. Save the clip from the response if you need to keep it.

> [!NOTE]
>
> Unsupported fields
>
> MiniMax H3 Fast does not accept `width`, `height`, `steps`, `guidance_scale` or `negative_prompt`. Set the shape with `extra.short_edge` and `extra.aspect_ratio`. A request that contains one of them returns a 400.

## Inputs

Each model takes its own roles in `refs`. A role that the model does not take returns a 400.

| Model ID | Role | Limit |
| - | - | - |
| `nunchux-minimax-h3-fast-fl2va` | `first_frame` | 1 image. The clip starts on it. |
| `nunchux-minimax-h3-fast-fl2va` | `last_frame` | 1 image. The clip ends on it. |
| `nunchux-minimax-h3-fast-ref2va` | `reference_image` | Up to 9 images |
| `nunchux-minimax-h3-fast-ref2va` | `reference_video` | Up to 3 clips, 2 to 15 seconds each, 15 seconds in all |
| `nunchux-minimax-h3-fast-ref2va` | `reference_audio` | Up to 3 audio tracks |

`nunchux-minimax-h3-fast-fl2va` takes a first frame, a last frame, both, or neither. With neither, it generates the clip from the prompt alone.

`nunchux-minimax-h3-fast-ref2va` needs at least one reference. A request with no `refs` returns a 400. In the prompt, name each reference by its role and its position in `refs`: the first `reference_image` is Image 1, the first `reference_video` is Video 1, and the first `reference_audio` is Audio 1.

The files must meet these limits:

* Images: up to 30 MB, each side 256 to 5760 pixels, and a width-to-height ratio from 0.4 to 2.5.
* Clips: up to 50 MB, each side 256 to 5760 pixels, a width-to-height ratio from 0.4 to 2.5, and 23.976 to 60 frames per second. Send MP4 or MOV, so that Nunchux can read the clip length for billing.
* Audio: up to 15 MB.

A minimal text-to-video body:

```json theme={"system"}
{
  "model": "nunchux-minimax-h3-fast-fl2va",
  "prompt": "A paper boat drifts down a rain-filled gutter at dusk, the patter of rain and a distant tram bell",
  "duration": 6,
  "extra": { "short_edge": 480, "aspect_ratio": "16:9" },
  "response_format": "url"
}
```

A body that starts and ends the clip on your frames:

```json theme={"system"}
{
  "model": "nunchux-minimax-h3-fast-fl2va",
  "prompt": "The flower opens slowly in the morning light, birdsong in the background",
  "duration": 6,
  "refs": [
    { "role": "first_frame", "url": "https://example.com/bud.png" },
    { "role": "last_frame", "url": "https://example.com/bloom.png" }
  ],
  "extra": { "short_edge": 768, "aspect_ratio": "1:1" },
  "response_format": "url"
}
```

A reference-to-video body:

```json theme={"system"}
{
  "model": "nunchux-minimax-h3-fast-ref2va",
  "prompt": "Reference the camera movement from Video 1, have the character in Image 1 sing, with the vocals matching Audio 1",
  "duration": 6,
  "refs": [
    { "role": "reference_image", "url": "https://example.com/singer.png" },
    { "role": "reference_video", "url": "https://example.com/camera-move.mp4" },
    { "role": "reference_audio", "url": "https://example.com/vocals.mp3" }
  ],
  "extra": { "short_edge": 480, "aspect_ratio": "16:9" },
  "prompt_expansion": "fast",
  "response_format": "url"
}
```

## Response

The response is JSON. The `data` array contains one MP4 clip, with its soundtrack, as base64 data or as a URL.

**created** `integer` *required*

The Unix timestamp of the generation.

**model** `string` *required*

The model that generated the clip.

**tier** `string` *required*

The tier that served the request: `radical_speed` or `radical_value`.

**seed** `integer` *required*

The seed of the clip. Send it again to get the same result.

**prompt\_expansion** `object`

Returned when `prompt_expansion` is not `off`. `mode` is the mode you sent. `outcome` is `expanded` when the clip rendered from the rewritten prompt.

**data** `array` *required*

The generated clip.

**Item properties**

**b64\_json** `string`

The MP4 clip as base64 data. Returned when `response_format` is `b64_json`.

**url** `string`

The URL of the MP4 clip. Returned when `response_format` is `url`.

**width** `integer`

The width of the clip in pixels.

**height** `integer`

The height of the clip in pixels.

**duration** `number`

The length of the clip in seconds.

**frames** `integer`

The number of frames in the clip.

**frame\_rate** `integer`

The frame rate of the clip.

**revised\_prompt** `string`

The rewritten prompt that the model rendered. Returned when `prompt_expansion` is not `off` and the rewrite succeeds.

```json theme={"system"}
{
  "created": 1234567890,
  "model": "nunchux-minimax-h3-fast-fl2va",
  "tier": "radical_speed",
  "seed": 1536904073,
  "data": [
    {
      "url": "https://...",
      "width": 864,
      "height": 480,
      "duration": 4.4583,
      "frames": 107,
      "frame_rate": 24
    }
  ]
}
```

## Example

A clip takes some time to render. A 6 second clip at 480 takes about 6 seconds on Radical Speed and about 20 seconds on Radical Value. Set the timeout of your HTTP client to 120 seconds.

```bash cURL theme={"system"}
curl -X POST https://api.nunchux.com/v1/videos/generations \
  --max-time 120 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NUNCHUX_API_KEY" \
  -d '{
    "model": "nunchux-minimax-h3-fast-fl2va",
    "prompt": "A paper boat drifts down a rain-filled gutter at dusk, the patter of rain and a distant tram bell",
    "tier": "radical_speed",
    "duration": 6,
    "extra": {"short_edge": 480, "aspect_ratio": "16:9"},
    "response_format": "b64_json"
  }' | jq -r '.data[0].b64_json // error(.error.message // .detail // tostring)' | base64 -d > output.mp4
```

```python Python theme={"system"}
import os
import base64
import requests

response = requests.post(
    "https://api.nunchux.com/v1/videos/generations",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["NUNCHUX_API_KEY"],
    },
    json={
        "model": "nunchux-minimax-h3-fast-fl2va",
        "prompt": "A paper boat drifts down a rain-filled gutter at dusk, the patter of rain and a distant tram bell",
        "tier": "radical_speed",
        "duration": 6,
        "extra": {"short_edge": 480, "aspect_ratio": "16:9"},
        "response_format": "b64_json",
    },
    timeout=120,
)
response.raise_for_status()

# Decode the base64 clip and save it. Change output.mp4 to any file name.
clip_b64 = response.json()["data"][0]["b64_json"]
with open("output.mp4", "wb") as f:
    f.write(base64.b64decode(clip_b64))
```

```javascript JavaScript theme={"system"}
import { writeFile } from "node:fs/promises";

const response = await fetch("https://api.nunchux.com/v1/videos/generations", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.NUNCHUX_API_KEY,
  },
  body: JSON.stringify({
    model: "nunchux-minimax-h3-fast-fl2va",
    prompt:
      "A paper boat drifts down a rain-filled gutter at dusk, the patter of rain and a distant tram bell",
    tier: "radical_speed",
    duration: 6,
    extra: { short_edge: 480, aspect_ratio: "16:9" },
    response_format: "b64_json",
  }),
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const data = await response.json();

// Decode the base64 clip and save it. Change output.mp4 to any file name.
await writeFile("output.mp4", Buffer.from(data.data[0].b64_json, "base64"));
```

## Billing

A clip is billed per second of output video, at the rate of its tier and its short edge. 768 costs more per second than 480, and Radical Value costs less than Radical Speed. The billed seconds are the `duration` you send, not the slightly longer clip that returns.

Inputs add to the charge only on `nunchux-minimax-h3-fast-ref2va`:

* Each reference clip is billed per second of its length, at the same rate as the output. A clip whose length Nunchux cannot read, such as a WebM file, is billed as 15 seconds.
* The first 5 reference images are free. Each image after the fifth has a fixed price.
* Reference audio is free.

First and last frames on `nunchux-minimax-h3-fast-fl2va` are free.

See the [pricing page](https://nunchux.ai/pricing) for current rates. Nunchux charges only for a successful clip. A request that fails is never billed.

## Tips

* Describe the sound in the prompt as well as the picture. The model generates both.
* On `nunchux-minimax-h3-fast-ref2va`, say what each reference is for: the character in Image 1, the camera movement from Video 1, the voice in Audio 1.
* Draft at 480 on Radical Speed. Use 768 for the final clip, and Radical Value for large batches.
* Use `prompt_expansion` set to `fast` for a short prompt. Use `off` when your prompt already describes the shot in detail.
* Keep the `seed` when you like a result. Then change one parameter at a time.

## Errors and limits

| Status | Code | Cause |
| - | - | - |
| 400 | none | `extra.short_edge` has no price, for example 1080. The body is a plain `detail` string that names the priced short edges. |
| 400 | `engine_error` | The model cannot render the request, for example a short edge other than 480 or 768, an aspect ratio off the list, a `duration` under 4 or over 15, an unsupported field, `n` above 1, a role the model does not take, too many references, or a reference URL that is not `https`. |

Every request counts toward the requests-per-minute cap of your plan. A request also holds one simultaneous-jobs slot until the response returns. See [Rate limits](https://docs.nunchux.ai/rate-limits.md). For authentication and credit errors, see [Error codes](https://docs.nunchux.ai/errors.md).


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