MiniMax H3 视频生成示例

您可以通过平台统一的异步视频接口调用 MiniMax-H3。完整流程分为三步：

调用 POST /v1/videos 创建任务；
调用 GET /v1/videos/{video_id} 轮询任务状态；
任务完成后使用响应中的 url，或调用 GET /v1/videos/{video_id}/content 下载视频。

请以本文中的平台接口字段为准。平台已将 MiniMax 原生字段适配为统一视频接口，例如使用 seconds 表示输出时长、使用 watermark 控制 AIGC 水印。当前支持 768P 和 2K，不支持 720P、1080P 等其他分辨率。

快速开始

创建任务

cURL

curl --request POST \
  --url https://model-api.skyengine.com.cn/v1/videos \
  --header 'Authorization: Bearer <API-KEY>' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --data '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "清晨，一只橘猫沿着海边奔跑，电影感镜头，阳光穿过薄雾"
      }
    ],
    "resolution": "2K",
    "ratio": "16:9",
    "seconds": "4",
    "watermark": false
  }'

创建成功后返回任务 ID：

{
  "id": "426740781494778",
  "object": "video.generation",
  "created_at": 1785743414,
  "model": "MiniMax-H3",
  "status": "pending"
}

查询任务

任务 ID 可用于查询最近 7 天内的任务。建议保存任务 ID，并在创建后及时轮询和下载结果。

cURL

curl --request GET \
  --url https://model-api.skyengine.com.cn/v1/videos/426740781494778 \
  --header 'Authorization: Bearer <API-KEY>'

任务状态可能为：

状态	说明
`pending`	已创建，等待处理
`in_progress`	正在生成
`completed`	已完成，可下载
`failed`	生成失败，查看 `error`

完成响应示例：

{
  "id": "426740781494778",
  "object": "video.generation",
  "model": "MiniMax-H3",
  "status": "completed",
  "seconds": "4",
  "size": "2K",
  "url": "https://example.com/generated-video.mp4",
  "usage": {
    "input_video_seconds": 6,
    "output_video_seconds": 4,
    "input_image_count": 0
  }
}

下载视频

cURL

curl --request GET \
  --url https://model-api.skyengine.com.cn/v1/videos/426740781494778/content \
  --header 'Authorization: Bearer <API-KEY>' \
  --output minimax-h3.mp4

完成响应中的 url 可能带有效期。需要长期保存时，请在任务完成后及时下载或转存，不要将临时 URL 持久化为永久资源地址。

请求参数

参数	类型	必填	说明
`model`	string	是	固定为 `MiniMax-H3`
`content`	array	是	多模态输入数组；必须包含至少一个非空 `text` 项，建议只提供一个文本项
`resolution`	string	是	`768P` 或 `2K`；大小写不敏感，不支持 `720P`
`seconds`	string	是	整数，范围 `"4"`～`"15"`
`ratio`	string	条件必填	支持 `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`adaptive`，具体规则见下文
`watermark`	boolean	否	是否添加 AIGC 水印，默认 `false`

不同生成模式的 ratio 规则如下：

生成模式	`ratio` 规则
文生视频	必填，且不能为 `adaptive`
首帧/尾帧/首尾帧生视频	输出比例由输入图片决定；建议传 `adaptive`，其他合法值会被忽略
多模态参考生视频	可选，默认 `adaptive`；也可以指定具体比例

生成较低分辨率视频时，将 resolution 设置为 768P：

{
  "model": "MiniMax-H3",
  "content": [{ "type": "text", "text": "海边日落，电影感镜头" }],
  "resolution": "768P",
  "ratio": "16:9",
  "seconds": "4"
}

MiniMax-H3 的低分辨率规格名称是 768P，不是 720P。平台也接受 768p，并在调用 MiniMax-H3 时规范化为 768P。

content 类型与 role

type	role	用途
`text`	不填	提示词；必须至少提供一项非空文本，建议只提供一项；平台最多接收 7000 个 Unicode 字符
`image_url`	`first_frame`	首帧图片；单张图片不填 role 时也按首帧处理
`image_url`	`last_frame`	尾帧图片
`image_url`	`reference_image`	多模态参考图片，最多9张
`video_url`	`reference_video`	多模态参考视频，最多3个
`audio_url`	`reference_audio`	多模态参考音频，最多3个

首帧/尾帧模式与 reference_* 多模态参考模式互斥。reference_audio 不能单独使用，必须同时提供至少一个 reference_image 或 reference_video。

输入媒体限制

媒体必须使用 MiniMax 服务可访问的公网 HTTP/HTTPS URL。不要使用 Base64 或 data URI；请求体总大小不能超过 64 MB。建议使用稳定的 HTTPS URL，并确保任务处理期间 URL 不会过期。

图片

项目	限制
格式	JPG、JPEG、PNG、WEBP、HEIC、HEIF
单文件大小	不超过 30 MB
宽、高	均在 256～5760 px 范围内
宽高比（宽/高）	0.4～2.5
数量	首帧最多1张、尾帧最多1张、参考图片最多9张

视频

项目	限制
格式	MP4、MOV
视频编码	H.264/AVC、H.265/HEVC
视频内音频编码	AAC、MP3
单文件大小	不超过 50 MB
数量	最多3个
时长	单段2～15秒，全部参考视频总时长不超过15秒
宽、高	均在 256～5760 px 范围内
宽高比（宽/高）	0.4～2.5
帧率	23.976～60 fps

音频

项目	限制
格式	WAV、MP3
单文件大小	不超过 15 MB
数量	最多3个
时长	单段2～15秒，全部参考音频总时长不超过15秒

首帧生成视频

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "保持人物外观，从静止状态开始自然向镜头挥手"
    },
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": {
        "url": "https://example.com/first-frame.jpg"
      }
    }
  ],
  "resolution": "2K",
  "ratio": "adaptive",
  "seconds": "4",
  "watermark": false
}

首尾帧生成视频

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "镜头平滑推进，人物从室内自然走到窗边"
    },
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": {
        "url": "https://example.com/first-frame.jpg"
      }
    },
    {
      "type": "image_url",
      "role": "last_frame",
      "image_url": {
        "url": "https://example.com/last-frame.jpg"
      }
    }
  ],
  "resolution": "2K",
  "ratio": "adaptive",
  "seconds": "6"
}

图片、视频和音频参考

cURL

curl --request POST \
  --url https://model-api.skyengine.com.cn/v1/videos \
  --header 'Authorization: Bearer <API-KEY>' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --data '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "保持参考图片中的主体外观，参考视频中的动作和镜头运动，并结合参考音频自然生成画面"
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": {
          "url": "https://example.com/character.jpg"
        }
      },
      {
        "type": "video_url",
        "role": "reference_video",
        "video_url": {
          "url": "https://example.com/motion.mp4"
        }
      },
      {
        "type": "audio_url",
        "role": "reference_audio",
        "audio_url": {
          "url": "https://example.com/reference.mp3"
        }
      }
    ],
    "resolution": "2K",
    "ratio": "16:9",
    "seconds": "4",
    "watermark": false
  }'

Python 完整流程

Python

import time
import requests

API_KEY = "<API-KEY>"
BASE_URL = "https://model-api.skyengine.com.cn/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

request_body = {
    "model": "MiniMax-H3",
    "content": [
        {
            "type": "text",
            "text": "雪山日出，金色晨光照亮山峰，镜头缓慢向前推进",
        }
    ],
    "resolution": "2K",
    "ratio": "16:9",
    "seconds": "4",
    "watermark": False,
}

create_response = requests.post(
    f"{BASE_URL}/videos",
    headers={**HEADERS, "Content-Type": "application/json; charset=utf-8"},
    json=request_body,
)
create_response.raise_for_status()
video_id = create_response.json()["id"]

while True:
    status_response = requests.get(
        f"{BASE_URL}/videos/{video_id}", headers=HEADERS
    )
    status_response.raise_for_status()
    task = status_response.json()
    print("status:", task["status"])

    if task["status"] == "completed":
        break
    if task["status"] == "failed":
        raise RuntimeError(task.get("error", "video generation failed"))
    time.sleep(5)

content_response = requests.get(
    f"{BASE_URL}/videos/{video_id}/content", headers=HEADERS
)
content_response.raise_for_status()
with open("minimax-h3.mp4", "wb") as output_file:
    output_file.write(content_response.content)

Usage 与计费

任务完成后，usage 返回本次任务的实际用量：

字段	含义
`input_video_seconds`	输入参考视频的实际计费秒数
`output_video_seconds`	输出视频的实际计费秒数
`input_image_count`	输入参考图片数量

平台按模型广场展示的当前价格配置计费。当前参考图片计费量为 max(input_image_count - 5, 0)；是否收取输入视频、输出视频或音频费用，以调用时模型广场展示的各用量维度价格为准。

视频生成通常需要较长处理时间并产生较高费用。seconds、输入视频总时长和参考图片数量可能增加计费用量。平台当前未按 768P 与 2K 区分单价；请在批量调用前查看模型广场的最新价格。

常见错误

场景	处理建议
中文提示词乱码	使用 UTF-8 JSON；cURL 建议设置 `application/json; charset=utf-8`
文生视频使用 `adaptive`	改为明确画幅，例如 `16:9`
`reference_audio` 单独使用	同时提供 `reference_image` 或 `reference_video`
首尾帧和 reference 混用	二选一，不要在同一请求中混用
图片超过9张、视频或音频超过3个	减少输入媒体数量
媒体 URL 无法访问或提前过期	使用无需登录、在任务处理期间持续有效的公网 HTTPS URL
输入媒体格式或尺寸不符合要求	按“输入媒体限制”检查格式、编码、大小、像素、时长和帧率
查询一直处于处理中	保持轮询间隔，建议5～20秒；不要重复创建相同任务

API端点参考

使用示例

MiniMax H3 视频生成示例

MiniMax H3 视频生成示例

快速开始

创建任务

查询任务

下载视频

请求参数

content 类型与 role

输入媒体限制

图片

视频

音频

首帧生成视频

首尾帧生成视频

图片、视频和音频参考

Python 完整流程

Usage 与计费

常见错误

​MiniMax H3 视频生成示例

​快速开始

​创建任务

​查询任务

​下载视频

​请求参数

​content 类型与 role

​输入媒体限制

​图片

​视频

​音频

​首帧生成视频

​首尾帧生成视频

​图片、视频和音频参考

​Python 完整流程

​Usage 与计费

​常见错误

MiniMax H3 视频生成示例

快速开始

创建任务

查询任务

下载视频

请求参数

content 类型与 role

输入媒体限制

图片

视频

音频

首帧生成视频

首尾帧生成视频

图片、视频和音频参考

Python 完整流程

Usage 与计费

常见错误