MiniMax H3 API

MiniMax H3 通过知梦视频的异步任务接口调用，支持文生视频、单图 / 首尾帧和多参考图片、视频、音频。本文按 2026-10-24 版本更新，计价货币为人民币 CNY。

在线调试 H3 → · 视频计费说明

能力与限制

项目	当前规则
Base URL	https://movie.zmoapi.cn，不含 /v1
模型 ID	minimax-h3
创建任务	POST /v1/videos，JSON
查询任务	GET /v1/videos/{task_id}
生成时长	4–30 秒，整数秒，省略时默认 4 秒
分辨率	480p、768P、1080p、2K，按此写法发送，建议显式指定
2K 时长	最长 15 秒，16–30 秒不支持 2K
通道	fast_mode: false 标准；fast_mode: true 优先
首尾帧	首帧 1 张，可再加尾帧 1 张；按首、尾顺序
多参考	最多 9 张图片、3 段视频、3 段音频
参考视频	单段 2–15 秒，总长 ≤15 秒，单文件 ≤50 MB
参考音频	工作台最多 3 段，总长 ≤15 秒
成片保留	约 1 天，成功后及时下载，具体以任务详情提示为准

素材使用可由服务端公开读取的 HTTP(S) 文件直链，并在任务创建时保持有效。可以使用自己的图床 / 对象存储，或在 视频工作台 上传后使用返回的素材 URL；不需要先调用带工作台会话的上传接口。不要使用本机地址、网盘分享页或需要登录态的私有链接。

价格与计费

以下均为生成视频本身每秒的最终售价。16–30 秒按该档单价乘以整个输出时长，不是只对超过 15 秒的部分使用长视频价。

输出分辨率	4–15 秒标准	4–15 秒优先	16–30 秒标准	16–30 秒优先
480p	¥0.12/秒	¥0.18/秒	¥0.18/秒	¥0.30/秒
768P	¥0.15/秒	¥0.24/秒	¥0.24/秒	¥0.42/秒
1080p	¥0.20/秒	¥0.34/秒	¥0.34/秒	¥0.62/秒
2K	¥0.21/秒	¥0.36/秒	不支持	不支持

参考图片前 5 张免费，第 6–9 张按下表逐张计费：

输出时长	标准通道	优先通道
4–15 秒	¥0.05/张	¥0.10/张
16–30 秒	¥0.10/张	¥0.20/张

参考视频按输入参考视频的实际合计时长另计费，单价跟随本次输出分辨率、输出时长档和通道；参考音频目前不另收费。

输出分辨率	4–15 秒标准	4–15 秒优先	16–30 秒标准	16–30 秒优先
480p	¥0.06/参考秒	¥0.12/参考秒	¥0.12/参考秒	¥0.24/参考秒
768P	¥0.09/参考秒	¥0.18/参考秒	¥0.18/参考秒	¥0.36/参考秒
1080p	¥0.14/参考秒	¥0.28/参考秒	¥0.28/参考秒	¥0.56/参考秒
2K	¥0.15/参考秒	¥0.30/参考秒	不支持	不支持

计算方式：

预估费用 = 输出秒数 × 对应视频单价
         + max(参考图片数 − 5, 0) × 对应超额图片单价
         + 参考视频实际总秒数 × 对应参考视频单价

例如 768P 标准通道输出 8 秒、8 张参考图、6 秒参考视频，预估为 8 × 0.15 + 3 × 0.05 + 6 × 0.09 = ¥1.89。服务端会读取参考视频文件确定实际时长；不要依赖客户端自己填写的参考视频时长计费。

优先通道不是标准价格简单乘二。 切换 fast_mode、输出秒数或分辨率时，应按上表重新取对应单价。价格为最终公开售价，实际消费以任务创建时平台报价及消费记录为准。

鉴权与请求参数

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

公开 API 使用平台令牌；工作台登录会话与 API Key 是不同认证方式。API Key 放在服务端配置中，不写进公开网页源码。BASE_URL 不含 /v1，不要重复拼接成 /v1/v1/videos。

字段	类型	必填	说明
model	string	是	固定 minimax-h3。
prompt	string	是，或提供 content 文本	非空视频描述；高级 content 写法用 type: "text" 提供文本。
duration	integer	建议显式传	4–30 秒，默认 4；2K 仅 4–15 秒。
seconds	integer	否	duration 的别名；同时提供时必须与 duration 相等。建议只传 duration。
resolution	string	建议显式传	480p / 768P / 1080p / 2K；调试台默认 768P，API 客户端仍应显式填写。
aspect_ratio	string	否	如 16:9、9:16、adaptive；省略时按场景取默认值。有图片时可使用 adaptive。
fast_mode	boolean	否	false 标准、true 优先。必须使用 JSON 布尔值，不是字符串。示例显式发送 false。
generation_mode	string	参考图时建议传	frames：首尾帧；references：多参考。参考视频使用 references。
image_urls	string[]	否	首尾帧最多 2 张；多参考最多 9 张。
video_urls	string[]	否	最多 3 段公开可下载参考视频，单段和合计限制见上表。
audio_urls	string[]	否	公开可下载参考音频，工作台最多 3 段，总长 ≤15 秒。
content	object[]	高级用法	显式指定文本和素材角色；非空时优先采用该数组，不再从简化素材字段自动构造。

frames 不带图片时就是纯文生视频；1 图是首帧，2 图是首帧 + 尾帧。需要多参考图片时明确传 generation_mode: "references"，否则简写的前两张图可能被解释为首尾帧。参考视频不能与首帧 / 尾帧混用。

文生视频：标准通道

BASE_URL='https://movie.zmoapi.cn'
API_KEY='<YOUR_API_KEY>'

curl --request POST "$BASE_URL/v1/videos" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "minimax-h3",
    "prompt": "海边日落，镜头缓慢推进，电影感光影",
    "duration": 8,
    "resolution": "768P",
    "aspect_ratio": "16:9",
    "fast_mode": false
  }'

该例生成费用为 8 × ¥0.15 = ¥1.20。创建成功后从响应的 id 或 task_id 保存任务 ID，随后查询；创建请求返回成功不等于已经生成成片。

首帧 / 首尾帧：优先通道

{
  "model": "minimax-h3",
  "prompt": "保持人物和衣服一致，缓慢走向镜头",
  "duration": 10,
  "resolution": "1080p",
  "aspect_ratio": "adaptive",
  "generation_mode": "frames",
  "image_urls": ["https://example.com/first-frame.jpg"],
  "fast_mode": true
}

此例费用为 10 × ¥0.34 = ¥3.40；首帧图片免费。需要尾帧时，第二张图片放在 image_urls[1]；顺序不能颠倒。两张图片是生成约束，不保证逐像素锁定；提示词应主要描述动作、过渡和镜头变化。

多参考图片、视频和音频

{
  "model": "minimax-h3",
  "prompt": "保持参考角色与场景一致，结合参考视频的镜头运动和参考音频的节奏",
  "duration": 12,
  "resolution": "768P",
  "aspect_ratio": "adaptive",
  "generation_mode": "references",
  "image_urls": ["https://example.com/character.jpg", "https://example.com/scene.jpg"],
  "video_urls": ["https://example.com/camera-reference.mp4"],
  "audio_urls": ["https://example.com/rhythm-reference.mp3"],
  "fast_mode": false
}

生成费用为 12 × ¥0.15 = ¥1.80，另加参考视频实测总秒数 × ¥0.09。两张图片与参考音频不加价。服务端会读取素材校验格式、大小和真实时长；客户端填写的时长不能替代该检测，也不能用于降低参考视频费用。

素材上传与文件限制

素材	工作台上传要求	提交方式
图片	单张 ≤15 MB	使用上传结果 URL 写入 image_urls。
视频	MP4 / MOV，单段 ≤50 MB；单段 2–15 秒，合计 ≤15 秒	使用 URL 写入 video_urls，采用多参考模式。
音频	MP3 / WAV / M4A / AAC / OGG / FLAC，单段 ≤30 MB，合计 ≤15 秒	使用 URL 写入 audio_urls，目前不另收费。

工作台上传后返回的素材地址可直接提交。独立 API 客户端也可以使用符合要求的公开素材 URL。素材失效、下载失败或视频时长超限会导致提交失败。

高级 content 写法

非空 content 数组优先于简化字段。不要同时依赖顶层 prompt、image_urls、video_urls、audio_urls 自动拼装内容。

type	数据字段	role
text	text	不需要
image_url	image_url: {"url":"..."}	first_frame / last_frame / reference_image
video_url	video_url: {"url":"..."}	reference_video
audio_url	audio_url: {"url":"..."}	reference_audio

例如，显式多参考内容可这样写；此例不包含首尾帧，避免与参考视频混用：

{
  "model": "minimax-h3",
  "duration": 8,
  "resolution": "768P",
  "fast_mode": false,
  "content": [
    {"type":"text", "text":"保持参考角色一致，结合镜头运动和音频节奏"},
    {"type":"image_url", "image_url":{"url":"https://example.com/reference.jpg"}, "role":"reference_image"},
    {"type":"video_url", "video_url":{"url":"https://example.com/reference.mp4"}, "role":"reference_video"},
    {"type":"audio_url", "audio_url":{"url":"https://example.com/reference.mp3"}, "role":"reference_audio"}
  ]
}

首尾帧的显式写法使用 role: "first_frame" 与 role: "last_frame"，仍遵守首尾帧不得搭配参考视频的限制。普通客户端可优先使用前面的简化字段。

查询任务与下载

TASK_ID='<创建时返回的任务ID>'

curl --request GET "$BASE_URL/v1/videos/$TASK_ID" \
  --header "Authorization: Bearer $API_KEY"

status	含义	客户端处理
queued	排队中	保持任务 ID，继续查询。
in_progress	生成中	展示进度，继续查询。
completed	完成	有非空成片 URL 后才展示下载。
failed	失败	停止轮询，读取 error.message。

建议每 10–20 秒查询一次；调试台每 10 秒查询。进度达到 100 或出现 URL 都不能替代 status: "completed" 的判断。

完成后优先读取 content.url，再按需兼容 url、result_url、video_url 或 output[0]；没有有效 URL 时检查原始响应，不当作成功。响应结构可能包含其他元数据，客户端不要依赖未列出的字段。

成片约保留 1 天，具体过期时间以工作台任务详情提示为准，请成功后及时下载到自己的存储。任务创建请求不自动重试；GET 查询可对 429、临时网络错误和 5xx 退避重试，避免因查询失败重新创建并重复收费。

调试与常见问题

打开 H3 调试台 →。可选择四档分辨率、4–30 秒、标准 / 优先通道、素材模式与公网素材 URL。2K 的 16–30 秒组合会被拒绝；已有 16–30 秒时不能选择 2K。

切换参数及图片后会刷新生成费用和图片附加费；有参考视频时显示已知小计，实际参考视频费用由服务端检测时长后另计，不把客户端估算当作最终报价。

问题	处理
费用与旧版本不同	使用本页四档分辨率、长短时长和通道的最终售价；长视频整段计价。
2K 长视频报错	2K 最长 15 秒；16–30 秒请选择其他分辨率。
参考视频与首尾帧冲突	改用 references，或移除参考视频。
素材无法读取	检查公网直链是否仍有效、文件格式、大小和实际时长。
创建成功但没有视频	异步任务需继续查询，完成且有链接后下载。
401 / 403	检查令牌、余额、分组与模型权限。
已完成却下载失败	检查成片是否已过期，保留任务 ID 及响应排查。

视频 API 概览 · 完整价格 · 视频计费说明