MiniMax 系列
- 文生视频、首帧、首尾帧、多模态参考
- 参考图、参考视频、参考音频可以同时使用
- 提示词里可用方括号写运镜指令
认证
All endpoints authenticate with a Bearer token.
Get an API key: open the console and create one.
Add it to the request header:
Authorization: Bearer YOUR_OAIRoute_KEY请求参数
提交成功只返回任务 ID，不含视频本身。拿成片用 task_id 轮询获取任务状态，成片地址在 result.videos[0].url，该地址约 24 小时后过期，请及时转存。
模型 ID，取值见下方模型列表。
画面描述。所有模式都必填，包括图生视频与参考生视频。
H3 上限 7000 字符，Hailuo 2.3 上限 2000 字符。
时长，单位秒。
MiniMax-H3：4 到 15，默认5MiniMax-Hailuo-2.3：6或10，默认6MiniMax-Hailuo-02：5或10，默认5
输出分辨率。
MiniMax-H3：2K、768P，默认2KMiniMax-Hailuo-2.3：768p、1080p，默认768pMiniMax-Hailuo-02：512p、768p、1080p，默认768p
输出画幅，取值 21:9、16:9、4:3、1:1、3:4、9:16。
别名 size、ratio。图生视频会忽略该字段，改用输入图片比例。
首帧图片地址，公网 URL 或 Base64 data URI。传入即进入图生视频。
与参考类字段互斥。
尾帧图片地址，可与 first_frame_image 组合成首尾帧过渡。
与参考类字段互斥。
多模态参考图，H3 最多 9 张。
该字段下的图片一律按参考图处理，不会因为数量变成首尾帧。
参考视频，H3 最多 3 段。
参考音频，H3 最多 3 段。不能单独使用，必须至少配一张参考图或一段参考视频。
带角色的图片数组，每项含 url 与 role。
role 取值 first_frame、last_frame、reference_image，也可用简写 first、last、reference。
自动改写提示词，默认 true。
缩短提示词优化耗时，画质略有损失，默认 false。
是否添加 AIGC 水印，默认 false。别名 aigc_watermark。
任务终态回调地址。不要使用官方的 callback_url，该字段保留给内部使用。
为 true 时先做内容审查，默认 false。
A successful submission returns only the task ID, not the video itself. Poll Get task status with the task_id; the video URL is at result.videos[0].url, expires after about 24 hours, so copy it promptly.
The model ID; see the model list below.
The scene description. Required in every mode, including image to video and reference to video.
H3 allows up to 7000 characters; Hailuo 2.3 allows up to 2000.
Duration in seconds.
MiniMax-H3: 4 to 15, default5MiniMax-Hailuo-2.3:6or10, default6MiniMax-Hailuo-02:5or10, default5
Output resolution.
MiniMax-H3:2Kor768P, default2KMiniMax-Hailuo-2.3:768por1080p, default768pMiniMax-Hailuo-02:512p,768p, or1080p, default768p
Output framing: 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16.
Aliases: size, ratio. Image to video ignores this field and uses the input image's ratio.
The first-frame image URL, as a public URL or Base64 data URI. Including it enters image to video.
Mutually exclusive with the reference-type fields.
The last-frame image URL; combined with first_frame_image it makes a first-and-last-frame transition.
Mutually exclusive with the reference-type fields.
Multimodal reference images, up to 9 on H3.
Images in this field are always treated as reference images; their count never turns them into first/last frames.
Reference videos, up to 3 on H3.
Reference audio, up to 3 on H3. Can't be used alone; at least one reference image or reference video is required alongside.
An array of images with roles, each with url and role.
role is first_frame, last_frame, or reference_image; the short forms first, last, and reference are also accepted.
Automatically rewrite the prompt; defaults to true.
Shortens prompt optimization time with a slight quality loss; defaults to false.
Whether to add an AIGC watermark; defaults to false. Alias: aigc_watermark.
The callback URL for the task's terminal state. Don't use the official callback_url; that field is reserved for internal use.
When true, runs a content check first. Defaults to false.
模式判定
只传提示词与通用字段是文生视频。
传 first_frame_image、last_frame_image，或 image_with_roles 里带 first_frame、last_frame 角色的图，走图生视频。
传 image_urls、video_urls、audio_urls，或 image_with_roles 里带 reference_image 角色的图，走多模态参考。
帧类字段与参考类字段严格互斥，混用返回 400。
Only a prompt and general fields means text to video.
Passing first_frame_image, last_frame_image, or image_with_roles entries with a first_frame or last_frame role means image to video.
Passing image_urls, video_urls, audio_urls, or image_with_roles entries with a reference_image role means multimodal reference.
Frame-type and reference-type fields are strictly mutually exclusive; mixing them returns a 400.
支持的模型列表
| 模型 ID | 定位 |
|---|---|
MiniMax-H3 | 当前旗舰，最高 2K，支持图、视频、音频三类参考 |
MiniMax-H3-max | H3 的高配版 |
MiniMax-Hailuo-2.3 | 支持首帧与首尾帧，1080p 限 6 秒 |
MiniMax-Hailuo-2.3-Fast | 快速版，必须传 first_frame_image |
MiniMax-Hailuo-02 | 上一代，512p 到 1080p 三档 |
| Model ID | Positioning |
|---|---|
MiniMax-H3 | Current flagship, up to 2K, supports image, video, and audio reference |
MiniMax-H3-max | A higher-spec variant of H3 |
MiniMax-Hailuo-2.3 | Supports first frame and first-and-last frames; 1080p limited to 6 seconds |
MiniMax-Hailuo-2.3-Fast | Fast variant; requires first_frame_image |
MiniMax-Hailuo-02 | Previous generation, three tiers from 512p to 1080p |
使用限制
- 1080p 与 10 秒不能组合，1080p 只支持 6 秒
- 参考音频不能单独使用
- 请求体不超过 64MB，大文件请用公网地址而不是 Base64
- 图片单张不超过 30MB，边长 256 到 5760 像素，宽高比 0.4 到 2.5
- 参考视频单段 2 到 15 秒，合计不超过 15 秒，单段不超过 50MB
- 参考音频每段 2 到 15 秒，合计不超过 15 秒，单段不超过 15MB
- 1080p and 10 seconds can't be combined; 1080p supports only 6 seconds
- Reference audio can't be used on its own
- The request body must stay under 64MB; use public URLs rather than Base64 for large files
- Images: up to 30MB each, sides 256 to 5760 pixels, aspect ratio 0.4 to 2.5
- Reference video: 2 to 15 seconds per clip, 15 seconds total, 50MB per clip
- Reference audio: 2 to 15 seconds per clip, 15 seconds total, 15MB per clip
响应
提交成功返回统一的受理结构：
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}状态码，200 表示任务已受理。
本次提交的任务列表，逐项提交时按顺序排列。
受理状态，提交成功时为 submitted。
任务 ID，用它轮询结果。
A successful submission returns the standard accepted structure:
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}The status code; 200 means the task was accepted.
The list of tasks submitted this time, in order when submitting item by item.
The acceptance status; submitted on success.
The task ID; use it to poll for the result.
错误
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 请求参数无效，或参数组合冲突 |
| 401 | authentication_error | 身份验证失败，需检查 API Key |
| 402 | payment_required | 账户余额不足，需先充值 |
| 429 | rate_limit_error | 调用频率过高，稍后重试 |
参数错误在提交阶段同步返回，不创建任务、不扣费。
内容安全审查不通过时返回 422，同样不扣费。
| HTTP | type | Notes |
|---|---|---|
| 400 | invalid_request_error | Invalid parameters, or a conflicting combination |
| 401 | authentication_error | Authentication failed; check the API key |
| 402 | payment_required | Insufficient account balance; top up first |
| 429 | rate_limit_error | Too many calls; retry later |
Parameter errors are returned synchronously at submission, creating no task and charging nothing.
Failing content safety review returns a 422, also unbilled.
For more status codes and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.
查询任务
GET /v1/tasks/{task_id} 返回任务进度与结果，status 为 completed 时成片地址在 result.videos[0].url，元素带 expires_at 过期时间戳。
建议每 5 到 10 秒轮询一次，客户端总超时设为 10 到 15 分钟。status 取值 pending、processing、completed、failed、cancelled，以状态判定完成，不要依赖 progress。
失败任务自动退回费用，error.message 给出原因。
GET /v1/tasks/{task_id} returns task progress and results; once status is completed, the video URL is at result.videos[0].url, with an expires_at timestamp on the element.
Poll every 5 to 10 seconds, with a 10 to 15 minute client timeout. status is one of pending, processing, completed, failed, cancelled; judge completion by status, not by progress.
Failed tasks are refunded automatically, with the reason in error.message.