minimax-h3 — 接入指南
model 使用本頁的精確 ID。只可呼叫下表列出的介面；未列出的介面不屬於此型號的接入範圍。
model: minimax-h3
模型與介面
| 支援的介面 | HTTP |
|---|---|
videos.generations | POST /v1/videos/generations |
準備與驗證
所有範例從環境變數讀取 ZAI_API_KEY。Python 範例使用標準函式庫，毋須安裝 SDK。金鑰只應存放於伺服器，不應放進瀏覽器程式。請求可能收費，範例只產生少量內容。
export ZAI_API_KEY="<your-api-key>"
參數與限制
以下為本平台的最小請求配置，並非所有可選值或最大限制。未列出的進階參數尚未由本指南驗證，請勿直接套用其他廠商或型號的參數表。
已驗證配置：duration=5 秒、resolution=768P、aspect_ratio=16:9，以及純文字 prompt；另驗證了首幀 image（data URL 或公開 https 連結）與兩張 reference_images。resolution 只有 768P 一檔；duration 為 1–15 的整數；aspect_ratio 可選 21:9、16:9、4:3、1:1、3:4、9:16。成片一律帶音軌，不接受 generate_audio。首尾幀與 reference_images 不可在同一請求同時使用；reference_images 最多 9 張，提示詞按陣列順序以 <Picture 1>、<Picture 2>… 指認（英文尖括號、首字母大寫、詞與序號之間一個空格，寫錯只當普通文字），首尾幀不佔編號。prompt 不超過 7000 個字元。last_frame、reference_audios 不在本頁已驗證範圍；seed、watermark 及負向提示詞不支援。
完整呼叫範例
import json
import os
import urllib.error
import urllib.request
BASE = "https://api.ourzai.com/v1"
KEY = os.environ["ZAI_API_KEY"]
def call(path, body=None, timeout=180):
headers = {"Authorization": f"Bearer {KEY}"}
data = None
if body is not None:
headers["Content-Type"] = "application/json"
data = json.dumps(body).encode("utf-8")
request = urllib.request.Request(BASE + path, data=data, headers=headers)
try:
with urllib.request.urlopen(request, timeout=timeout) as response:
return response.read()
except urllib.error.HTTPError as error:
raise RuntimeError(f"HTTP {error.code}: {error.read().decode(errors='replace')}") from error
import time
from pathlib import Path
from urllib.parse import quote
created = json.loads(
call(
"/videos/generations",
{
"model": "minimax-h3",
"prompt": "A red mug on a table, slow camera movement",
"duration": 5,
"resolution": "768P",
"aspect_ratio": "16:9",
},
)
)
task_id = created.get("request_id") or created.get("id")
if not task_id:
raise RuntimeError(created)
print("task_id:", task_id, flush=True)
path = "/videos/" + quote(task_id, safe="")
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
status = json.loads(call(path))
if status.get("status") == "done":
Path("result.mp4").write_bytes(call(path + "/content"))
break
if status.get("status") in ("failed", "expired"):
raise RuntimeError(status)
time.sleep(5)
else:
raise TimeoutError(f"Keep task ID {task_id} and query its status later")
結果與錯誤處理
提交成功不表示影片已完成。範例兼容 request_id/id，輪詢 pending → done，再以同一金鑰下載 /content；video.url 可能是相對路徑。failed/expired 為終態；409 表示尚未完成。下載須保留驗證，但不可將金鑰送至其他網域。客戶端逾時後先查詢既有任務，避免重複提交收費。
此目錄說明接入方式，不代表即時可用性。以 GET /v1/models 確認金鑰可見的模型，價格見控制台。已列出的模型仍可能因上游故障或冷卻回傳 502/503；請等待並以退避方式重試。