快速回答
MiniMax H3 官方 API 使用 V2 异步调用流程。向 https://api.minimax.io/v2/video_generation 发送 POST 请求，模型 ID 填 MiniMax-H3，并传入必填的 content[]、resolution: "2K"、4 到 15 秒整数时长，以及与生成模式匹配的画幅。接口会返回 task_id。随后大约每 10 秒轮询一次 GET https://api.minimax.io/v2/query/video_generation/{task_id}，直到状态变为 succeeded，或进入终止失败状态。任务成功后，视频地址直接位于 task.content.url。H3 V2 不需要旧接口中的 file_id 换取步骤。
API Key 必须留在服务端，并通过 Authorization: Bearer <API_KEY> 发送。H3 当前 2K 按量付费标价为每个输出秒 $0.13。下方示例已按 2026 年 8 月 2 日官方 schema 核对，但没有发起付费生成请求。minimaxh3.tv 是独立网站，不是 MiniMax 官方 API 服务。
V2 创建任务后返回 task_id。轮询任务直到成功或进入终止失败状态，只有成功状态才会提供 content.url。示意图依据官方 V2 指南制作，核验日期为 2026 年 8 月 2 日。
准备账号与 API Key
登录 MiniMax API Platform，在 Account Management > API Keys 中创建按量付费 Key，再把它放入服务端环境变量。MiniMax 将标准按量付费 Key 与 Token Plan 或 Credits Key 分开管理。发送付费视频请求前，应先确认当前 Key 使用哪一种余额。
export MINIMAX_API_KEY="replace-with-your-server-side-key"
创建任务和查询任务都使用同一个请求头：
Authorization: Bearer <API_KEY>
不要把 Key 写进浏览器 JavaScript、移动端安装包、公开仓库、截图或客户端可见日志。浏览器请求应先进入你自己的鉴权后端，由后端限制用户额度和并发。
H3 模型 ID 与生成模式
官方 V2 模型 ID 是 MiniMax-H3。三种模式共用一个创建接口，具体模式由 content[] 中的对象和 role 决定。
| 模式 | content[] 必填项 |
画幅规则 |
|---|---|---|
| 文生视频 | 一个非空 text 项 |
必填，可选 21:9、16:9、4:3、1:1、3:4、9:16 |
| 首帧或尾帧生成 | text 加 1 到 2 个 image_url，角色为 first_frame 和/或 last_frame |
由输入图片决定，接口按 adaptive 处理 |
| 参考生成 | text 加 reference_image、reference_video 或 reference_audio |
可选，默认 adaptive |
每个请求都必须有非空文本。参考音频不能单独使用，至少还要有一张参考图片或一个参考视频。首尾帧角色与参考角色不能出现在同一个请求中。
H3 V2 的三类有效 content[] 组合。文本始终必填；首尾帧角色不能与参考角色混用；参考音频需要同时提供图片或视频。依据 2026 年 8 月 2 日官方创建任务 schema 核验。
创建视频任务
下面的最小 cURL 请求会创建一个 5 秒、2K、16:9 的文生视频任务：
curl --request POST \
--url https://api.minimax.io/v2/video_generation \
--header "Authorization: Bearer ${MINIMAX_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "A paper boat crosses a rain-filled street while the camera tracks beside it."
}
],
"resolution": "2K",
"duration": 5,
"ratio": "16:9"
}'
创建成功后会得到任务 ID：
{
"task_id": "424010985738629"
}
后端应先保存这个 ID，再向客户端返回结果。任务记录还应保留用户、请求指纹、提交时间和当前状态，避免应用重启后丢失任务。
轮询任务状态
使用创建接口返回的 ID 查询 V2 任务：
curl --request GET \
--url "https://api.minimax.io/v2/query/video_generation/${TASK_ID}" \
--header "Authorization: Bearer ${MINIMAX_API_KEY}"
MiniMax 指南建议每 10 秒查询一次。应用需要明确处理以下状态：
| 状态 | 应用处理方式 |
|---|---|
queued |
等待后再次查询 |
running |
等待后再次查询 |
succeeded |
读取 task.content.url 并保存结果 |
failed |
停止查询并记录 task.error |
cancelled |
停止查询 |
expired |
停止查询，任务已没有可用结果 |
应用应设置最长等待时间，不要无限轮询。本地超时不能证明上游任务失败，因此需要保留 task_id，稍后继续核对状态。
下载结果
H3 V2 会在成功的查询响应中直接给出结果地址：
{
"task": {
"id": "424010985738629",
"model": "MiniMax-H3",
"status": "succeeded",
"content": {
"url": "https://example-cdn.invalid/generated-video.mp4"
},
"resolution": "2K",
"duration": 5,
"ratio": "16:9"
}
}
该结果地址有时效限制。后端应尽快读取，并把视频保存到你控制的存储中。不要把 H3 V2 接入建立在旧版 /v1/files/retrieve 接口上，因为当前 V2 查询响应已经包含 content.url。
Python 示例
import os
import time
from pathlib import Path
import requests
BASE_URL = "https://api.minimax.io"
API_KEY = os.environ["MINIMAX_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def create_task() -> str:
payload = {
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "A paper boat crosses a rain-filled street while the camera tracks beside it.",
}
],
"resolution": "2K",
"duration": 5,
"ratio": "16:9",
}
response = requests.post(
f"{BASE_URL}/v2/video_generation",
headers=HEADERS,
json=payload,
timeout=30,
)
response.raise_for_status()
return response.json()["task_id"]
def wait_for_result(task_id: str, timeout_seconds: int = 1800) -> str:
deadline = time.monotonic() + timeout_seconds
while time.monotonic() < deadline:
time.sleep(10)
response = requests.get(
f"{BASE_URL}/v2/query/video_generation/{task_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
response.raise_for_status()
task = response.json()["task"]
if task["status"] == "succeeded":
return task["content"]["url"]
if task["status"] in {"failed", "cancelled", "expired"}:
raise RuntimeError(f"Task ended with {task['status']}: {task.get('error')}")
raise TimeoutError(f"Task {task_id} did not finish before the local timeout")
def save_video(url: str, destination: str = "output.mp4") -> None:
with requests.get(url, stream=True, timeout=120) as response:
response.raise_for_status()
with Path(destination).open("wb") as output:
for chunk in response.iter_content(chunk_size=1024 * 1024):
output.write(chunk)
task_id = create_task()
save_video(wait_for_result(task_id))
JavaScript 示例
下面的写法使用当前 Node.js 自带的 fetch：
import { writeFile } from "node:fs/promises";
const baseUrl = "https://api.minimax.io";
const apiKey = process.env.MINIMAX_API_KEY;
if (!apiKey) throw new Error("MINIMAX_API_KEY is missing");
async function requestJson(url, options = {}) {
const response = await fetch(url, options);
if (!response.ok) {
throw new Error(`${response.status}: ${await response.text()}`);
}
return response.json();
}
async function createTask() {
const data = await requestJson(`${baseUrl}/v2/video_generation`, {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "MiniMax-H3",
content: [
{
type: "text",
text: "A paper boat crosses a rain-filled street while the camera tracks beside it.",
},
],
resolution: "2K",
duration: 5,
ratio: "16:9",
}),
});
return data.task_id;
}
async function waitForResult(taskId) {
for (let attempt = 0; attempt < 180; attempt += 1) {
await new Promise((resolve) => setTimeout(resolve, 10_000));
const data = await requestJson(
`${baseUrl}/v2/query/video_generation/${taskId}`,
{ headers: { Authorization: `Bearer ${apiKey}` } },
);
const { status, content, error } = data.task;
if (status === "succeeded") return content.url;
if (["failed", "cancelled", "expired"].includes(status)) {
throw new Error(`Task ended with ${status}: ${JSON.stringify(error)}`);
}
}
throw new Error(`Task ${taskId} exceeded the local wait limit`);
}
const taskId = await createTask();
const videoUrl = await waitForResult(taskId);
const videoResponse = await fetch(videoUrl);
if (!videoResponse.ok) throw new Error(`Download failed: ${videoResponse.status}`);
await writeFile("output.mp4", Buffer.from(await videoResponse.arrayBuffer()));
文本、首尾帧与参考负载的区别
content[] 取代了按生成模式区分 H3 模型 ID 的做法。所有模式都使用同一个 MiniMax-H3，只改变其中的角色。
首尾帧生成
{
"model": "MiniMax-H3",
"content": [
{ "type": "text", "text": "The paper sketch becomes a finished product render." },
{
"type": "image_url",
"image_url": { "url": "https://example.com/start.png" },
"role": "first_frame"
},
{
"type": "image_url",
"image_url": { "url": "https://example.com/end.png" },
"role": "last_frame"
}
],
"resolution": "2K",
"duration": 5
}
多模态参考生成
{
"model": "MiniMax-H3",
"content": [
{ "type": "text", "text": "Keep the subject's clothing and follow the reference motion." },
{
"type": "image_url",
"image_url": { "url": "https://example.com/subject.png" },
"role": "reference_image"
},
{
"type": "video_url",
"video_url": { "url": "https://example.com/motion.mp4" },
"role": "reference_video"
}
],
"resolution": "2K",
"duration": 8,
"ratio": "16:9"
}
接口最多接收 9 张参考图片、3 个参考视频和 3 个参考音频，但一个混合输入请求最多包含 12 个文件。单个视频或音频时长可以是 2 到 15 秒，同类素材累计不超过 15 秒。请求体上限为 64 MB，大文件更适合使用公开 URL。你也可以查看本站独立网页生成器提供的 MiniMax H3 模型工作流。
错误、重试与幂等
创建接口记录了以下常见响应：
| HTTP | 文档中的原因 | 处理方式 |
|---|---|---|
400 |
参数错误，包括提示词为空（2013） |
修正负载，不要原样重试 |
401 |
Bearer Key 缺失或无效（1004） |
修正服务端鉴权 |
402 |
余额不足（1008） |
充值或使用正确的 Key |
422 |
内容触发安全检查（1026） |
修改请求，不要规避安全规则 |
429 |
触发限流（1002） |
使用带抖动的退避，并控制并发 |
500 |
服务内部错误（1000） |
延迟后谨慎重试 |
当前限流页面给出的 H3 V2 最大并发为：免费层 2 个任务，付费层 15 个任务。它们是账号默认限制，不是吞吐量保证。
V2 创建接口没有记录幂等 Key 请求头。幂等需要在你的后端实现：调用上游前创建任务记录，为同一请求生成稳定指纹；同一客户端请求再次到达时，复用已保存的 task_id。如果创建请求超时，而上游可能已经接收任务，不要直接再发一个付费任务。先核对本地记录和官方最近 7 天任务列表。
API 价格与限制
MiniMax 按量付费页面在 2026 年 8 月 2 日列出的 H3 价格如下：
| 项目 | 当前标价或限制 |
|---|---|
| 2K 输出 | 每个输出秒 $0.13 |
| 768P 输出 | 每个输出秒 $0.09；封闭测试中，需要联系销售 |
| 参考音频 | 输入素材免费 |
| 参考图片 | 前 5 张免费，之后每张 $0.04 |
| 参考视频 | 按输入视频秒数和所选输出分辨率单价计费 |
| 输出时长 | 4 到 15 秒整数 |
| 当前公开创建 schema | 可用分辨率为 2K |
一个 5 秒 2K 输出的标价为 $0.65，另计可能收费的参考素材。产品显示报价或发送任务前，应重新核对官方价格。本站的 价格页 介绍 minimaxh3.tv 自己的积分套餐，不是 MiniMax API 账单。
安全检查清单
- MiniMax Key 只放在服务端密钥存储中。
- 用户通过你自己的鉴权后，才能创建付费任务。
- 提交前检查媒体 URL、文件类型、尺寸、时长和大小。
- 按账号限制并发，并设置消费上限。
- 日志中隐藏鉴权请求头；输入 URL 含私人数据时也要隐藏。
- 保存
task_id和终止状态，不额外保留产品不需要的用户素材。 - 成功结果应保存到受控存储，并遵守你的保留期限。
- Key 一旦出现在客户端包、仓库、截图或日志中，立即轮换。
常见问题
MiniMax H3 API 的模型 ID 是什么？
V2 视频生成接口使用 MiniMax-H3。
哪个接口用于创建 H3 视频？
向 POST https://api.minimax.io/v2/video_generation 发送有效 Bearer Key 和 JSON 请求体。
H3 任务应该多久轮询一次？
官方指南建议每 10 秒查询一次。轮询 GET /v2/query/video_generation/{task_id}，在 succeeded、failed、cancelled 或 expired 时停止。
下载 H3 V2 结果需要 file ID 吗？
不需要。V2 查询成功后，视频地址直接位于 task.content.url。旧版 V1 文件获取流程不属于当前 H3 V2 调用链。
H3 能否通过一个 API 接收文本、首尾帧、视频和音频？
可以。所有模式都使用 MiniMax-H3 和 content[]。文本必填；首尾帧角色不能与参考角色混用；参考音频必须同时提供至少一张图片或一个视频。
MiniMax H3 API 怎么计费？
2026 年 8 月 2 日，2K 按量付费标价是每个输出秒 $0.13。参考视频秒数和超出免费数量的参考图片可能增加费用。每次更新产品价格前，都应重新检查官方价格页。
minimaxh3.tv 是 MiniMax 官方 API 控制台吗？
不是。minimaxh3.tv 是独立服务，与 MiniMax 没有隶属、背书或运营关系。API Key 和直接 API 账单请使用 MiniMax 官方平台；如果要使用本站网页生成器，可以打开独立的 MiniMax H3 模型页。
来源与方法
本文的 schema、接口、生成模式、状态、示例、价格和限制均按 MiniMax 官方文档核验，日期为 2026 年 8 月 2 日。代码示例遵循文档中的请求与响应结构，没有使用付费生成作为证据。
最后核验：2026 年 8 月 2 日。
