---
name: minimax-video-api
description: Use when calling the MiniMax H3 video generation API — submitting a video task (text-to-video / image-to-video / first-last-frame / multi-reference), querying task status, or downloading the result. Also covers the fixed 1 req/s rate limit on query/download and the off-peak (0–8) per-account concurrency limit of 5 in-flight tasks.
---

# MiniMax H3 视频生成 API 调用

## 🔑 卡密钥（使用前必填）

把下面这行里的 `sk_你的卡密钥` 替换成你自己的卡密钥（`sk_` 开头），之后所有请求都用它鉴权：

**KEY = `sk_你的卡密钥`**

## 概述

鼠鼠工具（`www.runlive.top`）的视频生成 HTTP API。外部程序用 **卡密钥 `X-Card-Key`**（`sk_` 开头）作为唯一凭证调用，与前端网页共用同一套「码即账户」计费。

**积分 = 时长（秒）× 每秒单价**（按所选分辨率），从卡里扣。

## 基础

- 接口基址：`https://www.runlive.top/mnmx`
- 每个请求带头：`X-Card-Key: sk_你的卡密钥`
- **限速**：查询 / 下载各 **1 次/秒**（固定不可改），超出 `429`；提交不限速（扣钱即限速）
- **并发（闲时）**：凌晨 0–8 点每个账号最多同时 **5 个任务**在排队/生成，做完一个才能再交一个；白天不限

## 两个任务

| task_name | 用途 | 文件字段 | 分辨率 |
|---|---|---|---|
| `minimax_h3_v2` | 文生视频 / 图生视频（首帧）/ 首尾帧 | `first_frame` / `last_frame` | 480P / 768P / 1080P |
| `minimax_h3_multi_ref` | 多参考（全能参考）视频 | `ref_0` ~ `ref_5`（图 1~6）+ `ref_audio_0` ~ `ref_audio_2`（音频 1~3） | 480P / 768P（**不支持 1080P**） |

每秒单价（积分/秒）：

| 分辨率 | 值 | v2 | multi_ref |
|---|---|---|---|
| 480P | `0.4` | 5 | 5 |
| 768P | `1` | 10 | 10 |
| 1080P | `2` | 15 | — |

## 提交任务 `POST /api/v1/tasks`

multipart 表单，成功返回 **202**，记下 `data.task_id`。

| 字段 | 必填 | 说明 |
|---|---|---|
| `task_name` | 是 | `minimax_h3_v2` / `minimax_h3_multi_ref` |
| `prompt` | 是 | 提示词 |
| `resolution` | 否 | `0.4`=480P / `1`=768P / `2`=1080P |
| `duration` | 否 | 4–15 秒 |
| `aspect_ratio` | 否 | 见下，整串填写 |
| `first_frame` / `last_frame` | 否 | 首帧/尾帧图（仅 v2） |
| `ref_0` ~ `ref_5` | 否 | 参考图 1~6（仅 multi_ref） |
| `ref_audio_0` ~ `ref_audio_2` | 否 | 参考音频 1~3（仅 multi_ref；mp3 / wav / ogg / flac / m4a / aac，总时长 ≤ 15 秒） |

`aspect_ratio` 可选值：`21:9 (Ultrawide)` / `16:9 (Widescreen)`（默认）/ `4:3 (Standard)` / `1:1 (Square)` / `3:4 (Portrait Standard)` / `9:16 (Portrait Widescreen)`。

### 文生视频（v2，不传图）

```python
r = requests.post(f"{BASE}/api/v1/tasks", headers=H, data={
    "task_name": "minimax_h3_v2",
    "prompt": "一只猫在草地上奔跑，阳光明媚，电影质感",
    "resolution": "0.4", "duration": "5", "aspect_ratio": "16:9 (Widescreen)",
})
task_id = r.json()["data"]["task_id"]
```

### 图生视频 / 首尾帧（v2）

图片走 `files`，字段名固定 `first_frame` / `last_frame`，格式 `(文件名, 文件对象, MIME)`。只传 `first_frame` = 图生视频；`first_frame`+`last_frame` = 首尾帧。

```python
r = requests.post(f"{BASE}/api/v1/tasks", headers=H, data={
    "task_name": "minimax_h3_v2", "prompt": "...", "resolution": "1", "duration": "5",
    "aspect_ratio": "16:9 (Widescreen)",
}, files={
    "first_frame": ("first.jpg", open("first.jpg", "rb"), "image/jpeg"),
    "last_frame":  ("last.jpg",  open("last.jpg",  "rb"), "image/jpeg"),
})
```

### 多参考（multi_ref，1~6 张图 + 0~3 段音频）

```python
r = requests.post(f"{BASE}/api/v1/tasks", headers=H, data={
    "task_name": "minimax_h3_multi_ref", "prompt": "保持人物长相一致，让她跳舞",
    "resolution": "1", "duration": "5", "aspect_ratio": "16:9 (Widescreen)",
}, files={
    "ref_0": ("a.jpg", open("a.jpg", "rb"), "image/jpeg"),
    "ref_1": ("b.jpg", open("b.jpg", "rb"), "image/jpeg"),
    "ref_audio_0": ("voice.mp3", open("voice.mp3", "rb"), "audio/mpeg"),
})
```

## 查询状态 `GET /api/v1/tasks/{task_id}`

`data.status` 取值：`queued` / `processing` / `completed` / `failed`。轮询间隔建议 ≥ 3 秒（限速 1/秒）。

```python
import time
while True:
    d = requests.get(f"{BASE}/api/v1/tasks/{task_id}", headers=H).json()["data"]
    if d["status"] == "completed": break
    if d["status"] == "failed":
        raise RuntimeError(d.get("error"))
    time.sleep(3)
```

## 下载结果 `GET /api/v1/tasks/{task_id}/file-url`

任务 `completed` 后调用，返回签名直链（**无需再带头**）。`url` 末尾追加 `&download=1` 触发下载而非在线播放。

```python
d = requests.get(f"{BASE}/api/v1/tasks/{task_id}/file-url", headers=H).json()["data"]
resp = requests.get(d["url"] + "&download=1")
open(d["filename"], "wb").write(resp.content)
```

## 错误码

| 码 | 含义 | 处理 |
|---|---|---|
| 202 | 提交成功 | 记下 `task_id` |
| 400 | 参数错误 | 检查字段 |
| 402 | 积分不足 | 充值 |
| 404 | 任务不存在 / 非本人 / 未完成 | 检查参数 |
| 429 | 查询/下载超 1 次/秒；或凌晨闲时并发超 5 个 | 放慢轮询 / 等任务完成再提 |
| 502 | worker 未受理（自动退款） | 稍后重试 |
| 503 | 系统维护中 | 稍后再试 |

## 常见坑

- **1080P 只有 v2 支持**：`multi_ref` 传 `resolution=2` 会被拒。
- **1080P 首尾帧**：`first_frame`+`last_frame` 都传且 `resolution=2` 时，时长最长 **10 秒**（超出拒绝提交、不扣分）。
- **下载前先等 `completed`**：`file-url` 会实时核对 worker 状态，库里状态有秒级同步延迟也不误判，未完成仍返回 404。
- **图片**：jpg / png / webp，单张 ≤ 100MB；MIME 对应 `image/jpeg` / `image/png` / `image/webp`。
- **音频（仅 multi_ref）**：mp3 / wav / ogg / flac / m4a / aac，最多 3 段，总时长 ≤ 15 秒；MIME 对应 `audio/mpeg` / `audio/wav` 等。
- **提交的 `aspect_ratio` 要整串填**，如 `"16:9 (Widescreen)"`，不是只写 `"16:9"`。

第二步：调用

创建好后，直接对你的 AI 工具说：

用 minimax-video-api 生成一个 5 秒 480P 的视频：一只猫在草地上奔跑，阳光明媚，电影质感

效果示例（点击看大图）：