Skip to Content

MiniMax

Video Tasks
创建任务POST /v2/video_generation
查询任务GET /v2/query/video_generation/{task_id}
MiniMax-H3

视频生成是异步任务。创建成功后保存返回的 task_id,再通过查询接口获取任务状态和视频地址。

视频下载地址有时效,请在任务成功后及时下载或转存。

创建视频生成任务

POST /v2/video_generation

请求参数

参数类型必填说明
modelstring是固定为 MiniMax-H3。
contentarray是多模态输入数组。必须包含一个非空的 text 项;可组合图片、视频和音频输入。
resolutionstring是输出分辨率:768P 或 2K。
durationinteger是视频时长,单位为秒。纯文本输入使用 5 至 15 的整数;包含媒体输入时使用 5、10 或 15。
ratiostring条件必填支持 adaptive、21:9、16:9、4:3、1:1、3:4、9:16。文生视频必须传具体比例;包含图片、视频或音频时可使用 adaptive。
aigc_watermarkboolean否是否添加 AIGC 标识水印,默认值为 false。

content 项

type字段说明
texttext视频提示词,所有请求必须包含一个非空文本项,最多 7000 个字符。
image_urlimage_url.url、role图片地址和用途。role 可为 first_frame、last_frame 或 reference_image;首帧和尾帧各最多一张,参考图片最多 9 张。
video_urlvideo_url.url、role参考视频地址,role 固定为 reference_video,最多 3 段,单段 2 至 15 秒,总时长不超过 15 秒。
audio_urlaudio_url.url、role参考音频地址,role 固定为 reference_audio,最多 3 段,单段 2 至 15 秒,总时长不超过 15 秒。

图片支持 JPG、JPEG、PNG、WEBP、HEIC 和 HEIF,单张不超过 30 MB,宽高均为 256 至 5760 像素,宽高比为 0.4 至 2.5。视频支持 MP4 和 MOV,单个不超过 50 MB;音频支持 WAV 和 MP3,单个不超过 15 MB。请求体总大小不超过 64 MB,媒体地址应使用公网 URL。

每次请求最多包含 12 项媒体。仅传一张图片且省略 role 时,按 first_frame 处理。首帧 / 尾帧模式不能与参考图片、参考视频或参考音频混用;使用参考音频时必须同时提供参考图片或参考视频。

调用示例

curl -X POST "https://api.example.com/v2/video_generation" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-H3", "content": [ {"type": "text", "text": "一位宇航员站在月面,远处的地球从地平线升起,电影感镜头缓慢推进。"} ], "resolution": "2K", "duration": 5, "ratio": "16:9", "aigc_watermark": false }'

创建响应

字段类型说明
task_idstring任务 ID,需保存并用于查询任务。
{ "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }

查询视频生成任务

GET /v2/query/video_generation/{task_id}

路径参数

参数类型必填说明
task_idstring是创建任务返回的任务 ID,使用有权访问该任务的 API Key 查询。

响应参数

字段类型说明
task.idstring任务 ID。
task.modelstring任务使用的模型名称。
task.statusstringsubmitting(提交中)、submission_unknown(提交结果待确认)、queued(排队中)、running(运行中)、succeeded(成功)、failed(失败)或 cancelled(已取消)。
task.created_atinteger创建时间,Unix 时间戳(秒)。
task.updated_atinteger状态更新时间,Unix 时间戳(秒)。
task.content.urlstring任务成功时返回的视频下载地址。
task.resolutionstring任务产物的分辨率。
task.durationinteger任务产物的时长(秒)。
task.ratiostring任务产物的宽高比。
task.usageobject任务用量信息,可省略或为空对象。
task.usage.total_secondsinteger输入参考视频与输出视频的总秒数,可省略。
task.usage.input_secondsinteger输入参考视频秒数,可省略。
task.usage.output_secondsinteger输出视频秒数,可省略。
task.usage.input_image_countinteger输入图片数量,可省略。
task.usage.input_audio_secondsinteger输入参考音频秒数,可省略。
task.task_typestring视频生成任务为 generation,可省略。
task.modalitystring视频产物为 video,可省略。
task.error.codestring失败错误码,可能省略;失败时以 task.error.message 为主要提示。
task.error.messagestring失败提示,任务失败时返回。

响应中的时间、产物规格和用量字段可能尚未返回;task.content 在任务成功后读取,失败时读取 task.error,不要将字段缺失当作任务成功。

curl "https://api.example.com/v2/query/video_generation/<task_id>" \ -H "Authorization: Bearer <YOUR_API_KEY>"

成功响应示例:

{ "task": { "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "model": "MiniMax-H3", "status": "succeeded", "created_at": 1785125529, "updated_at": 1785125946, "content": {"url": "https://example.com/generated-video.mp4"}, "resolution": "2K", "duration": 5, "ratio": "16:9", "usage": {"total_seconds": 5, "input_seconds": 0, "output_seconds": 5, "input_image_count": 0}, "task_type": "generation", "modality": "video" } }

建议每隔 5 至 10 秒查询一次。任务处于 submitting、submission_unknown、queued 或 running 时继续等待,不重复创建任务;succeeded 时从 task.content.url 下载视频;failed 时读取 task.error.code 和 task.error.message;cancelled 时停止轮询。

错误处理

{ "type": "error", "error": { "type": "bad_request_error", "message": "invalid params", "http_code": "400" }, "request_id": "req_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }

对 429 和临时 5xx 响应使用带随机抖动的指数退避;参数错误、鉴权失败和内容安全错误应修正请求后再试。

Last updated on