H3 视频生成

minimax-h3：文生视频、首尾帧、多模态参考生成，4–15 秒、768P/2K，异步，用 GET /v1/tasks/{task_id} 查询

POST/v1/videos/generations

GET/v1/tasks/{task_id}

minimax-h3 使用通用异步视频接口（提交、轮询、任务对象、回调、错误见接口说明）。所有模式通过请求字段自动识别，无需传 mode。提交成功返回 HTTP 202 和 vt_ 开头的任务 ID，客户端总超时可设为 15 分钟。

项	值
模型	`minimax-h3`
模式	异步（提交 → 轮询 `GET /v1/tasks/{task_id}`）
时长 / 分辨率	`4-15` 秒（默认 `5`） / `768P`、`2K`（默认 `2K`）
计费	按秒 + 参考图/参考视频，官方价格原值，见计费
媒体保留	`video_url` 最长保留至任务完成后 72 小时

快速开始

curl https://api.vibelab.me/v1/videos/generations \
  -H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "prompt": "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
    "duration": 5,
    "resolution": "2K",
    "aspect_ratio": "16:9"
  }'

提交响应（响应只包含公共任务 ID 和公共模型 ID，不包含内部路由、供应商任务 ID 或采购价格）：

{
  "task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
  "model": "minimax-h3",
  "status": "pending",
  "created_at": 1786003200,
  "duration": 5,
  "resolution": "2k"
}

模式选择

模式	触发字段	说明
文生视频	仅 `prompt` 和通用控制字段	纯文本生成；未传宽高比时使用 `16:9`
首尾帧	`first_frame_image` / `last_frame_image`，或对应的 `image_with_roles`	支持首帧、尾帧或首尾帧；宽高比由图片决定
多模态参考	`image_urls` / `video_urls` / `audio_urls`，或 `reference_image` 角色	使用图片、视频、音频约束角色、动作、风格或声音

首尾帧字段与多模态参考字段严格互斥。audio_urls 不能单独使用，必须同时提供至少一张参考图片或一个参考视频。

请求参数

参数	类型	必填	默认	说明
`model`	string	是	-	固定为 `minimax-h3`
`prompt`	string	是	-	非空，最长 7000 字符
`duration`	integer	否	`5`	`4` 到 `15` 秒的整数
`resolution`	string	否	`2K`	`768P` 或 `2K`，不区分大小写
`aspect_ratio`	string	否	见宽高比规则	`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` 或 `adaptive`；别名 `size` / `ratio`
`watermark`	boolean	否	`false`	是否添加 AIGC 水印；别名 `aigc_watermark`
`callback_url`	string	否	-	终态回调地址，只接受可公网访问的 HTTPS URL

首尾帧字段

参数	类型	必填	默认	说明
`first_frame_image`	string	否	-	公网首帧图片 URL，最多 1 个
`last_frame_image`	string	否	-	公网尾帧图片 URL，最多 1 个，可与首帧组合

多模态参考字段

参数	类型	必填	默认	说明
`image_urls`	string[]	否	-	最多 9 个，全部按参考图处理，不会按数量推断首尾帧
`video_urls`	string[]	否	-	最多 3 个参考视频 URL
`audio_urls`	string[]	否	-	最多 3 个参考音频 URL；必须搭配参考图或参考视频
`image_with_roles`	object[]	否	-	为图片显式指定角色，可替代上述图片字段

image_with_roles 元素：

参数	类型	必填	默认	说明
`image_with_roles[].url`	string	是	-	非空公网图片 URL
`image_with_roles[].role`	string	是	-	`first_frame`、`last_frame` 或 `reference_image`

同一请求最多包含 1 张首帧、1 张尾帧和 9 张参考图。image_urls 与 image_with_roles 中的 reference_image 合并计数。

宽高比规则

模式	规则
文生视频	省略或传 `adaptive` 时按 `16:9` 生成，也可传具体比例
首尾帧	由输入图片决定，提交的比例被忽略
多模态参考	默认自适应，也可传具体比例

输入媒体限制

请求体整体上限 10 MiB。较大的媒体文件必须使用无需 Cookie 或登录态即可访问的公网 HTTPS URL，不要内联 Base64。

类型	格式	单文件	其他限制
图片	JPG、JPEG、PNG、WEBP、HEIC、HEIF	30 MB	宽高 256-5760 px，宽高比 0.4-2.5
视频	MP4、MOV	50 MB	H.264/H.265；单段 2-15 秒，总时长不超过 15 秒，23.976-60 fps
音频	WAV、MP3	15 MB	单段 2-15 秒，总时长不超过 15 秒

媒体格式、体积、时长和可访问性由生成服务进一步检查。媒体无法读取或损坏时任务会失败，失败任务不扣费。

请求示例

首尾帧生成：

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

带角色的统一图片数组：

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

多模态参考生成：

{
  "model": "minimax-h3",
  "prompt": "角色迎风说话，保持参考人物、动作节奏和音色",
  "image_with_roles": [
    {"url": "https://example.com/character.png", "role": "reference_image"}
  ],
  "video_urls": ["https://example.com/motion.mp4"],
  "audio_urls": ["https://example.com/voice.mp3"],
  "duration": 5,
  "resolution": "2K",
  "aspect_ratio": "16:9"
}

响应

用 GET /v1/tasks/{task_id} 查询，状态依次为 pending → running → succeeded / failed（终态）。成功结果：

{
  "task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
  "model": "minimax-h3",
  "status": "succeeded",
  "created_at": 1786003200,
  "completed_at": 1786003268,
  "duration": 5,
  "resolution": "2k",
  "credits_charged": 5.715,
  "video_url": "https://media.example.com/video.mp4",
  "expires_at": 1786089668
}

字段	类型	说明
`video_url`	string	视频下载地址，仅 `succeeded` 返回，尽快转存
`expires_at`	integer	`video_url` 失效时间，Unix 秒
`credits_charged`	number	本次实际扣费（积分）
`error`	object	仅 `failed` 返回：`{"code": "timeout" \| "upstream_error", "message": "..."}`；失败任务退回预扣 credits

完整任务对象字段见接口说明。

计费

LoopToken 使用官方价格原值作为实际售价，不另加价，也不展示虚假折扣。10 credits = 1 USD。

项目	实际价格
768P 视频	0.714 credits/秒
2K 视频	1.143 credits/秒
第 1-5 张参考图片	免费
第 6-9 张参考图片	0.286 credits/张
参考视频	按输出分辨率的每秒价格，与生成时长叠加

基础费用 = 生成时长 × 分辨率每秒价格
参考视频费用 = 存在 video_urls 时，生成时长 × 分辨率每秒价格
参考图费用 = max(参考图数量 - 5, 0) × 0.286
总费用 = 基础费用 + 参考视频费用 + 参考图费用

例：5 秒 2K 视频、不含参考视频 = 5 × 1.143 = 5.715 credits；同时使用参考视频 = 5 × 1.143 × 2 = 11.43 credits。提交时先冻结预计费用，成功后按实际输出时长结算，多退少补；失败任务不扣费。

错误

通用错误见接口说明。本模型提交时的参数校验返回 400 invalid_request_error，message 如下：

`message`	处理
`prompt is required and must be a non-empty string`	传非空 `prompt`
`prompt must not exceed 7000 characters`	缩短提示词
`duration must be an integer between 4 and 15`	时长传 4–15 的整数
`resolution must be one of 768P/2K`	分辨率传 `768P` 或 `2K`
`aspect_ratio must be one of adaptive/21:9/16:9/4:3/1:1/3:4/9:16`	比例取值见请求参数；`size`、`ratio` 别名同理
`watermark must be a boolean`	`watermark` / `aigc_watermark` 传布尔值
`webhook is not supported; use callback_url`	删除 `webhook`，改用 `callback_url`
`first_frame_image must be a non-empty string`	首尾帧图片传非空 URL（`last_frame_image` 同理）
`image_urls must contain at most 9 items`	`image_urls` ≤ 9，`video_urls` / `audio_urls` ≤ 3
`image_with_roles[].role must be one of first_frame/last_frame/reference_image`	修正 `role`
`at most one first frame and one last frame are allowed`	首帧、尾帧各最多 1 张
`at most 9 reference images are allowed`	参考图（含 `image_with_roles` 中的 `reference_image`）合计 ≤ 9
`first/last frame inputs cannot be combined with reference media`	首尾帧与多模态参考二选一
`audio_urls requires at least one reference image or video`	音频须搭配参考图或参考视频

媒体格式、体积、时长和可访问性由生成服务进一步检查，失败表现为异步 failed，不扣费。

注意事项

不要提交 webhook 或供应商回调字段，统一使用 callback_url。大媒体必须用公网 HTTPS URL，不要内联 Base64（请求体上限 10 MiB）。

首尾帧字段与多模态参考字段 → 严格互斥，不能混用。
audio_urls → 不能单独使用，必须搭配参考图或参考视频。
video_urls 存在 → 参考视频费用与生成时长叠加（费用翻倍）。

H3 视频生成

本页内容