> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MiniMax-H3 视频生成 API 参考
> MiniMax-H3 视频生成 API 参考与在线调试：一个端点覆盖文生、首尾帧、参考图/视频/音频生视频，异步提交 + 按 task_id 查询，768P、4–15 秒、按秒计费。
右侧的交互式 Playground 支持在线调试。在 **Authorization** 填入你的 API Key（格式 `Bearer sk-xxx`），在 `content` 里放一个文本项（需要时再加图片 / 视频 / 音频项），选好 `duration` 与 `ratio` 即可发送。发送后拿到的是 `task_id`，视频要用下文的查询接口取回。
**一个端点，四种玩法**：只放文本 = 文生视频；加 `first_frame` / `last_frame` 图片 = 首尾帧生视频；加 `reference_image` / `reference_video` / `reference_audio` = 参考素材生视频。系统按 `content[]` 自动识别，不用切换端点。能力总览见 [MiniMax-H3 概览](/api-capabilities/minimax-h3/overview)。
**⚠️ 最容易踩的四个坑**
1. **路径带 `/hailuo` 前缀**：创建是 `POST /hailuo/v2/video_generation`，查询是 `GET /hailuo/v2/query/video_generation/{task_id}`。不带前缀的 `/v2/...` 会返回网页而不是 JSON
2. **`duration` 必须是整数，范围 4–15**：传字符串 `"5"` 或小数 `5.5` 会被拒
3. **`resolution` 只能写大写 `768P`**：`768p`、`2K` 都会被拒
4. **纯文本和纯音频请求不能用 `ratio: "adaptive"`**，必须选固定比例；`adaptive` 只在带图片或视频时可用
## 代码示例
### Python（requests · 提交 + 轮询 + 下载）
```python theme={null}
import time
import requests
API_KEY = "sk-your-api-key"
BASE = "https://api.apiyi.com/hailuo/v2"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
# 第 1 步：提交任务
payload = {
"model": "MiniMax-H3",
"content": [
{"type": "text", "text": "黄昏海边的灯塔，镜头缓慢推进，海浪拍打礁石，电影级光影"}
],
"resolution": "768P", # 只支持大写 768P
"duration": 5, # 整数 4–15，按秒计费
"ratio": "16:9", # 纯文本请求必须用固定比例
}
for attempt in range(3):
# 提交本身要几秒；高峰期偶发 500，不扣费，退避后重试
r = requests.post(f"{BASE}/video_generation", headers=HEADERS, json=payload, timeout=60)
if r.status_code != 500:
break
time.sleep(5 * (attempt + 1))
r.raise_for_status()
task_id = r.json()["task_id"]
print("task_id:", task_id)
# 第 2 步：轮询（通常 2–4 分钟出片，最长等 15 分钟）
deadline = time.time() + 900
while time.time() < deadline:
task = requests.get(f"{BASE}/query/video_generation/{task_id}",
headers=HEADERS, timeout=30).json()["task"]
print(task["status"])
if task["status"] == "succeeded":
video_url = task["content"]["url"]
break
if task["status"] == "failed":
# 失败任务自动退款，error 里有原因
raise RuntimeError(task["error"])
time.sleep(10)
else:
raise TimeoutError(task_id)
# 第 3 步：下载（地址不需要鉴权；用 GET，不要用 HEAD 探活）
with requests.get(video_url, stream=True, timeout=300) as v, open("output.mp4", "wb") as f:
v.raise_for_status()
for chunk in v.iter_content(1 << 16):
f.write(chunk)
print("Saved: output.mp4")
```
### Python（首帧生视频 · 请求体片段）
```python theme={null}
payload = {
"model": "MiniMax-H3",
"content": [
{"type": "text", "text": "人物缓缓转头微笑，微风吹动发丝，镜头轻推"},
{"type": "image_url",
"image_url": {"url": "https://your-cdn.example.com/first.png"},
"role": "first_frame"},
],
"resolution": "768P",
"duration": 5,
"ratio": "adaptive", # 跟随首帧图片比例
}
```
### Python（多参考素材 · 请求体片段）
```python theme={null}
payload = {
"model": "MiniMax-H3",
"content": [
# 按同类素材的出现顺序编号：第 1 张图 = ，第 1 段视频 =