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

# MiniMax-H3/H3-Max

Call the MiniMax-H3 and MiniMax-H3-Max video generation (v2) capabilities through GregAPI. MiniMax's official v2 capability creates tasks with `POST /v2/video_generation` and queries them with `GET /v2/query/video_generation/{task_id}`; GregAPI exposes these as proxy endpoints, and both require a Bearer token.

## 1. Models and capabilities

| Model | Resolution | Duration range | Input capabilities |
| - | - | - | - |
| `MiniMax-H3` | `768P` / `2K` | 4–15 seconds | Text-to-video, first/last frame, reference material |
| `MiniMax-H3-Max` | `480P` / `768P` | 5–15 seconds | Text and first/last-frame images only; reference material is not accepted |

`minimax-h3-768p-second`, `minimax-h3-2k-second`, `minimax-h3-extra-input-image`, `minimax-h3-max-480p-second`, and `minimax-h3-max-768p-second` are GregAPI's internal billing component SKUs. They cannot be used as `model` values, nor are they configurable model allowlist entries.

## 2. Endpoints

```bash theme={null}
export BASE_URL="https://api.gregapi.com"
export TOKEN="oh-xxxxxxxxxxxxxxxx"
```

| Operation | Path |
| - | - |
| Create task | `POST /minimaxi/v2/video_generation` |
| Query task | `GET /minimaxi/v2/query/video_generation/{task_id}` |

All requests use the GregAPI API Token:

```http theme={null}
Authorization: Bearer <TOKEN>
Content-Type: application/json
```

## 3. Create a task

### Request body

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "content": [
    {"type": "text", "text": "A cat walking on the beach at sunset"}
  ],
  "duration": 5,
  "resolution": "768P",
  "ratio": "16:9"
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `model` | string | ✅ | `MiniMax-H3` or `MiniMax-H3-Max` |
| `content` | object\[] | ✅ | Exactly one non-empty `text` item plus at most 12 media items (array length 1–13) |
| `duration` | integer | ✅ | Output duration in seconds; H3 is 4–15, H3-Max is 5–15 |
| `resolution` | string | ❌ | `768P` (default) / `2K` / `480P`; H3 supports only `768P`/`2K`, H3-Max only `480P`/`768P` |
| `ratio` | string | ❌ | `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` |
| `callback_url` | string | ❌ | Callback URL on task completion |

The `text` item in `content` may be up to 7000 Unicode characters and must not set `role`.

### Create example

```bash theme={null}
curl -X POST "$BASE_URL/minimaxi/v2/video_generation" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3-Max",
    "content": [{"type": "text", "text": "A cat walking on the beach at sunset"}],
    "duration": 5,
    "resolution": "768P",
    "ratio": "16:9"
  }'
```

A successful creation returns only GregAPI's stable public identifiers:

```json theme={null}
{
  "task_id": "upstream-task-id",
  "platform_id": "video_01JSGXXXXXXXXXXXXXXXXXX"
}
```

## 4. Content and media rules

Media items in `content` are limited by type and count:

| Type | `role` | Max count |
| - | - | - |
| `image_url` | `first_frame` | 1 |
| `image_url` | `last_frame` | 1 |
| `image_url` | `reference_image` | 9 |
| `video_url` | `reference_video` | 3 |
| `audio_url` | `reference_audio` | 3 |

An `image_url` without a `role` is treated as `first_frame`. Constraints:

* First/last-frame mode cannot be mixed with any reference material.
* When only `reference_audio` is provided, `reference_image` or `reference_video` must also be present.

### Ratio and mode

* **Text-to-video**: with no media items, `ratio` is required and must be a concrete ratio, not `adaptive`.
* **First/last frame**: when `first_frame` or `last_frame` is present, `adaptive` is used.
* **Reference material**: when any `reference_*` item is present, `ratio` may be omitted (defaults to `adaptive`), or set to `adaptive` or a concrete ratio.

H3-Max supports only the first/last-frame mode; reference material is not supported.

## 5. Media locators and size limits

Each `image_url.url`, `video_url.url`, and `audio_url.url` may only use these locators:

* A public `https://` URL. GregAPI performs DNS fail-closed and private/loopback address blocking; HTTP, `file:`, `ftp:`, `blob:`, `javascript:`, and protocol-relative URLs are not accepted.
* A strict `data:<mime>;base64,<payload>`. The metadata must be exactly `<mime>;base64` with no whitespace, and the payload must be non-empty strict Base64.
* An authority-only `mm_file://<positive-int64>`. Only a positive decimal int64 authority is allowed, with no userinfo, port, path, query, or fragment.

For data URIs, GregAPI validates the decoded per-file size and MIME:

| Input type | Allowed MIME | Decoded limit |
| - | - | - |
| `image_url` | `image/jpeg`, `image/jpg`, `image/png`, `image/webp`, `image/heic`, `image/heif` | 30 MiB |
| `video_url` | `video/mp4` | 50 MiB |
| `audio_url` | `audio/wav`, `audio/mp3` | 15 MiB |

Public HTTPS URLs and `mm_file` references are not fetched or locally inspected by GregAPI; official media-format constraints are validated upstream. The full JSON request body is capped at 64 MiB; the Base64 expansion of data URIs and other fields count toward this limit, so the actual decoded size available will be lower than the per-file cap.

## 6. Query a task

Put the `task_id` (or `platform_id`) from the creation response into the path parameter:

```bash theme={null}
curl "$BASE_URL/minimaxi/v2/query/video_generation/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN"
```

The query response keeps the upstream `task` object and appends `platform_id` at the top level; `base_resp` may also appear. `task` may contain `id`, `status`, `model`, `task_type`, `resolution`, `duration`, `created_at`, `updated_at`, `content.url`, `usage`, and `error`. `status` and time fields reflect what upstream actually returns.

```json theme={null}
{
  "task": {
    "id": "upstream-task-id",
    "status": "succeeded",
    "content": {"url": "https://..."},
    "usage": {
      "input_seconds": 0,
      "output_seconds": 5,
      "total_seconds": 5,
      "input_image_count": 0
    }
  },
  "platform_id": "video_01JSGXXXXXXXXXXXXXXXXXX",
  "base_resp": {"status_code": 0, "status_msg": "success"}
}
```

## 7. Billing and notes

* On success, `task.content.url` is an upstream signed URL and will expire; the exact validity depends on the URL and the upstream response. Use it promptly and do not write the full signed URL into logs or long-term storage.
* Billing for creation failures, task failures, or cancellations is subject to the GregAPI account and actual task settlement records.


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