# MiniMax-H3 视频生成 API

> 原生 /v2 任务接口：创建、查询、列表、删除，以及提示增强（Context-IR）与视频再生（Regeneration）

MiniMax-H3 采用**异步任务**模式，接口与 MiniMax 官方 `/v2` 完全一致：先提交任务拿到 `task_id`，再轮询查询接口获取成片。已有的官方示例代码只需替换 Base URL 与 `Authorization` 即可运行。

<Warning>
**接入前请注意以下要点：**

1. Base URL 为 `https://api.looprouter.com`，端点是 `/v2/video_generation` 等，**没有** `/api` 前缀。
2. 鉴权用 LoopRouter 令牌：`Authorization: Bearer sk-...`（不是 MiniMax 官方的 JWT）。
3. `resolution` 只有 `768P` 与 `2K` 两档；`duration` 为 `4`–`15` 秒整数。
4. 成功状态是 `succeeded`；成片 `task.content.url` 为限时链接，且任务仅可查询近 **7 天**，请尽快转存。
5. 文生视频（t2v）时 `ratio` **必填且不能是 `adaptive`**；图生视频（i2v）时比例由输入图决定、`ratio` 恒按 `adaptive` 处理。
</Warning>

## 创建视频任务

`POST /v2/video_generation`

<CodeGroup>

```bash 文生视频（cURL）
curl -X POST "https://api.looprouter.com/v2/video_generation" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      { "type": "text", "text": "一个男孩在海边打篮球" }
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "16:9"
  }'

# 返回：{"task_id": "424010985738629"}
```

```python 完整流程（Python）
import time
import requests

BASE = "https://api.looprouter.com"
HEADERS = {"Authorization": "Bearer sk-你的APIKey"}

# 1. 创建任务
resp = requests.post(
    f"{BASE}/v2/video_generation",
    headers=HEADERS,
    json={
        "model": "MiniMax-H3",
        "content": [
            {"type": "text", "text": "一个男孩在海边打篮球"}
        ],
        "resolution": "2K",
        "duration": 5,
        "ratio": "16:9",
    },
)
resp.raise_for_status()
task_id = resp.json()["task_id"]
print("任务已创建:", task_id)

# 2. 轮询任务状态（建议 10 秒一次）
while True:
    task = requests.get(
        f"{BASE}/v2/query/video_generation/{task_id}",
        headers=HEADERS,
    ).json()["task"]
    status = task["status"]
    print("当前状态:", status)
    if status in ("succeeded", "failed", "cancelled"):
        break
    time.sleep(10)

# 3. 下载成片（下载时不要携带 Authorization 头）
if status == "succeeded":
    video_url = task["content"]["url"]
    with requests.get(video_url, stream=True) as r:
        r.raise_for_status()
        with open("output.mp4", "wb") as f:
            for chunk in r.iter_content(chunk_size=1 << 20):
                f.write(chunk)
    print("已保存 output.mp4")
else:
    print("任务未成功:", task.get("error"))
```

```python 图生视频与多模态参考（Python）
# 首帧图生视频：text + 1 张 first_frame 图（ratio 恒按 adaptive）
i2v_body = {
    "model": "MiniMax-H3",
    "content": [
        {"type": "text", "text": "镜头缓缓推进，人物转身微笑"},
        {"type": "image_url", "image_url": {"url": "https://example.com/first.jpg"}, "role": "first_frame"},
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "adaptive",
}

# 多模态参考：text + 参考视频 + 参考音频（不能与 first_frame/last_frame 混用）
r2v_body = {
    "model": "MiniMax-H3",
    "content": [
        {"type": "text", "text": "参考该片段的运镜与配乐节奏，生成新的城市夜景"},
        {"type": "video_url", "video_url": {"url": "https://example.com/ref.mp4"}, "role": "reference_video"},
        {"type": "audio_url", "audio_url": {"url": "https://example.com/voice.mp3"}, "role": "reference_audio"},
    ],
    "resolution": "2K",
    "duration": 6,
    "ratio": "adaptive",
}
```

```bash 查询任务（cURL）
curl "https://api.looprouter.com/v2/query/video_generation/424010985738629" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

</CodeGroup>

### 请求参数速查

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | string | 是 | — | 固定 `MiniMax-H3` |
| `content` | array | 是 | — | 多模态输入数组，见下方[内容项说明](#content-数组) |
| `resolution` | string | 是 | — | `768P` / `2K` |
| `duration` | int | 是 | — | 输出时长（秒），`4`–`15` |
| `ratio` | string | 条件 | `adaptive` | `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`；t2v 必填且不能为 `adaptive` |
| `aigc_watermark` | bool | 否 | `false` | 是否叠加 AIGC 水印 |
| `callback_url` | string | 否 | — | 任务状态变化的回调地址 |

### content 数组

每个元素是一个内容项，`type` 决定其结构，可选 `role` 指定用途：

| type | 结构 | role 取值 | 说明 |
| --- | --- | --- | --- |
| `text` | `{"type":"text","text":"..."}` | — | 提示词，**必填一条非空文本**，最长 7000 字符 |
| `image_url` | `{"type":"image_url","image_url":{"url":"..."},"role":"..."}` | `first_frame` / `last_frame` / `reference_image` | 首帧/尾帧或参考图 |
| `video_url` | `{"type":"video_url","video_url":{"url":"..."},"role":"reference_video"}` | `reference_video` | 参考视频（仅参考用途） |
| `audio_url` | `{"type":"audio_url","audio_url":{"url":"..."},"role":"reference_audio"}` | `reference_audio` | 参考音频（仅参考用途） |

**URL 支持三种形式**：公网 URL、Base64 data URI（`data:image/...`、`data:video/mp4;...`、`data:audio/...`），或已上传至 MiniMax 文件接口的 `mm_file://{file_id}`。大文件建议用公网 URL（请求体整体 ≤64MB）。

素材数量与格式限制见 [能力总览 → 技术规格](/api-capabilities/minimax/overview#技术规格)。

### 生成模式

| 模式 | content 组合 | ratio |
| --- | --- | --- |
| 文生视频（t2v） | 1 个 `text` | 必填，不能为 `adaptive` |
| 首帧图生视频（i2v） | `text` + 1 张图（`first_frame` 或不标 role） | 恒按 `adaptive` |
| 尾帧图生视频 | `text` + 1 张 `last_frame` 图 | 恒按 `adaptive` |
| 首尾帧 | `text` + `first_frame` + `last_frame` 各 1 张 | 恒按 `adaptive` |
| 多模态参考（r2v） | `text` + `reference_image` / `reference_video` / `reference_audio` | 可选，默认 `adaptive` |

<Warning>
图生视频（`first_frame`/`last_frame`）与多模态参考（`reference_*`）**互斥**，不能在同一请求中混用。
</Warning>

## 查询任务

`GET /v2/query/video_generation/{task_id}`

任务状态机：`queued → running → succeeded / failed / cancelled`。仅可查询近 **7 天**内的任务。

响应根对象包含一个 `task` 字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 任务 ID |
| `model` | string | 模型名，`MiniMax-H3` |
| `status` | string | `queued` / `running` / `succeeded` / `failed` / `cancelled` |
| `error` | object | 仅失败时返回，含 `code`、`message` |
| `created_at` / `updated_at` | int | Unix 时间戳（秒） |
| `content` | object | 输出：`url`（成片限时下载地址）或 `prompt`（Context-IR 增强提示词） |
| `resolution` | string | 输出分辨率 |
| `duration` | int | 输出时长（秒） |
| `usage` | object | 计费用量（见下） |
| `ratio` | string | 宽高比，不适用时可能为空串 |
| `task_type` | string | `generation` / `h3_context_ir` / `regeneration` |
| `modality` | string | `video` / `text` |

`usage` 字段：

| 字段 | 说明 |
| --- | --- |
| `total_seconds` | 总计费秒数（输入 + 输出） |
| `input_seconds` | 输入参考视频计费秒数 |
| `output_seconds` | 输出视频计费秒数 |
| `input_image_count` | 计费图片数 |
| `total_tokens` / `prompt_tokens` / `completion_tokens` | Context-IR 的 token 用量 |

成功响应示例：

```json
{
  "task": {
    "id": "424010985738629",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1785125529,
    "updated_at": 1785125946,
    "content": {
      "url": "https://api.looprouter.com/.../output.mp4"
    },
    "resolution": "2K",
    "duration": 5,
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 0
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}
```

失败响应示例：

```json
{
  "task": {
    "id": "424010985738630",
    "model": "MiniMax-H3",
    "status": "failed",
    "error": {
      "code": "1026",
      "message": "video description contains sensitive content"
    },
    "created_at": 1785125529,
    "updated_at": 1785125700,
    "resolution": "2K",
    "duration": 5,
    "usage": { "total_seconds": 0, "input_seconds": 0, "output_seconds": 0, "input_image_count": 0 },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}
```

<Warning>
`task.content.url` 为**限时下载链接**，请及时转存；下载时请求中**不要**携带 `Authorization` 头。
</Warning>

## 任务列表

`GET /v2/query/video_generation`

分页查询近 7 天的任务，可按状态、任务 ID、模型、任务类型筛选。全部为可选查询参数：

| 参数 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `page_num` | int | `1` | 页码，从 1 开始 |
| `page_size` | int | `20` | 每页数量 |
| `filter.status` | string | — | `queued` / `running` / `succeeded` / `failed` / `cancelled` |
| `filter.task_ids` | array | — | 按任务 ID 列表过滤 |
| `filter.model` | string | — | 模型名，如 `MiniMax-H3` |
| `filter.task_type` | string | — | `generation` / `h3_context_ir` / `regeneration` |

响应为 `{"items": [ ...VideoTask ], "total": n}`，元素结构与查询单个任务的 `task` 一致。

```bash
curl "https://api.looprouter.com/v2/query/video_generation?page_num=1&page_size=20" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

## 取消 / 删除任务

`DELETE /v2/video_generation/{task_id}`

按任务当前状态执行不同动作：

| 当前状态 | 动作 | 说明 |
| --- | --- | --- |
| `queued` | `cancelled` | 处理前取消，不计费 |
| `succeeded` | `deleted` | 删除任务记录 |
| `failed` | `deleted` | 删除任务记录 |
| `running` | — | 不可操作，返回错误 |
| `cancelled` | — | 不可操作，返回错误 |

响应：

```json
{
  "task_id": "424010985738629",
  "action": "cancelled",
  "status": "cancelled"
}
```

该端点同样适用于 Context-IR 与视频再生的任务记录。

## 提示增强 · Context-IR

`POST /v2/h3_context_ir`

理解多模态上下文，输出一段**结构化增强提示词**，用于提升后续视频生成质量。它**不生成视频**：成功后 `task.content.prompt` 返回增强提示词，`modality` 为 `text`，按 token 计费。

请求参数与视频生成基本一致（`model`、`content`、`duration` 必填，`ratio`、`callback_url` 可选），差别是**没有** `resolution`。

```bash
curl -X POST "https://api.looprouter.com/v2/h3_context_ir" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      { "type": "text", "text": "一个男孩在海边打篮球" }
    ],
    "duration": 5,
    "ratio": "16:9"
  }'

# 返回：{"task_id": "426586401755526"} —— 轮询查询接口获取增强提示词
```

查询成功示例（`task_type` 为 `h3_context_ir`，`content.prompt` 承载增强提示词）：

```json
{
  "task": {
    "id": "426586401755526",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "content": {
      "prompt": "integrated_multimodal_description: [Shot 1] ... overall_soundscape: ... non_diegetic_music: ..."
    },
    "duration": 5,
    "usage": {
      "total_tokens": 9090,
      "prompt_tokens": 5664,
      "completion_tokens": 3426
    },
    "ratio": "16:9",
    "task_type": "h3_context_ir",
    "modality": "text"
  }
}
```

## 视频再生 · Regeneration

`POST /v2/video_regeneration`

将符合 MiniMax-H3 **768P** 输出规格的源视频重生成为 **2K** 高清。输出恒为 `2K`，无需 `duration`。可用两种方式指定源视频，**二选一**（不能同时提供，也不能都不提供）：

<Tabs>
  <Tab title="方式一：按任务 ID">
    直接引用一个已成功的 `/v2/video_generation` 任务：

    | 字段 | 类型 | 必填 | 说明 |
    | --- | --- | --- | --- |
    | `model` | string | 是 | `MiniMax-H3` |
    | `source_task_id` | string | 是 | 源任务 ID，需属于当前账号、状态 `succeeded`、仍在 7 天查询窗口内 |
    | `resolution` | string | 是 | `2K` |
    | `aigc_watermark` | bool | 否 | 默认 `false` |
    | `callback_url` | string | 否 | 回调地址 |

    ```json
    {
      "model": "MiniMax-H3",
      "source_task_id": "424010985738629",
      "resolution": "2K"
    }
    ```
  </Tab>
  <Tab title="方式二：按源视频">
    `content` 必须包含生成 768P 源视频时的**全部原始输入**，外加**恰好一个** `type=video_url`、`role=base_video` 的源视频项。其中 `text` 必须是生成 768P 源视频时实际送入模型的最终 prompt（单条最长 40000 字符）。

    | 字段 | 类型 | 必填 | 说明 |
    | --- | --- | --- | --- |
    | `model` | string | 是 | `MiniMax-H3` |
    | `content` | array | 是 | 原始输入 + 1 个 `base_video` 源视频项 |
    | `resolution` | string | 是 | `2K` |
    | `aigc_watermark` | bool | 否 | 默认 `false` |
    | `callback_url` | string | 否 | 回调地址 |

    ```json
    {
      "model": "MiniMax-H3",
      "content": [
        { "type": "text", "text": "生成 768P 源视频时使用的最终 prompt" },
        {
          "type": "video_url",
          "video_url": { "url": "https://your-cdn.example.com/h3-768p.mp4" },
          "role": "base_video"
        }
      ],
      "resolution": "2K"
    }
    ```

    **`base_video` 源视频规格**：必须带音轨；帧率 24fps；宽高各能被 32 整除；面积（宽 × 高）≤ 768 × 1344（1,032,192 像素）；总帧数 107–362 帧（约 4–15 秒）。
  </Tab>
</Tabs>

两种方式都返回 `{"task_id": "..."}`，轮询查询接口获取结果；成功任务的 `task_type` 为 `regeneration`。

## 错误响应

所有错误采用 MiniMax 原生结构（顶层含 `type: "error"`）：

```json
{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "rate limit, please retry later (1002)",
    "http_code": "429"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}
```

| HTTP 状态码 | error.type | 常见原因 |
| --- | --- | --- |
| 400 | `bad_request_error` | 参数错误，如缺少非空 `text`、`resolution`/`duration` 取值非法 |
| 401 | `authorized_error` | API Key 缺失或无效 |
| 402 | `insufficient_balance_error` | 余额不足 |
| 422 | `unprocessable_entity_error` | 内容审核未通过（如涉敏内容） |
| 429 | `rate_limit_error` | 触发限流，请稍后重试 |
| 500 | `server_error` | 服务端异常，建议指数退避后重试 |

<Info>
错误 `message` 末尾括号内为上游内部错误码（如 `(1002)`）。429 与 5xx 建议指数退避重试（2s → 4s → 8s）。
</Info>

## 在线调试（试一试）

在 API 参考中可对每个 `/v2` 端点直接发起真实请求：

<CardGroup cols={3}>
  <Card title="创建视频任务" icon="flask" href="/api-reference/minimax/create-video-task">
    POST /v2/video_generation
  </Card>
  <Card title="查询任务" icon="flask" href="/api-reference/minimax/get-video-task">
    GET /v2/query/video_generation/{task_id}
  </Card>
  <Card title="任务列表" icon="flask" href="/api-reference/minimax/list-video-tasks">
    GET /v2/query/video_generation
  </Card>
  <Card title="取消 / 删除" icon="flask" href="/api-reference/minimax/delete-video-task">
    DELETE /v2/video_generation/{task_id}
  </Card>
  <Card title="提示增强 Context-IR" icon="flask" href="/api-reference/minimax/h3-context-ir">
    POST /v2/h3_context_ir
  </Card>
  <Card title="视频再生 768P→2K" icon="flask" href="/api-reference/minimax/video-regeneration">
    POST /v2/video_regeneration
  </Card>
</CardGroup>

## 相关文档

<CardGroup cols={2}>
  <Card title="能力总览与定价" icon="circle-info" href="/api-capabilities/minimax/overview">
    模型清单、技术规格、计费规则
  </Card>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    三步跑通第一个任务
  </Card>
</CardGroup>