MiniMax H3 视频生成 API 对接文档

服务商：andonai.cn ｜接口契约对标 MiniMax 官方 API ｜ v1.1 · 基于 2026-08-19 v1.0 补充 2K

一、快速上手

1. 基础信息

Open API Basehttps://andonai.cn/v2

站点 Originhttps://andonai.cn

鉴权Authorization: Bearer <API_KEY>

模型

MiniMax-H3 ｜ 输出 768P / 2K / 24fps / 32kHz 立体声 ｜ 时长 4-15 秒 ｜ 画幅 16:9 / 9:16 / 1:1 / 3:4 / 4:3 / 21:9

必须使用 HTTPS（当前可用：https://andonai.cn/v2）。勿用 http://andonai.cn —— 会 301 跳转到 https，部分客户端会把 POST 变成 GET，返回 405 Method Not Allowed。

2. 文生视频请求（curl）

curl -X POST "https://andonai.cn/v2/video_generation" \
  -H "Authorization: Bearer <你的API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "写实电影质感，中景：一位老人在雨天街角撑伞独行，镜头缓慢推近。"}
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9"
  }'

2. 文生视频请求 · 2K（curl）

curl -X POST "https://andonai.cn/v2/video_generation" \
  -H "Authorization: Bearer <你的API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "写实电影质感，中景：一位老人在雨天街角撑伞独行，镜头缓慢推近。"}
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "16:9"
  }'

成功响应：{"task_id": "4691e249-...", "status": "pending", "h3_task": "t2va"}

3. 查询任务 / 下载成片

# 查询状态
curl "https://andonai.cn/v2/query/video_generation?task_id=" \
  -H "Authorization: Bearer <你的API_KEY>"

# 下载成片
curl -o output.mp4 "https://andonai.cn/api/task//download" \
  -H "Authorization: Bearer <你的API_KEY>"

二、API 端点总览

操作	方法	路径	说明
上传素材	POST	/v1/files/upload	上传图片 / 视频 / 音频
创建生成任务	POST	/v2/video_generation	提交视频生成（5 种模式 · 768P / 2K）
查询任务	GET	/v2/query/video_generation	查询状态（task_id 走 query 参数）
下载成片	GET	/api/task/{task_id}/download	下载视频文件

三、上传素材

curl -X POST "https://andonai.cn/v1/files/upload" \
  -H "Authorization: Bearer <你的API_KEY>" \
  -F "purpose=video_generation_input" \
  -F "file=@/path/to/ref_image.png"

响应：{"file": {"file_id": 1787125059072928, "mm_file": "mm_file://1787125059072928", ...}}

类型	上限	说明
图片	最多 9 张	宽高 256-5760px
视频	最多 3 段	单段 2-15s，总时长 ≤15s，≤50MB
音频	最多 3 段	单段 2-15s，≤15MB，必须搭配图 / 视频

注意：mm_file 引用有效期 7 天，过期需重新上传。

四、五种生成模式

请求体通用结构

{
  "model": "MiniMax-H3",
  "content": [...],              // 多模态内容数组
  "resolution": "768P",          // 768P 或 2K
  "duration": 5,                 // 4-15 秒整数
  "ratio": "16:9",               // 画幅
  "callback_url": "https://..."  // 可选：任务完成回调
}

传 "resolution": "2K" 即可一步创建 2K 任务（与 768P 同一接口）。

① T2VA 文生视频

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "写实电影质感，中景：一位老人在雨天街角撑伞独行，镜头缓慢推近 ..."}
  ],
  "resolution": "768P",
  "duration": 10,
  "ratio": "16:9"
}

① T2VA 文生视频 · 2K

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "写实电影质感，中景：一位老人在雨天街角撑伞独行，镜头缓慢推近 ..."}
  ],
  "resolution": "2K",
  "duration": 10,
  "ratio": "16:9"
}

② I2VA 图生视频（首帧）

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "以首帧图为起点，镜头缓慢推近，画面逐渐展开 ..."},
    {"type": "image_url", "image_url": {"url": "mm_file://xxx"}, "role": "first_frame"}
  ],
  "resolution": "768P",
  "duration": 10,
  "ratio": "16:9"
}

② I2VA 图生视频（首帧） · 2K

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "以首帧图为起点，镜头缓慢推近，画面逐渐展开 ..."},
    {"type": "image_url", "image_url": {"url": "mm_file://xxx"}, "role": "first_frame"}
  ],
  "resolution": "2K",
  "duration": 10,
  "ratio": "16:9"
}

③ FL2VA 首尾帧

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "描述首尾之间的运动路径 ..."},
    {"type": "image_url", "image_url": {"url": "mm_file://xxx"}, "role": "first_frame"},
    {"type": "image_url", "image_url": {"url": "mm_file://xxx"}, "role": "last_frame"}
  ],
  "resolution": "768P",
  "duration": 8,
  "ratio": "16:9"
}

③ FL2VA 首尾帧 · 2K

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "描述首尾之间的运动路径 ..."},
    {"type": "image_url", "image_url": {"url": "mm_file://xxx"}, "role": "first_frame"},
    {"type": "image_url", "image_url": {"url": "mm_file://xxx"}, "role": "last_frame"}
  ],
  "resolution": "2K",
  "duration": 8,
  "ratio": "16:9"
}

④ L2VA 尾帧

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "推断合理开头，动作逐步收敛到尾帧构图 ..."},
    {"type": "image_url", "image_url": {"url": "mm_file://xxx"}, "role": "last_frame"}
  ],
  "resolution": "768P",
  "duration": 6,
  "ratio": "16:9"
}

④ L2VA 尾帧 · 2K

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "推断合理开头，动作逐步收敛到尾帧构图 ..."},
    {"type": "image_url", "image_url": {"url": "mm_file://xxx"}, "role": "last_frame"}
  ],
  "resolution": "2K",
  "duration": 6,
  "ratio": "16:9"
}

⑤ Ref2VA 多参考（≤9 图 +3 视频 +3 音频）

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "使用图片 1 控制角色，图片 2 控制场景 ...（六段式提示词）"},
    {"type": "image_url", "image_url": {"url": "mm_file://xxx"}, "role": "reference_image"},
    {"type": "image_url", "image_url": {"url": "mm_file://xxx"}, "role": "reference_image"},
    {"type": "video_url", "video_url": {"url": "mm_file://xxx"}, "role": "reference_video"},
    {"type": "audio_url", "audio_url": {"url": "mm_file://xxx"}, "role": "reference_audio"}
  ],
  "resolution": "768P",
  "duration": 15,
  "ratio": "16:9"
}

⑤ Ref2VA 多参考（≤9 图 +3 视频 +3 音频） · 2K

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "使用图片 1 控制角色，图片 2 控制场景 ...（六段式提示词）"},
    {"type": "image_url", "image_url": {"url": "mm_file://xxx"}, "role": "reference_image"},
    {"type": "image_url", "image_url": {"url": "mm_file://xxx"}, "role": "reference_image"},
    {"type": "video_url", "video_url": {"url": "mm_file://xxx"}, "role": "reference_video"},
    {"type": "audio_url", "audio_url": {"url": "mm_file://xxx"}, "role": "reference_audio"}
  ],
  "resolution": "2K",
  "duration": 15,
  "ratio": "16:9"
}

自动路由：仅文本 → T2VA；传 first_frame → I2VA；first+last → FL2VA；reference_* → Ref2VA。

五、查询与状态

状态枚举：pending（排队） / queued（等待 Worker） / running（生成中） / succeeded（完成） / failed（失败） / cancelled（取消）

成功响应含 content.url（/static/outputs/{task_id}.mp4），可拼 Base URL 直接下载。

六、错误码

HTTP	code	说明
400	2013	参数错误（content 缺 text / task_id 无效等）
401	1004	鉴权失败（Key 无效）
402	1008	余额 / 积分不足
429	1002	请求频率超限
422	1026	内容含敏感信息
500	1000	服务内部错误

七、Python 接入示例

Python · 768P

import requests, time
BASE = "https://andonai.cn"
KEY = "sk-你的KEY"
H = {"Authorization": f"Bearer {KEY}"}
# 1. 上传参考图
with open("ref.png", "rb") as f:
    mm = requests.post(f"{BASE}/v1/files/upload", headers=H,
        files={"file": f}, data={"purpose": "video_generation_input"}).json()["file"]["mm_file"]
# 2. 创建任务（ref2va）
r = requests.post(f"{BASE}/v2/video_generation", headers=H, json={
    "model": "MiniMax-H3",
    "content": [
        {"type": "text", "text": "提示词 ..."},
        {"type": "image_url", "image_url": {"url": mm}, "role": "reference_image"}
    ],
    "resolution": "768P", "duration": 10, "ratio": "16:9"
})
tid = r.json()["task_id"]
# 3. 轮询状态
while True:
    t = requests.get(f"{BASE}/v2/query/video_generation", headers=H,
        params={"task_id": tid}).json()["task"]
    if t["status"] == "succeeded":
        break
    time.sleep(5)
# 4. 下载
open("output.mp4", "wb").write(requests.get(f"{BASE}/api/task/{tid}/download",
headers=H).content)

Python · 2K

import requests, time
BASE = "https://andonai.cn"
KEY = "sk-你的KEY"
H = {"Authorization": f"Bearer {KEY}"}
# 1. 上传参考图
with open("ref.png", "rb") as f:
    mm = requests.post(f"{BASE}/v1/files/upload", headers=H,
        files={"file": f}, data={"purpose": "video_generation_input"}).json()["file"]["mm_file"]
# 2. 创建任务（ref2va）
r = requests.post(f"{BASE}/v2/video_generation", headers=H, json={
    "model": "MiniMax-H3",
    "content": [
        {"type": "text", "text": "提示词 ..."},
        {"type": "image_url", "image_url": {"url": mm}, "role": "reference_image"}
    ],
    "resolution": "2K", "duration": 10, "ratio": "16:9"
})
tid = r.json()["task_id"]
# 3. 轮询状态
while True:
    t = requests.get(f"{BASE}/v2/query/video_generation", headers=H,
        params={"task_id": tid}).json()["task"]
    if t["status"] == "succeeded":
        break
    time.sleep(5)
# 4. 下载
open("output.mp4", "wb").write(requests.get(f"{BASE}/api/task/{tid}/download",
headers=H).content)

八、计费说明

模式	价格	说明
T2VA 文生	按秒计费	768P / 2K 档
I2VA 图生	按秒计费 + 图片输入	—
FL2VA 首尾帧	按秒计费 + 图片输入	—
Ref2VA 多参考	按秒计费 + 多模态输入	参考素材越多消耗越高

注意：余额不足返回 402，充值后重试。具体单价请咨询服务商。

九、常见问题

Q1 提示词怎么写？三段式结构（integrated_multimodal_description / overall_soundscape / non_diegetic_music），镜头数按时长：5s≤2 镜、10s≤3 镜、15s≤5 镜。

Q2 mm_file 有效期？ 7 天，过期重新上传。

Q3 参考图要求？ ≥1344×768，脸部无遮挡、光线干净。

Q4 时长如何选？测试 5s / 剧情 10s / 完整短剧单元 15s。

Q5 如何出 2K？与 768P 同一创建接口，将 resolution 设为 "2K" 即可（见上文各 2K 示例）。

Q6 调用返回 405？请确认 Open API Base 为 https://andonai.cn/v2（勿用 http）。HTTP 会跳转 HTTPS，部分库会把 POST 改成 GET。