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

通过 GregAPI 调用 MiniMax-H3 与 MiniMax-H3-Max 视频生成（v2）能力。MiniMax 官方 v2 能力使用 `POST /v2/video_generation` 创建任务、`GET /v2/query/video_generation/{task_id}` 查询任务，GregAPI 以代理接口形式对外提供，两者都必须携带 Bearer Token。

## 1. 模型与能力

| 模型 | 分辨率 | 时长范围 | 输入能力 |
| - | - | - | - |
| `MiniMax-H3` | `768P` / `2K` | 4–15 秒 | 文生视频、首/尾帧、参考素材 |
| `MiniMax-H3-Max` | `480P` / `768P` | 5–15 秒 | 仅文本与首/尾帧图片，不接受参考素材 |

`minimax-h3-768p-second`、`minimax-h3-2k-second`、`minimax-h3-extra-input-image`、`minimax-h3-max-480p-second`、`minimax-h3-max-768p-second` 是 GregAPI 内部计费组件 SKU，不能作为 `model` 取值，也不是可配置的模型 allowlist 条目。

## 2. 接口

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

| 操作 | 路径 |
| - | - |
| 创建任务 | `POST /minimaxi/v2/video_generation` |
| 查询任务 | `GET /minimaxi/v2/query/video_generation/{task_id}` |

所有请求使用 GregAPI API Token：

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

## 3. 创建任务

### 请求体

```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"
}
```

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | ✅ | `MiniMax-H3` 或 `MiniMax-H3-Max` |
| `content` | object\[] | ✅ | 恰好一个非空 `text` 项 + 最多 12 个媒体项（数组长度 1–13） |
| `duration` | integer | ✅ | 输出时长（秒）；H3 为 4–15，H3-Max 为 5–15 |
| `resolution` | string | ❌ | `768P`（默认）/ `2K` / `480P`；H3 只支持 `768P`/`2K`，H3-Max 只支持 `480P`/`768P` |
| `ratio` | string | ❌ | `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` |
| `callback_url` | string | ❌ | 任务完成回调地址 |

`content` 中的 `text` 项提示词最多 7000 个 Unicode 字符，且不能设置 `role`。

### 创建示例

```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"
  }'
```

创建成功只返回 GregAPI 的稳定公共标识：

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

## 4. 内容与媒体规则

`content` 中媒体项按类型和数量受限：

| 类型 | `role` | 数量上限 |
| - | - | - |
| `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 |

`image_url` 未提供 `role` 时按 `first_frame` 处理。约束如下：

* 首/尾帧模式不能与任何参考素材混用；
* 仅提供 `reference_audio` 时，必须同时提供 `reference_image` 或 `reference_video`。

### 比例与模式

* **文生视频**：没有媒体项时 `ratio` 必填，且必须是具体比例，不能为 `adaptive`。
* **首/尾帧**：包含 `first_frame` 或 `last_frame` 时使用 `adaptive`。
* **参考素材**：包含任一 `reference_*` 项时，`ratio` 可省略（默认 `adaptive`），也可传 `adaptive` 或具体比例。

H3-Max 只支持首/尾帧模式，不支持参考素材。

## 5. 媒体 locator 与大小限制

每个 `image_url.url`、`video_url.url`、`audio_url.url` 只能使用以下 locator：

* 公网 `https://` URL。GregAPI 会对 URL 做 DNS fail-closed 和私网/回环地址拦截；不接受 HTTP、`file:`、`ftp:`、`blob:`、`javascript:` 或协议相对 URL。
* 严格的 `data:<mime>;base64,<payload>`。metadata 必须恰为 `<mime>;base64`，不能有空白字符，payload 必须是非空严格 Base64。
* authority-only 的 `mm_file://<positive-int64>`。只允许正十进制 int64 authority，不能包含用户信息、端口、路径、query 或 fragment。

对 data URI，GregAPI 会验证解码后单文件大小与 MIME：

| 输入类型 | 允许的 MIME | 解码后上限 |
| - | - | - |
| `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 |

公网 HTTPS URL 和 `mm_file` 引用不会由 GregAPI 拉取或在本地检查媒体内容，媒体格式等官方约束由上游校验。完整 JSON 请求体最大为 64 MiB；data URI 的 Base64 膨胀和其他字段也计入该限制，因此实际可用的解码后大小会低于单文件上限。

## 6. 查询任务

将创建响应的 `task_id`（或 `platform_id`）放入路径参数：

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

查询响应保持上游 `task` 对象，并在顶层附加 `platform_id`；`base_resp` 也可能出现。`task` 可包含 `id`、`status`、`model`、`task_type`、`resolution`、`duration`、`created_at`、`updated_at`、`content.url`、`usage` 和 `error`。`status` 与时间字段以上游实际返回为准。

```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. 计费与说明

* 成功结果中的 `task.content.url` 是上游签名 URL，会过期，具体有效期以该 URL 与上游返回为准；请在收到后及时使用，不要把完整签名 URL 写入日志或长期存储。
* 创建失败、任务失败或取消时的计费结果以 GregAPI 账户和实际任务结算记录为准。


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