> ## 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 概覽](/zh-Hant/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 段影片 =