MiniMax H3 Reference-to-Video API
minimax/h3/reference-to-videoMiniMax H3 Reference-to-Video API 接受提示词、最多 9 张参考图片、3 个参考视频和 3 个可选参考音频。请求必须至少包含一张图片或一个视频,再选择 5–15 秒时长及 adaptive 或固定画面比例,提交固定 2K 视频任务。
输入

输出
已就绪继续使用
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/reference-to-video",
"input": {
"prompt": "使用第一张图片定义角色外观,并参考视频中的运动方式。",
"reference_image_urls": [
"https://example.com/character.jpg"
],
"reference_video_urls": [
"https://example.com/motion.mp4"
],
"duration": 5,
"resolution": "2K",
"aspect_ratio": "adaptive"
}
}'等待并获取结果
使用返回的 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": "task-unified-...",
"status": "running",
"created_time": "2026-08-22T10:00:00Z"
}
}{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "finished",
"files": [
{
"file_url": "https://storage.vidgo.ai/generated/video.mp4",
"file_type": "video"
}
],
"created_time": "2026-08-22T10:00:00Z",
"progress": 100,
"error_message": null
}
}完整可运行示例
理解上面的三步流程后再展开。这里把提交、轮询、终态处理和结果读取合并在一个脚本中。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "minimax/h3/reference-to-video",
"input": {
"prompt": "使用第一张图片定义角色外观,并参考视频中的运动方式。",
"reference_image_urls": [
"https://example.com/character.jpg"
],
"reference_video_urls": [
"https://example.com/motion.mp4"
],
"duration": 5,
"resolution": "2K",
"aspect_ratio": "adaptive"
}
}
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/reference-to-video。 |
| callback_url | string (URL) | 否 | — | 用于接收最终异步结果的公开 HTTP(S) 地址;使用轮询时可省略。 |
| input | object | 是 | — | 下方模型生成参数的容器。 |
| input.prompt | string | 是 | — | 描述场景和各参考素材作用,去除首尾空白后为 1–2,000 个字符。 |
| input.reference_image_urls | string[] | 条件必填 | — | 最多 9 个图片地址;图片或视频至少提供一项。 |
| input.reference_video_urls | string[] | 条件必填 | — | 最多 3 个视频地址;图片或视频至少提供一项。 |
| input.reference_audio_urls | string[] | 否 | — | 最多 3 个音频地址,音频不能作为唯一参考类型。 |
| input.duration | integer | 否 | 5 | 生成时长,必须是 5–15 的整数秒。 |
| input.resolution | string | 否 | 2K | 固定输出分辨率,唯一可接受值为 2K。 |
| input.aspect_ratio | string | 否 | — | 可选 adaptive、21:9、16:9、4:3、1:1、3:4 或 9:16。 |
响应字段
提交响应会立即返回任务标识;随着任务推进,状态响应会补充进度、输出文件或失败信息。
| 字段 | 类型 | 说明 |
|---|---|---|
| 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视频正在生成,继续使用同一个 task_id 查询。
finished生成成功,从 data.files[].file_url 读取视频地址。
failed生成因错误终止,读取 data.error_message,不再继续轮询。
轮询与错误处理
- 认证失败401 表示 Bearer API Key 缺失或无效,修正凭证后再重试。
- 参数校验400 表示请求无效,应读取响应信息并修正对应字段。
- 轮询间隔初始建议约每 2 秒查询一次,长任务应逐步延长间隔。
- 终态处理仅在 not_started 或 running 时继续查询;遇到 finished 或 failed 立即停止。
- 回调方式提供 callback_url 可异步接收最终结果;否则使用状态查询接口。
模型规格
| 规格 | 取值 | 说明 |
|---|---|---|
| 输入模式 | 提示词 + 参考素材 | 必须至少提供一张参考图片或一个参考视频,参考音频为可选。 |
| 输出 | 视频 | MiniMax H3 Reference-to-Video API 返回一个异步视频生成任务。 |
| 分辨率 | 2K | 所有通过校验的请求都使用固定分辨率。 |
| 时长 | 5–15 秒 | 必须使用整数秒,默认值为 5 秒。 |
| 画面比例 | adaptive 或固定比例 | 支持 adaptive、21:9、16:9、4:3、1:1、3:4 和 9:16。 |
| 参考素材上限 | 9 图片 / 3 视频 / 3 音频 | 没有图片或视频参考时,不能单独提交音频。 |
相关模型
MiniMax H3 参考素材生视频 API 常见问题
什么是 MiniMax H3 Reference-to-Video API?
MiniMax H3 Reference-to-Video API 接受提示词、最多 9 张参考图片、3 个参考视频和 3 个可选参考音频,并返回固定 2K 视频的异步任务。请求必须至少包含一张图片或一个视频,因此只提交音频会被拒绝。
如何调用 MiniMax H3 Reference-to-Video API?
使用 Bearer API Key 向 /api/generate/submit 发送 POST 请求,将 model 设为 minimax/h3/reference-to-video,并把生成参数放入 input。接口会立即返回 task_id;API 页签提供可运行的 cURL、JavaScript 和 Python 示例,完整字段定义见 https://docs.vidgo.ai/api-manual/video-series/minimax-h3-reference-to-video。
MiniMax H3 Reference-to-Video 如何计费?
生成视频每秒消耗 21 积分。每个参考视频的时长会分别向下取整,并按每秒 21 积分计费;第 6–9 张参考图片每张额外消耗 6.4 积分。运行按钮会显示计算后的美元价格;远程参考视频时长未知时则显示最低美元价格。
MiniMax H3 Reference-to-Video 接受哪些输入?
核心输入包括 prompt、reference_image_urls、reference_video_urls、reference_audio_urls、duration、resolution 和 aspect_ratio。必须至少包含一张图片或一个视频,不能只提交音频;duration 为 5–15 的整数秒,resolution 固定为 2K。上方参数表列出了 9/3/3 素材上限、默认值以及 adaptive 或固定构图选项。
如何获取生成的视频?
使用返回的 task_id 轮询 GET /api/generate/status/{task_id},直到状态变为 finished 或 failed。任务完成后从 data.files[].file_url 读取视频地址;也可以在提交请求中加入 callback_url,异步接收最终结果。
应该选择哪个 MiniMax H3 API 模式?
请求需要多张图片、多个视频或可选音频参考时选择 Reference-to-Video;需要一张必填首帧和一张可选尾帧时选择 Image-to-Video;请求不包含源素材时选择 Text-to-Video。










