# MiniMax-H3 能力总览

> MiniMax-H3（海螺 Hailuo）多模态视频模型：原生 /v2 接口、生成模式、技术规格、提示增强、视频再生与计费说明

MiniMax-H3（海螺 Hailuo-03）是 MiniMax 的多模态视频生成模型，能同时理解文本、图片、视频与音频输入，支持文生视频、图生视频、首尾帧、多模态参考生成，并提供**提示增强（Context-IR）**与**视频再生（768P → 2K）**两项进阶能力。LoopRouter 以**与 MiniMax 官方完全一致的原生 `/v2` 接口**对外透传：官方示例代码只需把 Base URL 换成 `https://api.looprouter.com`、把 `Authorization` 换成 LoopRouter 令牌即可运行。

<Note>
本接口族的路径、请求体与响应体与 MiniMax 官方保持一致（`/v2/video_generation` 等，**没有** `/api` 前缀）。与豆包 Seedance 的 `/api/v3/...` 接口是两套独立的 API，不要混用。
</Note>

## 快速入口

<CardGroup cols={2}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/minimax/video-generation">
    创建 / 查询 / 列表 / 删除，以及提示增强与视频再生
  </Card>
  <Card title="在线调试（试一试）" icon="flask" href="/api-reference/minimax/create-video-task">
    在文档内直接对 `/v2` 接口发起真实请求
  </Card>
  <Card title="获取 API Key" icon="key" href="https://console.looprouter.com/keys">
    在控制台创建 `sk-` 令牌
  </Card>
</CardGroup>

## 核心特性

<CardGroup cols={2}>
  <Card title="多模态输入" icon="layer-group">
    文本、图片、视频、音频自由组合，支持首尾帧与参考生成
  </Card>
  <Card title="提示增强 Context-IR" icon="wand-magic-sparkles">
    `/v2/h3_context_ir` 理解多模态上下文，输出结构化增强提示词
  </Card>
  <Card title="视频再生 2K" icon="arrow-up-right-dots">
    `/v2/video_regeneration` 将 768P 成片重生成为 2K 高清
  </Card>
  <Card title="原生接口透传" icon="plug">
    请求 / 响应字节形状镜像官方，迁移零改造
  </Card>
</CardGroup>

## 模型清单

| 模型 | 说明 |
| --- | --- |
| `MiniMax-H3` | 多模态视频模型，覆盖生成、提示增强、视频再生三类任务（靠端点区分，`model` 恒为 `MiniMax-H3`） |

<Note>
三类任务（`video_generation` / `h3_context_ir` / `video_regeneration`）在请求体中 `model` 均填 `MiniMax-H3`，任务类型由**调用的端点**决定，响应里的 `task_type` 会回显 `generation` / `h3_context_ir` / `regeneration`。
</Note>

## 技术规格

| 项目 | 规格 |
| --- | --- |
| 生成模式 | 文生视频 / 图生视频（首帧、尾帧、首尾帧）/ 多模态参考 |
| 分辨率 | `768P` / `2K` |
| 时长 | `4`–`15` 秒整数 |
| 宽高比 | `adaptive`（默认）、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` |
| 提示词 | 必填一条非空 `text`，最长 7000 字符 |
| 参考图片 | JPG/JPEG/PNG/WEBP/HEIC/HEIF；单张 ≤30MB；边长 [256, 5760]px；宽高比 [0.4, 2.5]；首帧 ≤1、尾帧 ≤1、参考图 ≤9 |
| 参考视频 | MP4/MOV（视频 H.264/HEVC，音频 AAC/MP3）；单个 ≤50MB；≤3 段，单段 2–15 秒且合计 ≤15 秒 |
| 参考音频 | WAV/MP3；单个 ≤15MB；≤3 段，单段 2–15 秒且合计 ≤15 秒 |
| 请求体大小 | 整体 ≤64MB，大文件请用公网 URL |
| 任务模式 | 异步任务：`queued → running → succeeded / failed / cancelled` |
| 任务保留 | 仅可查询近 **7 天**内的任务；成片 URL 为限时链接，请及时转存 |

<Warning>
图生视频（首帧/尾帧）与多模态参考**互斥**：同一请求不能同时出现 `first_frame`/`last_frame` 与任意 `reference_*` 角色。
</Warning>

## 端点一览

Base URL：`https://api.looprouter.com`

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/v2/video_generation` | 创建视频生成任务 |
| GET | `/v2/query/video_generation/{task_id}` | 查询单个任务 |
| GET | `/v2/query/video_generation` | 任务列表（分页/筛选） |
| DELETE | `/v2/video_generation/{task_id}` | 取消/删除任务 |
| POST | `/v2/h3_context_ir` | 提示增强（返回增强提示词，不生成视频） |
| POST | `/v2/video_regeneration` | 视频再生（768P → 2K） |

<Tip>
所有接口统一使用 `Authorization: Bearer sk-...` 请求头，API Key 在 [控制台 → 令牌](https://console.looprouter.com/keys) 创建。
</Tip>

## 模型定价

计费采用**提交预扣、完成结算**的两段式流程，不同任务类型口径不同：

| 任务类型 | 计费口径 |
| --- | --- |
| 视频生成 / 视频再生 | 按**分辨率 × 时长（秒）**计费，`768P` 与 `2K` 各有每秒单价；视频再生固定按 `2K` 结算 |
| 提示增强 Context-IR | 按 **token** 计费（`prompt_tokens` 输入 + `completion_tokens` 输出，分别核价） |

<Steps>
  <Step title="提交预扣">
    任务创建成功后按参数（分辨率、时长）预估并预扣一笔额度。视频再生无 `duration`，按最大可计费时长预扣。
  </Step>
  <Step title="完成结算">
    任务成功后按响应 `usage` 的实际用量结算（视频看 `output_seconds`，Context-IR 看 token），多退少补；任务失败或被取消全额退回。
  </Step>
</Steps>

<Info>
`768P` / `2K` 每秒单价与 Context-IR 每百万 token 单价请以控制台「模型广场」与「日志中心」展示为准。实际扣费还会应用 API Key 所在[分组](/user-groups)的计费倍率。
</Info>

## 限流与重试

- 收到 429（`rate_limit_error`）或 5xx（`server_error`）时，建议指数退避重试（2s → 4s → 8s）。
- 轮询查询接口建议间隔约 10 秒；`2K` 与长时长任务生成耗时更久，请适当延长轮询周期。

## 常见问题

<AccordionGroup>
  <Accordion title="它和豆包 Seedance 是同一个接口吗？">
    不是。MiniMax-H3 走原生 `/v2/...` 接口（无 `/api` 前缀），豆包 Seedance 走 `/api/v3/contents/generations/tasks`。请求体与响应体结构也不同，按各自文档接入。
  </Accordion>
  <Accordion title="创建任务后怎么拿到视频？">
    这是异步任务：创建返回 `task_id`，需轮询 `GET /v2/query/video_generation/{task_id}` 直到 `status` 为 `succeeded`，再从 `task.content.url` 下载成片。
  </Accordion>
  <Accordion title="支持哪些分辨率？">
    仅 `768P` 与 `2K` 两档。视频再生（regeneration）的输出恒为 `2K`。
  </Accordion>
  <Accordion title="为什么查询旧任务返回 invalid task_id？">
    任务与查询窗口仅覆盖近 7 天，超过 7 天的任务 ID 无法再查询。请在生成后尽快转存成片。
  </Accordion>
  <Accordion title="Context-IR 为什么没有视频？">
    `/v2/h3_context_ir` 只做提示增强：成功后 `task.content.prompt` 返回结构化增强提示词，`modality` 为 `text`，不产出视频。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={2}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/minimax/video-generation">
    参数、示例、查询、列表、删除、提示增强与视频再生
  </Card>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    三步跑通第一个任务
  </Card>
</CardGroup>