# MiniMax-H3 特惠版

> 通过独立 /special/v2 接口使用 MiniMax-H3 特惠版，支持 768P 与 2K 输出

特惠版使用独立的**特惠渠道**，请求尽量沿用 MiniMax-H3 的 `model`、`content`、`duration`、`resolution` 和 `ratio` 字段。客户端使用 LoopRouter 令牌，不需要任何额外凭据。

<Warning>
特惠版的路径以 `/special/v2` 开头，官方 MiniMax 渠道仍使用 `/v2`。两套渠道和任务互相隔离，查询任务时必须使用创建任务的那套接口。
</Warning>

## 创建视频

```bash
curl --request POST 'https://api.looprouter.com/special/v2/video_generation' \
  --header 'Authorization: Bearer YOUR_LOOPROUTER_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MiniMax-H3",
    "content": [{"type": "text", "text": "日出时分，海边的小船缓缓驶向远方"}],
    "duration": 5,
    "resolution": "768P",
    "ratio": "16:9"
  }'
```

返回异步任务 ID：

```json
{"task_id": "task_example"}
```

客户不需要处理任何内部路由参数。网关根据 `content` 中的素材角色选择文生、首帧/尾帧或多参考生成流程，并自动完成参数转换。

## 查询任务

```bash
curl 'https://api.looprouter.com/special/v2/query/video_generation/task_example' \
  --header 'Authorization: Bearer YOUR_LOOPROUTER_API_KEY'
```

响应沿用 MiniMax 的 `{ "task": { ... } }` 结构。视频处理期间为 `queued` 或 `running`，完成后为 `succeeded`，成片在 `task.content.url`。`h3_context_ir` 是文本任务，结果在 `task.content.prompt`。

## 接口列表

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/special/v2/video_generation` | 创建视频任务 |
| POST | `/special/v2/h3_context_ir` | 创建提示词增强任务 |
| POST | `/special/v2/video_regeneration` | 基于已有素材与提示词重新生成 2K 视频 |
| GET | `/special/v2/query/video_generation/{task_id}` | 查询任务 |
| GET | `/special/v2/query/video_generation` | 分页查询本账号特惠版任务 |
| DELETE | `/special/v2/video_generation/{task_id}` | 删除已结束的本地任务记录 |

特惠版不支持取消执行中的任务，此时请求删除会返回 501。已结束的任务可以删除本地记录，但不会删除已生成的媒体或退还已经结算的费用。不要将本地删除当作成功取消付费任务。

Context-IR 沿用创建视频的 `model`、`content`、`duration` 和 `ratio` 结构，但不带 `resolution`。单独调用再生成时，`content` 需包含实际生成源视频时使用的完整提示词、原始素材，以及一个 `type: "video_url"`、`role: "base_video"` 的源视频项。

Context-IR 的纯文本模式必须指定具体比例；多参考模式支持 `adaptive`（默认）；首尾帧模式由图片决定比例，`ratio` 不传给上游。

已有本账号通过特惠接口生成的成功 768P 任务时，也可用 `source_task_id` 代替整个 `content`。网关会读取原任务的提示词与素材；不能引用其他用户、官方渠道或文本任务。

```json
{"model":"MiniMax-H3","source_task_id":"task_example","resolution":"2K"}
```

## 分辨率与时长

| 参数 | 特惠版规则 |
| --- | --- |
| `resolution: "768P"` | 支持 |
| `resolution: "2K"` | 支持，任务完成后交付 2K 成片 |
| 其他分辨率 | 不自动替换为 768P，返回不支持错误 |
| 生成时长 | 5–15 秒整数；官方的 4 秒生成请求在特惠版中不支持 |
| Context-IR 时长 | 4–15 秒，与生成接口的范围不同 |

<Note>
请求 2K 时只需轮询原任务，任务完成后即获得 2K 成片，不需要创建第二个任务。
</Note>

## 与官方接口的区别

这里是协议适配，不是将请求原样转发到 MiniMax 官方。特惠版的时长、素材格式、宽高比及可选参数不一定覆盖官方所有能力；不能正确实现的参数会返回明确错误，不应依赖静默丢弃或替换。

- 生成请求必须显式传具体 `ratio`，不支持 `adaptive`，不会根据图片猜测比例。
- 素材使用公网 HTTP(S) URL，不支持官方的 `mm_file://` 或 Base64 data URI。
- 不支持 `callback_url`、`aigc_watermark` 或 `seed`；查询使用上面的轮询接口。
- 再生成源视频需要符合音轨、24fps、尺寸及帧数要求。仅标记为“768P”不能保证任意视频均兼容。
- 特惠版按分辨率与时长计费，不产生官方 token 用量账单，费用口径与官方渠道相互独立。