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

# Text-to-video

> Generate a video clip from a text prompt with LTX. The clip is in the response.

# Text-to-video

Send a text prompt, and the response contains the generated video clip. The request is synchronous. There is no task to poll. A clip is 1 to 8 seconds long, at 1080p or 720p, with an optional soundtrack.

## Models

| Model | Model ID | Use it for |
| - | - | - |
| LTX 2.5 | `nunchux-ltx-2.5-video` | New work. The newer release, with the same controls as LTX 2.3. |
| LTX 2.3 | `nunchux-ltx-2.3-video` | Continuity with clips that you already made with LTX 2.3. |

Both models also serve [Image-to-video](https://docs.nunchux.ai/nunchux-optimized/image-to-video.md). See [Choosing a model](https://docs.nunchux.ai/nunchux-optimized/overview.md#choosing-a-model).

MiniMax H3 Fast also serves text-to-video on this endpoint, with a soundtrack and its own fields. See [MiniMax H3 Fast](https://docs.nunchux.ai/nunchux-optimized/minimax-h3-fast.md).

## Endpoint

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

The path `/v1/videos/generations` is an alias. It gives the same result and the same billing.

## 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-ltx-2.5-video`, `nunchux-ltx-2.3-video`

**prompt** `string` *required*

A text description of the clip. Describe the shot: the subject, the camera movement, the light, and what changes during the clip.

**width** `integer` (default: 1920)

Output width in pixels. Send it together with `height`. The size selects the tier, 1080p or 720p. 1080p costs more per second.

Options: `1920` (1080p), `1280` (720p)

**height** `integer` (default: 1080)

Output height in pixels. Send it together with `width`.

Options: `1080` (1080p), `720` (720p)

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

The clip length in seconds. Range: 1 to 8. The model renders at 24 frames per second, so the length of the clip can differ from your value by a fraction of a second. The response gives the length of the clip.

**extra** `object`

Model options.

**properties**

**audio** `boolean` (default: false)

When `true`, the model generates a soundtrack with the picture. Describe the sound in the prompt.

**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. In `b64_json` format, Nunchux also tries to keep a copy for your request history, but it skips the copy when the service is busy. Save the clip from the response if you need to keep it.

> [!NOTE]
>
> Unsupported fields
>
> LTX does not accept `steps`, `guidance_scale`, `negative_prompt` or `num_frames`. A request that contains one of them returns a 400.

A minimal request body:

```json theme={"system"}
{
  "model": "nunchux-ltx-2.3-video",
  "prompt": "A golden retriever running on a beach at sunset, cinematic",
  "width": 1280,
  "height": 720,
  "duration": 6,
  "extra": { "audio": false },
  "response_format": "b64_json"
}
```

## Response

The response is JSON. The `data` array contains one MP4 clip, 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*

Always `radical_speed`. This field does not show the LTX tier. The `width` and `height` of the clip show it.

**seed** `integer` *required*

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

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

```json theme={"system"}
{
  "created": 1234567890,
  "model": "nunchux-ltx-2.3-video",
  "tier": "radical_speed",
  "seed": 1873420651,
  "data": [
    {
      "b64_json": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQ...",
      "width": 1280,
      "height": 720,
      "duration": 6.0417,
      "frames": 145,
      "frame_rate": 24
    }
  ]
}
```

A base64 clip is large. A 6 second 1080p clip can be more than 10 MB of base64 data. Use `response_format: "url"` when you do not need the data in the response.

## Example

A clip takes some time to render. Set the timeout of your HTTP client to 120 seconds.

```bash cURL theme={"system"}
curl -X POST https://api.nunchux.com/v1/video/generations \
  --max-time 120 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NUNCHUX_API_KEY" \
  -d '{
    "model": "nunchux-ltx-2.3-video",
    "prompt": "A golden retriever running on a beach at sunset, cinematic",
    "width": 1280,
    "height": 720,
    "duration": 6,
    "extra": {"audio": false},
    "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/video/generations",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["NUNCHUX_API_KEY"],
    },
    json={
        "model": "nunchux-ltx-2.3-video",
        "prompt": "A golden retriever running on a beach at sunset, cinematic",
        "width": 1280,
        "height": 720,
        "duration": 6,
        "extra": {"audio": False},
        "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/video/generations", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.NUNCHUX_API_KEY,
  },
  body: JSON.stringify({
    model: "nunchux-ltx-2.3-video",
    prompt: "A golden retriever running on a beach at sunset, cinematic",
    width: 1280,
    height: 720,
    duration: 6,
    extra: { audio: false },
    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"));
```

## Tips

* Write the shot, not only the subject. Include the camera movement, the light, and what changes during the clip.
* When `extra.audio` is `true`, describe the sound in the prompt. For example: rain on a window, a crowd, or one piano line.
* Start at 1080p and 6 seconds. Use 720p for faster and lower-cost previews.
* Keep the `seed` when you like a result. Then change one parameter at a time.

## Errors and limits

| Status | Code | Cause |
| - | - | - |
| 400 | none | `model` is missing or not valid, or a size value is not valid. The body is a plain `detail` string. |
| 400 | `invalid_request` | The request sets `tier` to a value other than `radical_speed`. On LTX, `width` and `height` select the tier. Do not send the `tier` field. |
| 400 | `unsupported_response_format` | `response_format` is not `b64_json` or `url`. |
| 400 | `engine_error` | The model cannot render the request, for example a size, a duration or a field that it does not accept. |
| 422 | `request_too_large` | The requested size is larger than 1920x1080. `details` gives the requested value and the maximum. |
| 502 | `output_too_large` | The clip is too large to return. You are not charged. Request a shorter clip or a smaller size. |
| 504 | none | The clip did not complete in 120 seconds. Send the request again. |

A clip is billed per second of output video, at the rate of its tier: 1080p costs more per second than 720p. 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.

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.