MINIMAX H3
MiniMax H3 视频生成
MiniMax H3 视频 API:768P 和 2K 支持 4–15 秒及图片、首尾帧、音视频参考。含画幅、素材限制、异常退款与认证下载说明。
最后验证:2026-11-04
MiniMax H3 使用 RootFlowAI 的异步视频接口:先提交任务取得 ID,再查询状态,完成后播放或下载视频。客户端统一使用 https://api.rootflowai.com 和自己的 RootFlowAI API Key。
本页说明当前已开放的 H3 规格、参考素材、计费与等待方式。接口流程总览见 视频生成指引。
模型与规格
| 模型 ID | 分辨率 | 时长 |
|---|---|---|
minimax-h3 | 768P | 4–15 秒,整数 |
minimax-h3-2k | 2K | 4–15 秒,整数 |
有些客户端称 768P 为“1K”,本接口仍使用 minimax-h3 和 768P,不传 1K。
模型 ID 统一使用全小写;分辨率仍按上表填写为 768P 或 2K。minimax-h3-2k 是平台用于选择 2K 规格的模型名称。
2K 使用同一个视频任务完成生成与文件交付。客户端只提交一次,持续查询同一个平台任务 ID,等待 status=completed 后再下载;中间处理阶段结束不代表最终完成。
metadata.processing_stage 是可选的阶段提示:
| 阶段值 | 建议显示 |
|---|---|
generation | 生成中 |
processing | 视频处理中 |
finalizing | 完成核验中 |
阶段字段缺失或未知时继续按原任务状态处理;只有 status: "completed" 才表示最终成片可交付。
seconds 必须写成 JSON 字符串,例如 "4"、"8" 或 "15"。H3 按本次请求的整数秒数生成,请使用与模型匹配的分辨率。视频文件的实际播放时长可能与请求秒数略有差异。
分辨率可以省略,平台会使用对应模型的默认值。若显式指定,则必须匹配模型:minimax-h3 对应 768P,minimax-h3-2k 对应 2K,不能靠修改 resolution 跨模型切换规格。
请在 模型价格 确认当前分组、时长与分辨率对应的价格,以 消费日志 的记录为准。任务失败或提交结果不明时,请先核查任务与消费日志,必要时联系服务支持。
计费标准
文生、1–5 张参考图、音频及首尾帧模式按请求的输出秒数计费;参考视频和第 6–9 张图片另计输入费用。价格使用 $ 符号表示站内额度,并非美元;基础充值 1 元人民币对应 1 站内额度。以下为已包含会员优惠的每秒单价,不要再次换汇或重复打折:
| 会员 | 768P($ / 秒) | 2K($ / 秒) |
|---|---|---|
| 普通 | $0.40 | $0.64 |
| VIP | $0.35 | $0.56 |
| SVIP | $0.30 | $0.48 |
例如 SVIP 生成 4 秒 768P 视频为 $1.20,生成 10 秒 2K 文生视频为 $4.80。当前价格请查看模型价格页,实际扣费以消费日志为准。
2K 按上述输出单价和请求秒数计费,不因成片略长而多收输出费用。
两种规格均支持参考素材:参考视频按平台检测的真实输入秒数另计,使用所选规格相同的每秒单价。第 6–9 张图片每张按该规格每秒单价乘以图片折算系数计算:768P 为 0.04 / 0.08,2K 为 0.04 / 0.13。音频不加收输入费。视频输入先预留最多 15 秒费用,再按检测到的实际用量调整;最终金额按账单精度舍入。输出 seconds 不包含输入视频时长。
例如 SVIP 的 4 秒 768P 输出+2 秒视频参考为 $1.80。失败或提交结果未知时先核查任务与消费日志,不要直接重复提交。
在 消费日志 中展开 H3 记录,可查看输出视频、参考视频和额外参考图的费用,以及参考音频用量。明细按该次请求的计费记录核对,单价已包含本次优惠;不会用当前价格重新计算历史账单。历史记录缺少素材信息或金额暂时无法核对一致时,会保留日志金额并提示明细不可用。
退款记录需要结合任务状态查看:按实际素材用量调整预留费用,可能会产生差额退款,并不表示视频生成失败。费用调整记录会显示调整前、调整后的金额和本次返还金额。记录查询失败时可重新查询明细,无需重新创建视频任务。
在同一 H3 分组中切换清晰度
创建 RootFlowAI API Key 时选择 「MiniMax 视频」 分组,并确认令牌允许 minimax-h3 和 minimax-h3-2k 两个模型。分组用于选择可用服务,model 用于选择视频规格;切换清晰度无需更换 Key 或分组,在创建请求中选择对应模型即可。
| 希望生成 | model 必须填写 | resolution 可填写 | 不传 resolution 时 |
|---|---|---|---|
| 768P | minimax-h3 | 768P | 默认 768P |
| 2K | minimax-h3-2k | 2K | 默认 2K |
从 768P 切换到 2K 时,将 model 改为 minimax-h3-2k,同时将 resolution 改为 2K(或删除该字段,使用默认值);切回时反向修改。不能只把 minimax-h3 的 resolution 改为 2K;model: "minimax-h3" 始终对应 768P,2K 必须使用 minimax-h3-2k。
2K 不会自动降为 768P;所选规格暂不可用时会返回错误或任务失败,不能把它当作低清晰度成功结果。不同规格独立计价,会员优惠按当前分组规则计算,具体以模型价格页为准。
2K 当前支持 4–15 秒文生和下述参考模式。从 768P 切换到 2K 时,同步修改模型与分辨率,并按所选规格重新校验时长、素材和画幅;保留原草稿,不能静默丢弃素材或改变时长。
清晰度是在创建任务时确定的,已创建任务不能修改;需要另一规格时会创建新的任务并单独计费。若原任务正在生成或提交结果不明,应先核查原任务,不要以“切换清晰度”作为重试方式。
接口流程
POST /v1/videos
→ 取得任务 ID,保存后再进行其他操作
GET /v1/videos/{task_id}
→ queued / in_progress / completed / failed
GET /v1/videos/{task_id}/content
→ completed 后播放或下载 MP4以上三个接口均使用 RootFlowAI API Key。不要将 API Key 放入 URL 查询参数,也不要把包含 Key 的请求代码直接放在公开网页中。
提交视频任务
请求参数
| 字段 | 必填 | 说明 |
|---|---|---|
model | 是 | minimax-h3 或 minimax-h3-2k |
prompt | 是 | 非空视频描述,最多 7000 字符 |
seconds | 是 | 字符串形式的整数,768P 为 "4"–"15",2K 为 "4"–"15" |
resolution | 否 | 与模型匹配的 768P 或 2K |
image_urls | 否 | 最多 9 个公网 HTTPS 图片地址或 PNG/JPEG/WebP 的 Base64 data URI |
first_frame_url | 否 | 指定首帧,可单独使用,或与尾帧一起使用 |
last_frame_url | 否 | 指定尾帧,可单独使用,或与首帧一起使用 |
video_urls | 否 | 最多 3 段参考视频,每段 2–15 秒、合计 ≤15 秒 |
audio_urls | 否 | 单独音频最多 1 段;与图片/视频组合时最多 3 段。时长限制见下表 |
aspect_ratio | 否 | 文生默认 16:9,可选 21:9、16:9、4:3、1:1、3:4、9:16;视觉参考素材省略时为 adaptive;两种规格的纯音频省略时为 16:9,不接受 adaptive;首尾帧使用 adaptive |
本页素材字段适用于 768P 和 2K。参考示例默认使用 768P;用于 2K 时,同时将 model 改为 minimax-h3-2k、resolution 改为 2K,其他素材字段和角色保持原样。
本页示例使用 JSON 视频任务请求。不传 size,也不需要 stream 或聊天消息格式的 messages。首尾帧与参考素材数组不能混用。组合参考时,各类型最多 9 图、3 视频、3 音频;两种规格均合计最多 12 个素材。各类型仍遵守独立数量和时长上限。
画幅与 adaptive
aspect_ratio: "adaptive" 表示根据参考图片或视频选择输出宽高比,界面可显示为“跟随参考画面”。它只决定画幅,清晰度仍由 model / resolution 决定。
| 输入模式 | 画幅规则 |
|---|---|
| 文生视频 | 使用固定比例,默认 16:9;不能传 adaptive |
| 普通参考图、视频或包含视觉素材的组合 | 可选固定比例或 adaptive;省略时默认 adaptive |
| 首帧、尾帧、首尾帧 | 使用 adaptive,画幅跟随参考图片 |
| 两种规格的纯音频 | 使用固定比例;省略时为 16:9,显式 adaptive 会被拒绝 |
纯音频没有提供参考画面,客户端建议始终传 16:9、9:16 等固定比例。切换素材模式时重新检查画幅,不应把首尾帧模式的 adaptive 原样带到纯音频请求。
768P 示例
先把自己的 RootFlowAI API Key 设置到环境变量 ROOTFLOWAI_API_KEY。以下请求创建一个 4 秒横屏视频:
curl --connect-timeout 15 --max-time 900 \
https://api.rootflowai.com/v1/videos \
-H "Authorization: Bearer ${ROOTFLOWAI_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3",
"prompt": "阳光下木桌上的蓝色陶瓷杯,镜头缓慢推近,柔和自然光,无人物、无文字。",
"seconds": "4",
"resolution": "768P",
"aspect_ratio": "16:9"
}'2K 竖屏示例
{
"model": "minimax-h3-2k",
"prompt": "一只橘猫安静地坐在窗边,阳光照亮毛发,镜头缓慢推近,保持主体清晰。",
"seconds": "10",
"resolution": "2K",
"aspect_ratio": "9:16"
}参考图片:1–9 张
768P 和 2K 均可通过 image_urls 数组传入 1–9 张图片。参考图用于引导主体、风格和内容,不保证作为视频第一帧;需要控制开头或结尾时,请选择下面的首尾帧模式。多图数组不是时间轴,不能把第 2 张图绑定到第 2 秒等中间时刻;当前接口不提供中间关键帧时间戳。
{
"model": "minimax-h3",
"prompt": "让两张参考图中的红色和蓝色小球一起出现在米色桌面上,轻轻滚动,镜头固定。",
"seconds": "4",
"resolution": "768P",
"aspect_ratio": "16:9",
"image_urls": [
"https://your-domain.example/red.png",
"https://your-domain.example/blue.png"
]
}只有一张图时,数组只保留一个元素。不要同时传入首帧或尾帧字段,也不要传入超过 9 张图片。
指定首帧、尾帧或首尾帧
三种模式均使用 aspect_ratio: "adaptive",画幅跟随图片。首尾帧用于控制对应端点的构图,生成细节可能有所变化。
| 模式 | 填写字段 |
|---|---|
| 指定首帧 | 只传 first_frame_url |
| 单独尾帧 | 只传 last_frame_url,无须补首帧 |
| 指定首尾帧 | 同时传 first_frame_url 与 last_frame_url |
{
"model": "minimax-h3",
"prompt": "从红色小球所在的开头画面自然过渡到蓝色小球所在的结尾画面,镜头固定。",
"seconds": "4",
"resolution": "768P",
"aspect_ratio": "adaptive",
"first_frame_url": "https://your-domain.example/first.png",
"last_frame_url": "https://your-domain.example/last.png"
}只指定一个端点时删除另一个字段。首尾帧不能与 `image_urls`、视频或音频参考混用。 普通参考图不能替代首帧字段。
视频、音频与组合参考
视频引导运动、镜头和画面内容,不等于续接原视频;音频引导声音和节奏,不保证原曲逐样本复制、歌词完整一致或口型同步。两种规格均支持单独使用或与图片组合,但不能与首尾帧混用。
| 素材 | 格式与大小 | 数量与时长 |
|---|---|---|
| 视频 | MP4/MOV,H.264/H.265,单段 ≤50 MB;视频内音轨 AAC/MP3 | 最多 3 段,每段 2–15 秒,合计 ≤15 秒 |
| 音频 | WAV/MP3,单段 ≤15 MB | 单独最多 1 段;搭配图片或视频时最多 3 段。每段至少 2 秒;两种规格音频合计均 ≤6 秒 |
视频宽高 256–5760 px、宽高比 0.4–2.5、帧率 23.976–60 fps。平台会检查真实内容;公开 HTTPS 链接必须直接可读,不能是登录页或本机路径。也可传对应格式的 Base64 data URI,较大素材建议使用 HTTPS 链接。
以下示例将图片主体、视频运动与音频线索组合;只使用一种素材时省略其他数组:
{
"model": "minimax-h3",
"prompt": "保留参考图中的主体,参考视频的运动方式,以音频的节奏引导配乐。",
"seconds": "4",
"resolution": "768P",
"aspect_ratio": "16:9",
"image_urls": ["https://your-domain.example/subject.png"],
"video_urls": ["https://your-domain.example/motion.mp4"],
"audio_urls": ["https://your-domain.example/rhythm.wav"]
}视频和音频分别累计时长:视频合计不超过 15 秒;音频合计不超过 6 秒。输入时长不占用输出 seconds。超限会在创建生成任务前拒绝。只选择组合模式但没有添加图片或视频,仍按单独音频的 1 段限制检查。纯音频参考建议显式传入 aspect_ratio: "16:9" 等固定画幅。两种规格的纯音频省略画幅时使用 16:9,显式 adaptive 会被拒绝;有图片或视频参考时仍可使用 adaptive。
素材数组不是时间轴,不能为中间画面指定精确关键帧时间。两种规格的组合总数均最多 12 个,例如 9 图+3 视频。超限会返回错误,不会静默忽略多余素材或降低分辨率。
纯音频参考示例
下面生成 4 秒 768P 视频,输入音频应为 2–6 秒。音频时长与输出 seconds 分别计算:
{
"model": "minimax-h3",
"prompt": "彩色几何图形随着参考音频的节奏移动,无人物、无文字。",
"seconds": "4",
"resolution": "768P",
"aspect_ratio": "16:9",
"audio_urls": ["https://your-domain.example/rhythm.wav"]
}2K 同样支持音频参考。纯音频始终最多 1 段;“组合模式”中移除全部图片和视频后,也需按纯音频限制校验。
切换规格或素材模式
768P 和 2K 均为 4–15 秒,普通参考总数最多 12 个、音频合计 ≤6 秒。客户端在切换清晰度、模式或移除素材后,应重新检查数量、实际时长、素材角色和画幅。超限时保留草稿并提示修正,不要静默删除素材、改变角色或降低清晰度。
首帧、尾帧和首尾帧使用独立角色,不能与普通参考数组一起提交。当前没有公开取消、独立素材上传或中间关键帧时间轴接口;移除本地节点或停止等待不等于取消已受理任务。
素材与提交要求
所有图片字段均接受公网 HTTPS 地址或完整的 data:image/png;base64,...、data:image/jpeg;base64,...、data:image/webp;base64,...。请替换示例地址或省略号,不能传入本机文件路径、需要登录的网页或临时失效链接。
建议客户端将图片控制在每张 8 MiB 内,宽高 256–5760 px、宽高比 0.4–2.5,以便预览和传输。API 对内嵌图片的解码上限是 20 MiB、3600 万像素。完整 JSON 请求不超过 64,000,000 字节,Base64 编码后的体积也计入限制,较大素材建议使用公开 HTTPS。
平台会在生成前检查图片、首尾帧、视频和音频的实际格式、大小、时长及可读性。HTTPS 链接和 Base64 输入均需符合上述要求;素材按请求中指定的参考用途处理。
源链接已过期、需要登录或拒绝访问时,请重新提供可读取的素材。素材准备和提交期间不要重复点击;这部分等待包含在创建请求时间内。当前视频接口没有单独的素材上传 API,不能直接提交浏览器 blob: 地址、画布图层或本机路径。
画布中的多个图层需先导出为图片,再按参考图、首帧或尾帧角色传入。多张参考图没有中间关键帧时间戳;视频裁剪也需先导出实际片段,输入费按提交文件的真实时长计算。使用第三方客户端时,请确认其版本支持所需的素材参数。
创建响应
{
"id": "task_xxxxxxxxxxxxxxxxxxxxx",
"object": "video",
"model": "minimax-h3",
"status": "queued",
"progress": 0,
"created_at": 1792454400
}保存响应中的 id;如果客户端读取的是兼容字段 task_id,则使用该字段返回的值。后续始终使用平台返回的任务 ID,不要自行拼接或替换。
查询与等待
将创建响应中的任务 ID 设置为 TASK_ID,然后查询:
curl --connect-timeout 15 --max-time 180 \
"https://api.rootflowai.com/v1/videos/${TASK_ID}" \
-H "Authorization: Bearer ${ROOTFLOWAI_API_KEY}"| 状态 | 建议操作 |
|---|---|
queued | 已受理,等待调度,继续查询原任务 |
in_progress | 正在生成或准备视频,继续等待 |
completed | 可以调用 content 接口播放或下载 |
failed | 任务失败,查看返回的错误信息与消费记录 |
当前 768P 和 2K 均不启用自动备用。2K 的生成与文件交付属于同一次任务的连续阶段。查询超时、断线或提交结果未知时,不会因此自动创建另一个任务;客户端持续查询原平台任务 ID,以最终状态为准,不要自行切换渠道或重发 POST。历史任务仍按创建时的执行记录查询。
任务明确失败时,显示平台返回的安全错误说明,例如 error.message,保留素材位置、参数、时长或审核原因,不要统一替换成“生成失败”。非终态响应中的当前异常提示也应展示,不能一律显示“进行中”;异常解除或任务成功后清除旧提示。查询或文件交付异常不等于生成失败,也不能直接显示“已退款”。错误说明应作为纯文本渲染。
建议每次查询结束后至少间隔 12 秒再查询,同一任务不要并发轮询。progress 不是线性计时器,长时间保持 0 不代表任务停止。
提交异常与退款
HTTP 5xx、连接超时或缺失可靠回执时,任务可能显示“受理待确认”,这不代表已经开始生成。请继续查询原任务,不要重复提交。接口的 metadata.submission_state 为 unknown 时,metadata.status_detail 与 error 会说明当前异常,必要时包含安全的 HTTP 状态码;查询暂不可用或文件交付中也会单独说明。非终态的 error 是当前异常提示,最终结果仍以任务状态为准。
H3 受理结果持续不明超过 10 分钟,平台会全额退回该任务的预扣费用,并关闭客户任务。定时处理通常会有约一分钟延迟;门户可查看退款流水和任务净额。之后即使收到生成成功结果,也不会再次扣费。正常已受理的长任务、单次查询故障和文件交付问题不适用这一受理不明保障规则。
客户端展示时先核对平台明确的退款结算,再处理终态和当前异常:
| 返回信息 | 建议展示 |
|---|---|
metadata.submission_state: "unknown" | 受理待确认,并展示当前安全原因,保留任务 ID |
非终态的 metadata.status_detail.message / error.message | 当前查询、受理或交付异常提示;不自行改成失败 |
status: "failed" | 该任务最终安全失败原因;没有退款证据时不宣称已退款 |
error.code: "submission_unconfirmed_refunded" 或 metadata.customer_settlement.status: "refunded" | 已退款(受理未确认),按平台结算信息和消费日志核对金额 |
status: "completed" | 提供播放下载并清除中间异常提示 |
这不是“生成超过 10 分钟一律退款”。客户端不能根据本地等待时长执行退款或重发生成。仅凭视频 API Key 不能访问门户登录态账单接口,需要核对实际扣费时可打开消费日志并登录查看。
生成十分钟,会让请求超时吗?
取得任务 ID 后,视频在后台异步生成,不需要让创建连接一直等到视频完成。 客户端定期查询同一个 ID,完成后再下载;本接口采用主动查询,不依赖原连接回传视频或自动推送到客户端。
视频时长与生成耗时不同。当前 2K 包含生成、视频处理和完成核验,已验收的 10 秒文生样本耗时约 10–42 分钟;这是样本记录,不是完成时间承诺。排队或结果存储准备还可能延长等待。页面显示的“用时”是累计耗时,不是单次 HTTP 请求时长。已明确受理、仍在生成或处理的任务,即使超过 10 分钟或 900 秒,也不应仅因此判为失败、退款或重新创建。受理未确认退款规则不适用于正常进行中的长任务。
客户端超时配置建议
| 配置项 | 建议值 | 作用 |
|---|---|---|
| 建立连接超时 | 15–20 秒 | 只控制建立网络连接,不限制后台生成时间 |
创建请求 POST /v1/videos | 至少 900 秒 | 等待任务受理回执和 ID;不自动重试 POST |
单次状态查询 GET /v1/videos/{id} | 180 秒 | 一次查询的上限;超时后仍查询原 ID |
| 查询间隔 | 每次请求结束后至少等待 12 秒 | 串行查询,避免上一请求未结束就并发发送下一次 |
| 客户端总观察窗口 | 建议至少 40 分钟,可设为 60 分钟 | 用于提醒和人工核查,不作为自动失败、退款或重新生成的依据 |
视频下载 GET /v1/videos/{id}/content | 1260 秒 | 为结果准备和视频传输预留时间;中断后可重新下载同一任务 |
如果 SDK 的 timeout 单位是毫秒,900 秒应填写 900000,180 秒填写 180000,1260 秒填写 1260000。不要把“单次请求超时”配置复用为“整个轮询流程的总时限”,也不要让一个 60 秒的计时器在多次查询之间持续倒计时。
自己的服务端、反向代理、网关或云函数也需要允许对应请求等待;客户端设置 900 秒不能覆盖中间层更短的限制。慢创建接入可使用 https://us.rootflowai.com,Key 与 /v1/videos 路径保持一致。受理后始终保留原任务 ID,不因换线路而重新创建。
前端关闭页面或停止轮询不会主动取消已受理的后台任务。请持久化任务 ID,重新打开页面后恢复查询,或使用自己的后台作业定时查询。观察 40–60 分钟仍未完成时,保留 ID 并联系服务支持;客户端应显示“仍在处理中 / 待核查”,不要伪造 failed 状态。
连接中断时怎么处理
- 已取得任务 ID:保留 ID,重新查询原任务。网络超时或临时 502/503/504 时,可等待 10–15 秒后重试 GET;429 遵循响应中的
Retry-After(如有)。401/403 先检查 Key 和权限。上述请求错误均不能直接当作任务failed,不要重新创建视频。 - 创建时没有收到任务 ID:先到 视频任务 核查最近任务。不要立即重新发送 POST;若无法确认是否受理,联系 服务支持,提供请求时间和模型名。
- 状态仍为
queued或in_progress:继续查询,不要因为等待超过一两分钟就自行改成失败。 - 看到
video storage is preparing:说明视频结果仍在准备,稍后查询或下载即可。
播放与下载
任务为 completed 后下载:
curl --connect-timeout 15 --max-time 1260 \
"https://api.rootflowai.com/v1/videos/${TASK_ID}/content" \
-H "Authorization: Bearer ${ROOTFLOWAI_API_KEY}" \
-o minimax-h3.mp4接口返回视频二进制内容,通常为 video/mp4;它不是一个供客户端再次请求的第三方视频 URL。浏览器或播放器需要携带认证,普通网页建议通过自己的服务端代理视频流,避免将 API Key 暴露给访客。
也可以登录门户的 视频任务 页面查看、预览和下载。视频沿用平台的 7 天保留规则,请在生成完成后及时下载保存,不要把任务页面当作永久备份。
常见问题
为什么提示模型不可用?
先检查模型 ID 是否完全一致,以及当前 Key 的「MiniMax 视频」分组和模型权限。
为什么 `seconds` 不能直接写数字 `4`?
平台视频接口使用字符串类型的 seconds。请写 "seconds": "4",以保证通过平台请求校验。
为什么 2K 请求被拒绝?
检查是否使用 model: "minimax-h3-2k",以及 resolution 为 2K 或省略;seconds 必须为字符串整数 "4"–"15",参考模式需符合图片、首尾帧、视频和音频的角色、数量、时长及画幅限制。还需确认当前 Key 有该模型权限。minimax-h3 的对应规格是 768P;公开请求不要改成内部模型名、1440P、720p 或像素形式的 size。
可以套用其他模型的参考图参数吗?
不同视频模型的素材角色和限制不同。H3 的 1–9 张参考图使用本页的 image_urls 数组;首尾帧使用单独的 first_frame_url / last_frame_url。请按所选模式填写,不能混用或照搬其他模型的参数。
相关说明:获取 API Key · 视频生成指引 · 服务定价