Use Image 1 for the ranger's exact face, short silver hair, green field jacket and red neck scarf. Use Image 2 for the narrow stone footbridge and misty mountain valley. Create one continuous five-second live-action shot of this same adult ranger stepping onto the bridge, gripping the stone parapet and turning toward a distant bird call. The red scarf lifts briefly in the mountain breeze. Camera slowly arcs a few degrees, preserving the person and the bridge's spatial geometry. Realistic cloth, mist and subtle facial recognition. Native stereo breeze, one distant bird and footsteps on stone, no speech or music. No extra people, animals in frame, logos, captions or text.
MiniMax H3 Max Reference to Video API
minimax/h3-max/reference-to-videoMiniMax H3 Max Reference to Video 结合多模态参考生成电影质感视频,支持图片、视频与音频联合引导。它能延续角色外观与运动节奏,同时自适应画幅并稳定交付多档高清成片。
拖拽文件、粘贴剪贴板素材,或输入 URL。 必填,1–9 张静态 JPEG、PNG 或 WebP,每张不超过 30 MB。比例:1:1、4:3、3:4、16:9、9:16、5:2 或 2:5;上传前归一化图片方向。所有参考素材合计最多 12 个。
1/9 个素材
拖拽文件、粘贴剪贴板素材,或输入 URL。 可选,最多 3 个 MP4/MOV,每个不超过 50 MB。每段 2–15 秒,合计不超过 15 秒。16:9 或 9:16、恒定 24 fps、方形像素、无旋转元数据。按输出时长截取后帧数须为 48、120、240 或 360;由服务端精确核验。
1/3 个素材
拖拽文件、粘贴剪贴板素材,或输入 URL。 可选,最多 3 个 MP3/WAV,每个不超过 15 MB。每段 2–15 秒且不超过输出时长,合计不超过 15 秒。32 kHz 单声道或双声道,解码采样数须能被 800 整除;由服务端精确核验。
1/3 个素材
示例
REST API
快速开始
用三个步骤完成第一次参考生视频调用。短示例会说明每项参考素材的作用,并返回用于获取结果的 task_id。
连接 Vidgo API
创建 API Key,将它安全保存在服务端,并通过 Authorization 请求头以 Bearer Token 发送。
- 接口地址
- POST
https://api.vidgo.ai/api/generate/submit - 认证方式
- Authorization: Bearer VIDGO_API_KEY
提交一个生成任务
在短示例中至少提供一张参考图片。视频和音频为可选项,必须与参考图片一起使用。
curl --request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "minimax/h3-max/reference-to-video",
"input": {
"prompt": "Use Image 1 for the adult female taiko performer's exact face, tied-back hair and indigo happi costume. Use Video 1 for the temple courtyard, large drum and the restrained left-to-right camera movement. Use Audio 1 for the dry wooden attack and low resonant drum atmosphere. In one continuous five-second cinematic shot, she raises both sticks, makes one decisive strike on the large drum, and holds the finish as her sleeve settles. Preserve her identity and drum geometry throughout. Match the drum impact to the generated sound, with the resonance spreading through the quiet courtyard. Late golden sunlight, subtle determined expression, no crowd or dialogue, no text, subtitles, logos or advertisements.",
"duration": 5,
"resolution": "768p",
"enable_safety_checker": true,
"aspect_ratio": "16:9",
"reference_image_urls": [
"https://cdn.vidgo.ai/apis/models/minimax/h3-max/reference-to-video/v1/01/input-01.png"
],
"reference_video_urls": [
"https://cdn.vidgo.ai/apis/models/minimax/h3-max/reference-to-video/v1/01/input-02.mp4"
],
"reference_audio_urls": [
"https://cdn.vidgo.ai/apis/models/minimax/h3-max/reference-to-video/v1/01/input-03.wav"
]
}
}'等待并获取结果
使用返回的 task_id 查询同一个任务,直到状态变为 finished 或 failed;成功后读取 data.files[].file_url。
查询状态
GET https://api.vidgo.ai/api/generate/status/{task_id}当状态为 not_started 或 running 时,建议约每 2 秒轮询一次;到达 finished 或 failed 后停止。成功时从 data.files[].file_url 读取视频地址;长任务可逐步延长间隔,也可在提交请求顶层添加 callback_url 异步接收最终结果。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "EY5BASNT7IWV6QKU",
"status": "running",
"created_time": "2026-10-11T22:57:28"
}
}{
"code": 200,
"data": {
"task_id": "EY5BASNT7IWV6QKU",
"status": "finished",
"files": [
{
"file_url": "https://cdn.vidgo.ai/apis/models/minimax/h3-max/reference-to-video/v1/01/output.mp4",
"file_type": "video"
}
],
"created_time": "2026-10-11T22:57:28",
"error_message": null,
"progress": 100
}
}完整可运行示例
理解上面的三步流程后再展开。这里把提交、轮询、终态处理和结果读取合并在一个脚本中。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "minimax/h3-max/reference-to-video",
"input": {
"prompt": "Use Image 1 for the adult female taiko performer's exact face, tied-back hair and indigo happi costume. Use Video 1 for the temple courtyard, large drum and the restrained left-to-right camera movement. Use Audio 1 for the dry wooden attack and low resonant drum atmosphere. In one continuous five-second cinematic shot, she raises both sticks, makes one decisive strike on the large drum, and holds the finish as her sleeve settles. Preserve her identity and drum geometry throughout. Match the drum impact to the generated sound, with the resonance spreading through the quiet courtyard. Late golden sunlight, subtle determined expression, no crowd or dialogue, no text, subtitles, logos or advertisements.",
"duration": 5,
"resolution": "768p",
"enable_safety_checker": true,
"aspect_ratio": "16:9",
"reference_image_urls": [
"https://cdn.vidgo.ai/apis/models/minimax/h3-max/reference-to-video/v1/01/input-01.png"
],
"reference_video_urls": [
"https://cdn.vidgo.ai/apis/models/minimax/h3-max/reference-to-video/v1/01/input-02.mp4"
],
"reference_audio_urls": [
"https://cdn.vidgo.ai/apis/models/minimax/h3-max/reference-to-video/v1/01/input-03.wav"
]
}
}
JSON
)
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
while true; do
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
case "$STATUS" in
finished)
printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
break
;;
failed)
printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
exit 1
;;
not_started|running)
sleep 2
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
done请求参数
model 和 callback_url 位于请求根层;生成参数位于 input。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| model | string | 是 | — | 固定为 minimax/h3-max/reference-to-video。 |
| callback_url | string (URL) | 否 | — | 用于接收任务完成通知的公开 HTTP(S) 地址。 |
| input | object | 是 | — | 生成参数对象:至少包含 1 张参考图片,视频和音频为可选补充;图片、视频和音频合计最多 12 个素材。 |
| input.prompt | string | 是 | — | 场景演进、运镜与动作描述。原始输入最多 50,000 个字符(含首尾空白),去除首尾空白后不能为空。 |
| input.duration | integer | 否 | 5 | 生成时长,支持 5–15 秒的任意整数。 |
| input.resolution | string | 否 | 768p | 视频清晰度,可选 480p、768p 或 1080p。 |
| input.enable_safety_checker | boolean | 否 | true | 是否开启生成内容安全检查器。 |
| input.aspect_ratio | string | 否 | adaptive | adaptive 或 21:9、16:9、4:3、1:1、3:4、9:16。 |
| input.reference_image_urls | string[] | 是 | — | 必填,1–9 张静态 JPEG、PNG 或 WebP 图片的公开 HTTP(S) URL,每张不超过 30 MB。图片比例须为 1:1、4:3、3:4、16:9、9:16、5:2 或 2:5,上传前归一化图片方向。图片、视频和音频合计最多 12 个素材。 |
| input.reference_video_urls | string[] | 否 | — | 可选,最多 3 个 MP4/MOV 视频的公开 HTTP(S) URL,每个不超过 50 MB。每段 2–15 秒,同类合计不超过 15 秒。须为 16:9 或 9:16、恒定 24 fps、方形像素且无旋转元数据。按请求输出时长截取后的计数帧数须为 48、120、240 或 360;由服务端精确核验。 |
| input.reference_audio_urls | string[] | 否 | — | 可选,最多 3 个 MP3/WAV 音频的公开 HTTP(S) URL,每个不超过 15 MB。每段 2–15 秒且不超过请求输出时长,同类合计不超过 15 秒。须为 32 kHz 单声道或双声道,每声道解码采样点数须能被 800 整除;由服务端精确核验。 |
响应字段
提交响应会立即返回任务标识;随着任务推进,状态响应会补充进度、输出文件或失败信息。
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 应用层结果码,成功响应使用 0 或 200。 |
| message | string | 存在时返回便于阅读的响应或错误信息。 |
| data.task_id | string | 任务标识,用于拼接状态查询地址。 |
| data.status | string | 当前状态:not_started、running、finished 或 failed。 |
| data.created_time | string | 任务创建时间,采用日期时间格式。 |
| data.progress | number | 上游提供进度时返回的完成百分比。 |
| data.files[] | array | 任务成功后返回的生成文件列表。 |
| data.files[].file_url | string | 生成视频的公开访问地址。 |
| data.files[].file_type | string | 生成文件类型,例如 video。 |
| data.files[].watermark_url | string | null | 存在水印版本时返回对应地址。 |
| data.error_message | string | null | status 为 failed 时的失败详情。 |
任务生命周期
not_started 与 running 属于非终态;finished 与 failed 是两种终态,收到任意终态后都应停止轮询。
not_started任务已被接受,正在等待排队开始。
running视频正在生成中,请保持轮询查询。
finished任务完成,从 data.files[].file_url 读取视频地址。
failed生成失败,读取 data.error_message 了解原因并停止轮询。
轮询与错误处理
- 认证失败401 表示 Bearer API Key 缺失或无效,请在控制台确认密钥后重试。
- 参数校验400 表示请求参数不合法,请检查 reference 素材总数及格式限制。
- 轮询间隔建议每 2 秒查询一次状态,长任务可按指数退避逐步延长间隔至 5 秒。
- 终态处理仅在 not_started 或 running 时轮询;收到 finished 或 failed 立即终止。
- 回调方式提供 callback_url 可以在生成完成时自动接收推送,无需持续轮询。
模型规格
| 规格 | 取值 | 说明 |
|---|---|---|
| Model | minimax/h3-max/reference-to-video | 异步多模态参考生视频模型标识。 |
| Duration | 5–15 | 整数秒,默认值为 5 秒。 |
| Resolution | 480p | 768p | 1080p | 多档清晰度输出,默认 768p。 |
| Pricing | 10 / 16 / 32 credits/s | 分别对应 480p / 768p / 1080p 档位。 |
相关模型
MiniMax H3 Max Reference to Video API 常见问题
MiniMax H3 Max Reference to Video API 是什么?
MiniMax H3 Max Reference to Video 是 MiniMax 推出并经深度后训练优化的多模态参考生视频模型。它能够结合文本提示词以及输入的图片、视频和音频参考素材,生成 5–15 秒带原生立体声的高保真连贯视频。基于先进的多模态交叉注意力架构,它在深度融合参考角色特征、运动节奏与声学风格的同时,赋予新镜头自然的叙事张力与光影物理表现。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
MiniMax H3 Max Reference to Video 支持哪些参考素材格式?
参考图片支持 1–9 张 JPEG、PNG 或 WebP 格式(单张不超过 30MB);参考视频支持最多 3 个恒定 24fps 的 MP4 或 MOV 文件(单个不超过 50MB);参考音频支持最多 3 个 32kHz 的 MP3 或 WAV 文件(单个不超过 15MB)。所有素材合计不超过 12 个。
MiniMax H3 Max Reference to Video 如何保证角色面容一致性?
建议提供 2–3 张同一角色在不同角度或光线下的清晰肖像作为参考图片,并在提示词中指明“主角面部五官与发型严格延续参考图片中的人物”。模型会将视觉特征提取为多维嵌入向量,在整个生成序列中牢牢锚定人物身份。
MiniMax H3 Max Reference to Video 参考音频如何影响生成结果?
输入的参考音频主要用于指导生成视频的背景声场基调、节奏强弱与音色质感。模型会分析参考音频的频谱特征,并在生成的新视频中合成具备类似声学空间感与氛围特性的原生立体声音频。
MiniMax H3 Max Reference to Video 的 Token 额度如何计算?
每个请求享有 4,096 tokens 的免费参考素材额度。参考图片按比例与数量计量,视频按计费帧数计量,音频按解码采样点计量。若参考总用量超出该额度,超出部分将按每 1,000 tokens 4 积分的比例在基础时长费之外单独计费。
MiniMax H3 Max Reference to Video 的自适应画幅如何运作?
当 aspect_ratio 设置为 adaptive 时,模型会自动检测参考素材中的主体构图与主要图片的长宽比,智能匹配最契合视觉呈现的输出画幅。如果你有确定的分发平台要求,也可以显式指定 16:9、9:16 等固定比例。
Reference to Video 与 Image to Video 有何核心差异?
Image to Video 严格将输入图片作为视频生成的起始第一帧(或终止尾帧),具有强时序起止约束;而 Reference to Video 则将素材作为特征知识库,支持从多张图片、动作视频和音频中各取所需,适合复杂的多镜头与跨资产创作。















