MiniMax
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation认证: Tokenhub API Key / Bearer
MiniMax 视频(海螺视频)是 MiniMax 推出的视频生成模型系列,支持文生视频、图生视频(首帧 / 首尾帧)、多模态参考生视频等能力,具备 2K 直出、原生立体声等特性。H3 支持文本以及图片、视频、音频的多模态参考生成;H3 Max 支持文本和首帧 / 尾帧输入。
两款模型统一使用 content 多模态数组传参,提交端点为 POST /v1/wand/minimax-video-v2/generation,查询端点为 GET /v1/wand/minimax-video-v2/tasks/{task_id}。文生、图生、多模态参考生三种能力共用同一提交端点,通过 content 数组中的素材类型与 role 区分。
基本信息
| 项目 | 值 |
|---|---|
| 调用路径 | Tokenhub API |
| 支持解除护栏 | 支持 |
前提条件
- 已注册腾讯云账号并开通 TokenHub 服务。
- 已在 TokenHub 控制台获取 API Key。
- 已在控制台 - 在线推理 - 视觉模型处开启对应模型的后付费。
参考: 下文所有示例中的 YOUR_API_KEY 均需替换为您自己的 API Key,鉴权方式为请求头 Authorization: Bearer YOUR_API_KEY。
各版本支持规格
| 版本 | 分辨率 | 比例 | 时长 | 选型建议 |
|---|---|---|---|---|
minimax-video-h3 | 768P / 2K | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 | 4 ~ 15 秒 | 旗舰款:2K 直出、多模态参考(图 / 视频 / 音频)、原生立体声。 |
minimax-video-h3-max | 480P / 768P | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 | 5~15 秒 | H3 极速版:出片更快、成本更低;不支持中间帧与多模态参考生视频。 |
参考: ratio(画幅)取值规则:文生视频必填且不能为 adaptive;图生视频由输入图片决定(恒 adaptive);多模态参考生视频可选。
输入模式
| 版本 | 输入 |
|---|---|
minimax-video-h3 | 文生视频 / 图生视频(首帧和尾帧)/ 基于多模态参考的生成 |
minimax-video-h3-max | 文生视频 / 图生视频(首帧 / 尾帧),不支持中间帧。 |
分辨率转换
| 版本 | 输入分辨率 | 输出分辨率 |
|---|---|---|
minimax-video-h3 | 1080P / 4K | 768P / 2K |
minimax-video-h3-max | 1080P / 2K / 4K | 768P |
H3 Max 不支持中间帧和多模态参考输入。
调用流程
视频生成属于耗时较长的任务(通常 1~3 分钟),因此 API 采用异步调用方式,由以下两个步骤组成。
- 提交任务:调用
POST /v1/wand/minimax-video-v2/generation,成功后会返回task_id。 - 轮询结果:用
task_id调用任务结果查询 API,直到状态变为task.status = succeeded,再从task.content.url中获取视频 URL。
参考: 所有 API 响应中都包含用于排查问题的顶层 request_id。查询 API 还会返回表示用量(含 tokenhub_usage.total_tokens)的 tokenhub_usage。任务状态枚举为 queued / running / succeeded / failed / cancelled,请以实际响应为准。
文生视频
API 说明
若仅使用文本提示词生成视频,请在提示词中用自然语言直接描述运镜等镜头表现。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| model | 必填 | string | 模型名称。取值:minimax-video-h3、minimax-video-h3-max |
| content | 必填 | array[object] | 多模态输入数组。文生视频时仅包含一个 text 元素。子字段:type(text)、text(提示词)。 |
| resolution | 必填 | string | 视频分辨率。h3:768P / 2K(1080P 输入会降级为 768P,4K 输入会降级为 2K),h3-max:仅支持 480P / 768P,不支持 2K(1080P / 2K / 4K 输入会在无额外提示的情况下降级为 768P)。 |
| duration | 必填 | integer | 视频时长(秒)。h3:4~15 的整数,h3-max:5~15 的整数(不支持 4 秒)。 |
| ratio | 必填 | string | 宽高比。文生视频时为必填,且不能使用 adaptive(adaptive 会按 16:9 处理)。可选项:21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16。 |
| aigc_watermark | 选填 | boolean | 是否添加 AIGC 水印。默认值:false。 |
请求示例
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "minimax-video-h3",
"content": [
{
"type": "text",
"text": "一只橙色小猫在窗台上看向镜头"
}
],
"resolution": "2K",
"duration": 6,
"ratio": "16:9"
}'参考: 若要调用高速版本,请将示例中的 model 换成 minimax-video-h3-max。h3-max 不支持 2K 或 4 秒 时长。
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| task_id | string | 所创建任务的任务 ID,用于轮询查询任务状态。 |
| request_id | string | 用于排查问题的唯一请求标识符。 |
参考: 提交响应中不包含 base_resp。提交是否成功,以 HTTP 状态码和是否返回 task_id 判断。
响应示例
{
"task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
"request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"
}错误码
请求失败时会返回错误码。具体错误码和处理建议请参考「附录:统一错误码」。任务提交成功后,生成阶段的任务状态可通过「查询任务结果」API 确认。
图生视频(首帧 / 首帧和尾帧)
API 说明
将图片作为首帧,并可选地同时指定为尾帧,再结合文本提示词生成视频。输出宽高比跟随输入图片。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| model | 必填 | string | 模型名称。取值:minimax-video-h3、minimax-video-h3-max |
| content | 必填 | array[object] | 多模态输入数组:text 1 个 + image_url 项 1~2 个(role 为 first_frame / last_frame,首帧可省略 role)。图片约束:JPG / JPEG / PNG / WEBP / HEIC / HEIF,宽高 [256, 5760] px,宽高比 [0.4, 2.5],单张图片 ≤ 30 MB;支持 URL 或 Base64 两种格式。• URL:需公网可访问(http / https)。 • Base64:所有图片大小和 ≤ 75 MB,转为 Base64 后大小和 ≤ 100 MB;格式为 data:image/<图片格式>;base64,<Base64 编码>(注:图片为 jpg 时格式填 jpeg)。 |
| resolution | 必填 | string | 视频分辨率。h3:768P / 2K(1080P 输入会降级为 768P,4K 输入会降级为 2K),h3-max:仅支持 480P / 768P,不支持 2K(1080P / 2K / 4K 输入会在无额外提示的情况下降级为 768P)。 |
| duration | 必填 | integer | 视频时长(秒)。h3:4~15 的整数,h3-max:5~15 的整数(不支持 4 秒)。 |
| ratio | 选填 | string | 宽高比。图生视频的默认值为 adaptive(由输入图片决定),也可以显式指定 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16。其他取值会被忽略且不报错。 |
| aigc_watermark | 选填 | boolean | 是否添加 AIGC 水印。默认值:false。 |
参考: minimax-video-h3-max 支持首帧和尾帧,但不支持中间帧。
请求示例
首帧和尾帧生成:
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "minimax-video-h3",
"content": [
{
"type": "text",
"text": "从首帧自然过渡到尾帧"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/start.jpg"
},
"role": "first_frame"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/end.jpg"
},
"role": "last_frame"
}
],
"resolution": "768P",
"duration": 6
}'响应参数
与「文生视频」的输出参数相同。
响应示例
{
"task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
"request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"
}错误码
请求失败时会返回错误码。具体错误码和处理建议请参考「附录:统一错误码」。任务状态说明与「文生视频」相同。
多模态参考生视频(H3 专用)
API 说明
将文本与参考图片、参考视频或参考音频组合生成视频。该功能仅支持 minimax-video-h3。minimax-video-h3-max 不支持多模态参考输入,若 content 中存在 reference_image、reference_video 或 reference_audio,会立即返回参数错误。不能仅输入音频。必须包含至少一个参考视频或图片。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| model | 必填 | string | 模型名称。取值:minimax-video-h3 |
| content | 必填 | array[object] | 多模态输入数组:text 1 个 + 参考素材(role 为 reference_image / reference_video / reference_audio)。参考图片:最多 9 个,参考视频:最多 3 个,参考音频片段:最多 3 个,全部素材:最多 12 个。子字段和素材限制条件请参考下表。 |
| resolution | 必填 | string | 视频分辨率。可选项:768P / 2K。 |
| duration | 必填 | integer | 视频时长(秒)。可选项:4~15 的整数。 |
| ratio | 选填 | string | 宽高比。默认值为 adaptive(自动),也可显式设为 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16。 |
| aigc_watermark | 选填 | boolean | 是否添加 AIGC 水印。默认值:false。 |
content 数组元素的子字段:
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| type | 必填 | string | 素材类型。枚举值:text / image_url / video_url / audio_url。 |
| text | 条件必填 | string | 文本提示词。type=text 时为必填(每个请求都必须包含一个非空的 text 项)。 |
| image_url | 条件必填 | object | 图片素材。type=image_url 时为必填。支持 URL 或 Base64。约束:JPG / JPEG / PNG / WEBP / HEIC / HEIF,宽高 [256, 5760] px,宽高比 [0.4, 2.5],单张 ≤ 30 MB;Base64 格式为 data:image/<格式>;base64,<编码>(jpg 填 jpeg)。结构:{ "url": "..." } |
| video_url | 条件必填 | object | 视频素材。type=video_url 时为必填。支持 URL 或 Base64。约束:MP4 / MOV,单段 2~15 秒、总时长 ≤ 15 秒,单个 ≤ 50 MB;Base64 所有参考视频大小和 ≤ 64 MB,格式为 data:video/<格式>;base64,<编码>(mov 填 quicktime)。结构:{ "url": "..." } |
| audio_url | 条件必填 | object | 音频素材。type=audio_url 时为必填。支持 URL 或 Base64。约束:WAV / MP3,单段 2~15 秒,单个 ≤ 15 MB;Base64 所有音频大小和 ≤ 48 MB、转为 Base64 后 ≤ 64 MB,格式为 data:audio/<格式>;base64,<编码>(mp3 填 mpeg)。结构:{ "url": "..." } |
| role | 选填 | string | 素材用途。枚举值:first_frame / last_frame / reference_image / reference_video / reference_audio。 |
参考: 图生视频和多模态参考生成是互斥的。若 content 中存在 reference_image / reference_video / reference_audio 角色中的任意一个,就不能使用 first_frame / last_frame,反之亦然。参考视频:MP4 / MOV(H.264 / H.265),不超过 50 MB,最多 3 个片段,每个片段 2~15 秒 且总时长不超过 15 秒,宽度和高度分辨率 256~5760 px,帧率 23.976~60 fps。参考音频:WAV / MP3,不超过 15 MB,最多 3 个片段,每个片段 2~15 秒 且总时长不超过 15 秒。不能仅输入音频。整个请求正文大小不能超过 64 MB。较大的文件请使用公网 URL 而非 Base64。
请求示例
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "minimax-video-h3",
"content": [
{
"type": "text",
"text": "参考图中的角色在参考视频的场景中自然运动"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/character.jpg"
},
"role": "reference_image"
},
{
"type": "video_url",
"video_url": {
"url": "https://example.com/scene.mp4"
},
"role": "reference_video"
}
],
"resolution": "768P",
"duration": 6,
"ratio": "16:9"
}'响应参数
与「文生视频」的输出参数相同。
响应示例
{
"task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
"request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"
}错误码
请求失败时会返回错误码。具体错误码和处理建议请参考「附录:统一错误码」。任务状态说明与「文生视频」相同。
查询任务结果
API 说明
所有生成功能共用的任务查询方式。提交任务并返回 task_id 后,通过统一的任务查询端点轮询任务状态。成功后从结果中获取视频 URL。
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/tasks/{task_id}
参考: 路径中的 {task_id} 是提交任务时返回的 task_id,示例中以 YOUR_TASK_ID 表示。视频生成大约需要 1~3 分钟,建议每 3~5 秒 轮询一次。
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| task_id | 必填 | string | 任务 ID(路径参数),即提交任务时返回的 task_id。 |
请求示例
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/tasks/YOUR_TASK_ID' \
-H 'Authorization: Bearer YOUR_API_KEY'响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| task | object | 任务对象。 |
| task.id | string | 任务 ID。 |
| task.model | string | 所使用的模型名称(例如 MiniMax-H3、MiniMax-H3-Max)。 |
| task.status | string | 任务状态:queued / running / succeeded / failed。 |
| task.task_type | string | 任务类型(例如 generation(视频生成))。 |
| task.created_at | integer | 任务创建时间,为秒级 Unix 时间戳。 |
| task.updated_at | integer | 任务更新时间,为秒级 Unix 时间戳。 |
| task.content | object | 所创建任务结果的内容,成功时返回。 |
| task.content.url | string | 生成视频的下载 URL。它是有效期为 12 小时 的临时 URL,请立即下载并保存。 |
| task.duration | integer | 视频时长(秒)。 |
| task.resolution | string | 视频分辨率(例如 768P)。 |
| task.ratio | string | 视频宽高比(例如 16:9)。 |
| task.usage | object | 任务的视频用量信息。 |
| task.usage.input_image_count | integer | 输入图片数。 |
| task.usage.input_seconds | integer | 输入视频时长(秒)。 |
| task.usage.output_seconds | integer | 输出视频时长(秒)。 |
| task.usage.total_seconds | integer | 全部视频时长(秒)。 |
| tokenhub_usage | object | 本次请求的用量。 |
| tokenhub_usage.total_tokens | integer | 本次任务消耗的 token 数,用于计费和结算。 |
| request_id | string | 用于定位和排查问题的唯一请求标识符。 |
参考: 查询响应是不含 base_resp 或顶层 status 的 task 对象。任务标识符和状态位于 task.id / task.status 中。
响应示例
生成成功:
{
"task": {
"id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
"model": "MiniMax-H3-Max",
"task_type": "generation",
"status": "succeeded",
"created_at": 1772345678,
"updated_at": 1772345810,
"resolution": "768P",
"duration": 5,
"ratio": "16:9",
"content": {
"url": "https://example.com/output-video.mp4"
},
"usage": {
"total_seconds": 5,
"input_seconds": 0,
"output_seconds": 5,
"input_image_count": 0
}
},
"tokenhub_usage": {
"total_tokens": 102655
},
"request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"
}错误码
| status | 说明 | 处理建议 |
|---|---|---|
| succeeded | 生成成功 | 从 task.content.url 中获取视频 URL。 |
| queued / running | 排队等待 / 生成中 | 每 3~5 秒 轮询一次,直到任务成功。 |
| failed | 生成失败 | 确认失败原因(参考 task.error)并修正后重试。若持续失败,请联系技术支持并提供 request_id。 |
请求级错误码请参考「附录:统一错误码」。
附录
统一错误码
| HTTP 状态码 | 业务码 | 错误信息 | 说明 |
|---|---|---|---|
200 | 0 | 成功 | 请求成功。 |
401 | 1000 | 认证失败 | 缺少 Authorization 或 apikey 无效。 |
401 | 1001 | Authorization 为空 | 未传入 Authorization 头。 |
401 | 1002 | Authorization 无效 | apikey 无效或已过期。 |
401 | 1003 | Authorization 尚未生效 | apikey 尚未生效。 |
401 | 1004 | Authorization 已过期 | apikey 已过期。 |
429 | 1100 | 账号异常 | 账号异常(可能因结算欠费、停用或封禁导致)。 |
429 | 1101 | 账号欠费(后付费) | 后付费账号的结算已欠费。 |
429 | 1102 | 资源包耗尽或已过期 | 资源包已耗尽或已过期。 |
403 | 1103 | 拒绝访问所请求的资源 | 无法访问所请求的资源(未订阅相应模型/功能)。 |
400 | 1200 | 请求参数有误 | 请求参数有误(缺少必填字段、类型有误、枚举值超出范围等)。 |
400 | 1201 | 参数无效 | 参数值有误。请在文档中确认有效取值范围。 |
404 | 1202 | 所请求的方法无效 | HTTP 方法有误。 |
404 | 1203 | 所请求的资源不存在 | 端点路径有误或资源不存在。 |
400 | 1300 | 触发平台策略 | 触发了平台策略(例如内容审核未通过或输入不合规)。 |
400 | 1301 | 触发平台敏感词列表 | 内容中包含敏感词或不合规的提示词。 |
429 | 1302 | API 调用频率过高 | 调用频率过高,已触发限速。 |
429 | 1303 | 并发数或 QPS 超出限制 | 并发数或 QPS 超出预设配额。 |
400 | 1304 | 触发 IP 策略 | 触发了基于 IP 地址策略的拦截。 |
500 | 5000 | 内部服务器错误 | 内部服务器错误。 |
503 | 5001 | 服务器暂时不可用 | 服务暂时不可用(通常因高负载或维护导致)。 |
504 | 5002 | 服务器内部超时 | 服务器内部超时。 |
通用素材限制条件
图片:JPG / JPEG / PNG / WEBP / HEIC / HEIF,不超过 30 MB,宽度和高度 256~5760 px,宽高比 0.4~2.5,首帧最多 1 个,尾帧最多 1 个,参考图片最多 9 个。
视频(参考视频,h3 专用):MP4 / MOV(H.264 / H.265,音频 AAC / MP3),不超过 50 MB,最多 3 个片段,每个片段 2~15 秒 且总时长不超过 15 秒,宽度和高度 256~5760 px,宽高比 0.4~2.5,帧率 23.976~60 fps。
音频(参考音频,h3 专用):WAV / MP3,不超过 15 MB,最多 3 个片段,每个片段 2~15 秒 且总时长不超过 15 秒。
参考: 整个请求正文大小不能超过 64 MB。较大的文件请使用公网 URL 而非 Base64。
FAQ
1. 两个模型中应该选择哪一个?
- 需要
2K直接输出、多模态参考(参考图片/视频/音频)、最短时长4 秒时:minimax-video-h3。 - 不需要多模态参考,但要 H3 的画质,并希望生成更快、成本更低时:
minimax-video-h3-max。
2. 时长和分辨率的限制是什么?
- h3:时长
4~15 秒,分辨率768P/2K(1080P输入会降级为768P,4K会降级为2K)。 - h3-max:时长
5~15 秒(不支持4 秒),分辨率仅支持480P/768P,1080P/2K/4K输入会在无额外提示的情况下降级为768P。
3. 如何控制运镜?
在提示词中用自然语言描述运镜,例如「镜头缓慢推近」或「镜头向左横移」。无需特殊的指令语法。
4. 生成的视频链接会过期吗?
链接会过期。生成结果是有效期为 12 小时 的临时地址。任务成功后,请立即下载视频文件并转存到自有存储中。请勿依赖该链接长期使用。