H3 视频生成

minimax-h3 使用 LoopToken 通用异步视频接口，支持文生视频、首帧/尾帧控制，以及参考图片、视频和音频的多模态生成。所有模式都通过请求字段自动识别，无需传 mode。

接口

POST https://api.vibelab.me/v1/videos/generations
GET  https://api.vibelab.me/v1/tasks/{task_id}

提交成功返回 HTTP 202 和 vt_ 开头的公共任务 ID。建议每 5-10 秒查询一次，客户端总超时可设为 15 分钟。

生成模式

模式	触发字段	说明
文生视频	仅 `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

不要提交 webhook 或供应商回调字段。LoopToken 对外统一使用 callback_url，回调内容与任务查询结果保持一致。

首尾帧字段

字段	类型	数量	说明
`first_frame_image`	string	最多 1 个	公网首帧图片 URL
`last_frame_image`	string	最多 1 个	公网尾帧图片 URL，可与首帧组合

多模态参考字段

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

image_with_roles 的元素结构：

子字段	类型	必填	说明
`url`	string	是	非空公网图片 URL
`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 秒

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

请求示例

文生视频

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"
  }'

首尾帧生成

{
  "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"
}

提交响应

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

响应只包含 LoopToken 公共任务 ID 和公共模型 ID，不包含内部路由、供应商任务 ID 或采购价格。

查询结果

curl https://api.vibelab.me/v1/tasks/vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b \
  -H "Authorization: Bearer $LOOPTOKEN_API_KEY"

处理中状态为 pending 或 running。成功结果示例：

{
  "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 是临时地址，请以 expires_at 为准及时下载转存。失败时状态为 failed，并返回归一化的 error.code 和 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。提交时先冻结预计费用，成功后按实际输出时长结算，多退少补；失败任务不扣费。

常见错误

HTTP 状态	`error.type`	常见原因
400	`invalid_request_error`	参数类型/范围错误、两种媒体模式混用、音频单独输入、回调地址不合规
402	`insufficient_credits`	可用 credits 不足
404	`model_not_found`	模型 ID 不存在或当前不可用
422	`invalid_request_error`	输入内容未通过安全检查
502 / 503	`upstream_error` / `no_available_channel`	服务繁忙、请求频率过高或暂时没有可用生成资源

客户端只应依赖公共 HTTP 状态、error.type 和 error.message，不要解析内部错误信息。

H3 视频生成

本页内容