获取 API Key 获取 API
文档

MiniMax-H3 视频生成

- 异步处理模式,返回任务 ID 用于后续查询

  • 支持文生视频、图生视频(首帧 / 尾帧 / 首尾帧)、多模态参考生视频(参考图 + 参考视频 + 参考音频)
  • 支持 2K / 768P 分辨率,时长 4 ~ 15 秒,带音轨
  • 与 MiniMax-Hailuo-02 / MiniMax-Hailuo-2.3 共用统一提交与查询接口

请求示例

curl --request POST \
  --url https://api.openveer.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MiniMax-H3",
    "prompt": "一个男孩在海边打篮球,黄昏,海浪拍岸,电影感运镜",
    "duration": 5,
    "resolution": "2K",
    "aspect_ratio": "16:9"
  }'

响应示例

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ"
    }
  ]
}

认证

Authorization string

所有接口均需要使用 Bearer Token 进行认证

获取 API Key:

访问 API Key 管理页面 获取您的 API Key

使用时在请求头中添加:

Authorization: Bearer YOUR_API_KEY

生成模式

MiniMax-H3 通过请求字段自动路由到对应模式,无需指定 mode 字段:

模式 触发条件 能力
文生视频(T2V) 只传 prompt 及通用字段 纯文本驱动生成
图生视频(I2V) 传入 first_frame_image / last_frame_image(或 image_with_roles 中的 first_frame / last_frame) 首帧、尾帧、首尾帧控制
多模态参考(R2V) 传入 image_urls / video_urls / audio_urls,或 image_with_roles 中的 reference_image 参考图 + 参考视频 + 参考音频
警告

严格互斥:图生视频字段(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。

警告

不能只给音频。 传了 audio_urls 时,必须至少再配一个参考图或参考视频。

请求参数

通用字段

model string

固定值:MiniMax-H3

警告



必须显式传递 model 字段。 已接入海螺系列的客户端将 model 改为 MiniMax-H3 即可使用本模型。

prompt string

视频内容描述,任何场景都必填且不能为空,单条 ≤ 7000 字符

建议详细描述场景、主体、动作、风格等,以获得更好的生成效果。

示例:"一个男孩在海边打篮球,黄昏,海浪拍岸,电影感运镜"

duration integer

生成时长(秒)

  • 取值范围:4 \~ 15 的整数
  • 默认值:5
resolution string

视频分辨率

可选值:

  • 2K(默认)
  • 768P
aspect_ratio string

宽高比。也可用 size 或 ratio 传,效果相同。

可选具体比例:21:9、16:9、4:3、1:1、3:4、9:16

不同场景下的行为见下方「宽高比规则」。

watermark boolean

是否添加 AIGC 水印

默认值:false

兼容字段名:aigc_watermark

webhook string

任务到达终态(成功 / 失败)时,本服务主动推送到该地址

注意



请使用 webhook,不要传官方的 callback_url。callback_url 由本服务内部使用,不接受用户传入。

图生视频字段

要做首帧 / 尾帧图生视频,必须显式指定,不要依赖 image_urls 张数推断。

first_frame_image string

首帧图 URL

传入后将以该图片作为视频的起始画面。

last_frame_image string

尾帧图 URL

传入后将以该图片作为视频的结束画面,可与 first_frame_image 组合实现首尾帧控制。

多模态参考字段

image_urls string[]

参考图 URL 数组

警告



image_urls 里的图一律按参考图(reference_image)处理,不管传几张。不会按张数自动当成首帧 / 首尾帧。

  • 数量:≤ 9
video_urls string[]

参考视频 URL 数组

  • 数量:≤ 3
  • 格式与限制见下方「输入媒体限制」
audio_urls string[]

参考音频 URL 数组

  • 数量:≤ 3
  • 不能单独使用,必须搭配参考图或参考视频

通用图片数组(可选写法)

image_with_roles object[]
带角色的图片数组,可替代 first_frame_image / last_frame_image / image_urls。每个元素结构如下:
url string

图片 URL

role string

图片角色,可选值:

  * first_frame(也接受 first)— 首帧(图生视频)
  * last_frame(也接受 last)— 尾帧(图生视频)
  * reference_image(也接受 reference)— 参考图(多模态参考)
示例(首尾帧):
{
  "image_with_roles": [
    {"url": "https://example.com/start.png", "role": "first_frame"},
    {"url": "https://example.com/end.png", "role": "last_frame"}
  ]
}
示例(参考图):
{
  "image_with_roles": [
    {"url": "https://example.com/char.png", "role": "reference_image"}
  ]
}

宽高比规则

场景 aspect_ratio 行为
文生视频(只有 prompt) 必须是具体比例;不传或传 adaptive 会回落到 16:9
图生视频(有首 / 尾帧) 由输入图片决定,传什么都会被忽略(恒 adaptive)
多模态参考生视频 可选,默认 adaptive;也可显式指定具体比例

可用具体比例:21:9、16:9、4:3、1:1、3:4、9:16。

输入媒体限制

请求体总大小 ≤ 64 MB。大文件请使用公网 URL,不要使用 Base64。

图片

项 限制
格式 JPG / JPEG / PNG / WEBP / HEIC / HEIF
单文件 ≤ 30 MB
宽高 256 \~ 5760 px
长宽比(宽/高) 0.4 \~ 2.5
数量 首帧 ≤ 1、尾帧 ≤ 1、参考图 ≤ 9

视频(仅多模态参考场景)

项 限制
格式 MP4(.mp4)、MOV(.mov)
编码 视频 H.264/AVC、H.265/HEVC;音频 AAC、MP3
单文件 ≤ 50 MB
个数 ≤ 3
时长 单段 2 \~ 15 s;总时长 ≤ 15 s
宽高 / 长宽比 / 帧率 256 \~ 5760 px / 0.4 \~ 2.5 / 23.976 \~ 60

音频(仅多模态参考场景)

项 限制
格式 WAV、MP3
单文件 ≤ 15 MB
个数 ≤ 3
时长 单段 2 \~ 15 s;总时长 ≤ 15 s

参数约束

以下约束违反时请求将被拒绝并返回 400(敏感内容可能返回 422),且 不产生计费:

参数 约束
prompt 任何场景必填且非空,≤ 7000 字符
duration 仅接受 4 \~ 15 的整数
resolution 2K(默认)或 768P
aspect_ratio 见「宽高比规则」;文生不传时回落 16:9
首尾帧与参考素材 互斥,不能混用
audio_urls 不能单独输入,须搭配参考图或参考视频
参考图 ≤ 9
参考视频 ≤ 3
参考音频 ≤ 3
参考视频探测失败 返回 input_video_probe_failed(URL 不可访问或文件损坏),未扣费

响应

code integer

响应状态码,成功时为 200

data array
返回数据数组
status string

任务状态,初始提交时为 submitted

task_id string

任务唯一标识符,用于查询任务状态和结果

请求示例

场景 1:文生视频

{
  "model": "MiniMax-H3",
  "prompt": "一个男孩在海边打篮球,黄昏,海浪拍岸,电影感运镜",
  "duration": 6,
  "resolution": "2K",
  "aspect_ratio": "16:9"
}

场景 2:图生视频 — 首帧

{
  "model": "MiniMax-H3",
  "prompt": "Pull focus to the people in the background and add more steam to the ramen bowl.",
  "first_frame_image": "https://cdn.example.com/ramen.png",
  "duration": 5,
  "resolution": "2K"
}

场景 3:图生视频 — 首尾帧

{
  "model": "MiniMax-H3",
  "prompt": "镜头从清晨缓慢过渡到日落",
  "first_frame_image": "https://cdn.example.com/morning.png",
  "last_frame_image": "https://cdn.example.com/sunset.png",
  "duration": 8
}

场景 4:多模态参考生视频

{
  "model": "MiniMax-H3",
  "prompt": "角色说话:Follow the wind, live free. Leave worries behind, enjoy the moment,音色参考音频1",
  "image_with_roles": [
    {"url": "https://cdn.example.com/char.png", "role": "reference_image"}
  ],
  "video_urls": ["https://cdn.example.com/ref_motion.mp4"],
  "audio_urls": ["https://cdn.example.com/ref_voice.mp3"],
  "duration": 5,
  "resolution": "2K"
}

场景 5:使用 image_with_roles 指定首尾帧

{
  "model": "MiniMax-H3",
  "prompt": "镜头从清晨缓慢过渡到日落",
  "image_with_roles": [
    {"url": "https://cdn.example.com/morning.png", "role": "first_frame"},
    {"url": "https://cdn.example.com/sunset.png", "role": "last_frame"}
  ],
  "duration": 8
}
注意

查询任务结果

视频生成为异步任务,提交后会返回 task_id。使用 获取任务状态 接口查询生成进度和结果。

建议每 5 \~ 10 秒轮询一次,客户端超时建议设为 15 分钟。成功后 result.videos[0].url 为 mp4 地址;视频 URL 约 24 小时有效,请及时转存。任务失败时会自动退款。