# MiniMax H3 / H3 Max

> Create MiniMax H3 and H3 Max video tasks with the native JSON API, including query, media references, Context, regeneration and task management.

Canonical URL: https://docs.uniall.ai/models/video/minimax-h3
Locale: en

Use the MiniMax native video API with your UniAI API key.

- Base URL: `https://api.uniall.ai`
- Models: `MiniMax-H3`, `MiniMax-H3-Max`
- Content type: `application/json`

## Endpoints

| Method | Path | Use |
| --- | --- | --- |
| POST | `/v2/video_generation` | Create a video |
| POST | `/v2/h3_context_ir` | Create a Context prompt |
| POST | `/v2/video_regeneration` | Regenerate an H3 video at 2K |
| GET | `/v2/query/video_generation/{task_id}` | Query a task |
| GET | `/v2/query/video_generation` | List tasks |
| DELETE | `/v2/video_generation/{task_id}` | Cancel or delete a task |

## Create a video

See [request examples](/models/video/minimax-h3/examples) for frame, reference, H3 Max, Context, and regeneration requests.

```bash
curl -X POST "https://api.uniall.ai/v2/video_generation" \
  -H "Authorization: Bearer $UNIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "A paper boat crosses a quiet pond in warm morning light."
      }
    ],
    "duration": 5,
    "resolution": "768P",
    "ratio": "16:9"
  }'
```

Response:

```json
{
  "task_id": "task_YOUR_VIDEO"
}
```

## Parameters

| Field | Required | Values |
| --- | --- | --- |
| `model` | Yes | `MiniMax-H3` or `MiniMax-H3-Max` |
| `content` | Yes | One `text` item and optional media items |
| `duration` | Yes | H3: integer 4–15; H3 Max: integer 5–15 |
| `resolution` | No | H3: `768P` or `2K`; H3 Max: `480P` or `768P`. Default: `768P` |
| `ratio` | Text only | Text-only requests require a concrete ratio. Frame input uses `adaptive`; references default to `adaptive`. Accepted values: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `adaptive`. |
| `aigc_watermark` | No | Boolean; default `false` |
| `extra.prompt_expansion_mode` | H3 Max only | `disabled`, `balanced` (default), or `quality` |
| `callback_url` | No | Public HTTP(S) URL. Return the verification `challenge` unchanged within 3 seconds; otherwise poll the query endpoint. |

## Add images, video, or audio

Put media in `content`. Each request must contain one text item (up to 7,000 characters).

| Type | Role |
| --- | --- |
| `image_url` | `first_frame`, `last_frame`, or `reference_image` |
| `video_url` | `reference_video`; use `base_video` only for regeneration |
| `audio_url` | `reference_audio` |

Use `{"url":"https://..."}` for each media field. Image role defaults to `first_frame`. Frame images and reference media cannot be mixed.

Example with a first frame:

```json
{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "A paper boat crosses a quiet pond in warm morning light."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://YOUR_PUBLIC_URL/first.png"
      },
      "role": "first_frame"
    }
  ],
  "duration": 5,
  "resolution": "768P"
}
```

Limits: up to 9 images, 3 videos, and 3 audio files (12 media items total). Images: JPEG, PNG, WEBP, HEIC, or HEIF; 30 MB each; dimensions 256–5,760 px. Video: MP4 or MOV, 50 MB each, 23.976–60 fps; 2–15 seconds each and 15 seconds total. Audio: WAV or MP3, 15 MB each; 2–15 seconds each and 15 seconds total. Use publicly accessible URLs or matching data URIs. This API does not upload media.

## Query a task

Poll the returned ID:

```bash
curl "https://api.uniall.ai/v2/query/video_generation/task_YOUR_VIDEO" \
  -H "Authorization: Bearer $UNIAI_API_KEY"
```

Video task response:

```json
{
  "task": {
    "id": "task_YOUR_VIDEO",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "task_type": "generation",
    "modality": "video",
    "content": {
      "url": "https://YOUR_RESULT_URL/video.mp4"
    }
  }
}
```

Statuses: `queued`, `running`, `succeeded`, `failed`, `cancelled`. Download a completed video from `task.content.url`.

## Context

Context returns an enhanced prompt; it does not create a video. Use H3 and omit `resolution`.

```bash
curl -X POST "https://api.uniall.ai/v2/h3_context_ir" \
  -H "Authorization: Bearer $UNIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "A paper boat crosses a quiet pond in warm morning light."
      }
    ],
    "duration": 5,
    "ratio": "16:9"
  }'
```

Query it with the same task endpoint. The result prompt is in `task.content.prompt`.

## Regenerate at 2K

Regeneration is H3 only. Use a completed H3 768P task created by your account within the last seven days:

```bash
curl -X POST "https://api.uniall.ai/v2/video_regeneration" \
  -H "Authorization: Bearer $UNIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "source_task_id": "task_YOUR_COMPLETED_H3_768P",
    "resolution": "2K"
  }'
```

Alternatively, send the original prompt and all original inputs with one `base_video` item in `content`. Do not send `duration` or `ratio`.

## List, cancel, or delete tasks

```bash
curl "https://api.uniall.ai/v2/query/video_generation?page_num=1&page_size=10" \
  -H "Authorization: Bearer $UNIAI_API_KEY"
```

List response contains `items` and `total`. Use `page_num`, `page_size` and `filter.model`, `filter.task_type`, `filter.task_ids`, or `filter.status`. Native task history is available for seven days.

```bash
curl -X DELETE "https://api.uniall.ai/v2/video_generation/task_YOUR_VIDEO" \
  -H "Authorization: Bearer $UNIAI_API_KEY"
```

DELETE cancels a queued task or deletes a succeeded/failed task. It does not cancel a running task.

## Errors

HTTP errors use this response shape:

```json
{
  "type": "error",
  "error": {
    "type": "bad_request_error",
    "message": "Invalid request parameters.",
    "http_code": "400"
  },
  "request_id": "opaque_request_id"
}
```

A failed task is returned with `task.status` set to `failed` and an `task.error` object. If a create request times out, check for the task before submitting again.