MiniMax H3 · MiniMax 格式

接入说明

MiniMax 格式的接口和 MiniMax 开放平台的「视频生成 V2」接口一致：路径、请求参数、返回结果、任务状态、回调和错误格式都相同，用来调用 MiniMax H3 系列模型。已经接入 MiniMax 的代码，换掉接口地址和 API Key 就能使用。

从 MiniMax 迁移

只需要改下面两项，模型 ID、请求参数和处理返回结果的代码都不用改：

配置	MiniMax	本平台
接口地址	`https://api.minimaxi.com`（国内）或 `https://api.minimax.io`（海外）	https://your-domain/minimax
API Key	MiniMax 开放平台创建的 API Key	在控制台 → API Keys创建
模型 ID	`MiniMax-H3`、`MiniMax-H3-Max`	相同，见模型与价格

接口路径和 MiniMax 相同，接在接口地址后面，例如创建任务是 https://your-domain/minimax/v2/video_generation。API Key 同样放在 Authorization: Bearer ... 请求头里。

接口地址也可以不带 /minimax，直接写成 https://your-domain，路径同样以 /v2/ 开头。

接口列表

下表的路径接在接口地址后面，和 MiniMax 相同。

接口	方法和路径	说明
创建视频生成任务	POST`/v2/video_generation`	提交任务，返回任务 ID
查询视频生成任务	GET`/v2/query/video_generation/{task_id}`	查询任务状态，成功后返回视频地址
查询视频生成任务列表	GET`/v2/query/video_generation`	最近 7 天的任务，可以按状态、任务 ID 或模型筛选
取消视频生成任务	DEL`/v2/video_generation/{task_id}`	取消排队中的任务，退回费用

完整示例

这组接口直接用 HTTP 调用，cURL、Python 的 requests、Node.js 的 fetch 或任意 HTTP 库都可以。下面的例子提交任务后每 10 秒查询一次，成功后把视频保存到本地：

minimax_quickstart.py

import os
import time

import requests

BASE_URL = "https://your-domain/minimax"
HEADERS = {"Authorization": f"Bearer {os.environ['MINIMAX_API_KEY']}"}

# 提交任务
resp = requests.post(
    f"{BASE_URL}/v2/video_generation",
    headers=HEADERS,
    json={
        "model": "MiniMax-H3",
        "content": [{"type": "text", "text": "清晨的海边，一只金毛犬沿着浪花奔跑，镜头缓慢跟随，阳光穿过薄雾"}],
        "resolution": "768P",
        "duration": 6,
        "ratio": "16:9"
    },
)
data = resp.json()
if not resp.ok:
    raise SystemExit(data["error"]["message"])
task_id = data["task_id"]
print("任务 ID:", task_id)

# 每 10 秒查询一次，直到任务结束
while True:
    time.sleep(10)
    resp = requests.get(f"{BASE_URL}/v2/query/video_generation/{task_id}", headers=HEADERS)
    task = resp.json()["task"]
    print(task["status"])
    if task["status"] not in ("queued", "running"):
        break

if task["status"] == "succeeded":
    video = requests.get(task["content"]["url"])
    with open("video.mp4", "wb") as f:
        f.write(video.content)
    print("已保存到 video.mp4")
else:
    print("任务没有成功:", task["status"], task.get("error"))

各接口的 cURL、Python、Node.js 写法见对应的接口页面。不想轮询的话，可以在创建任务时传 callback_url，见回调通知。

与 MiniMax 的差异

文生视频、图生视频（首帧、尾帧、首尾帧）、提示词优化（extra.prompt_expansion_mode）、AIGC 水印和回调通知都和 MiniMax 一致。下面这些地方有所不同：

项目	MiniMax	本平台
支持的接口	视频生成 V1、V2，以及文件管理等其他接口	只支持上面四个视频生成 V2 接口。V1 接口（`/v1/video_generation`）不支持，可以改用 V2 接口或OpenAI 格式
多模态参考	两个模型都支持	只有生成方式里有「参考生成」的模型能用，见模型与价格；其他模型返回 400（2013）
`mm_file://`	可以引用上传到 MiniMax 的文件	不支持，请改用素材链接或 Base64
Base64 图片	单张不超过 30 MB	单张不超过 10 MB，更大的图片请传链接
`filter.task_type`	可以查询 generation、h3_context_ir、regeneration 类型的任务	只有 generation（视频生成）任务，查询其他类型时返回空列表
DELETE 已结束的任务	删除任务记录	不删除，返回 400
视频地址（content.url）	MiniMax 的下载地址	视频转存到本平台，可以长期访问
`error.message`	MiniMax 的错误说明，末尾带错误码	中文说明，末尾同样带错误码，例如 (2013)
任务 ID	MiniMax 生成的 ID	以 `video_` 开头

视频转存失败时会退回使用 MiniMax 的原始地址，这种地址可能会过期。建议拿到视频后及时下载到自己的存储。

和其他格式互通

各种格式的任务是同一份：用 MiniMax 格式创建的任务，也可以用 GET /v1/videos/{id} 查询，或者用 GET /v1/videos/{id}/content 下载视频；用 OpenAI 格式或在控制台创建的 MiniMax 任务，也能用 MiniMax 格式查询和取消。所有任务都能在控制台 → 视频任务里看到。

这组接口只能调用 MiniMax H3 系列模型，传其他模型会返回 400，其他模型请用 OpenAI 格式调用。

错误处理

出错时返回 HTTP 4xx 或 5xx 状态码，返回结果是 MiniMax 的错误格式 {"type": "error", "error": {...}, "request_id": "..."}，error.message 末尾的括号里是 MiniMax 的错误码。错误码列表和处理方法见错误码。