大模型服务平台 TokenHub MiniMax 生视频调用指南

一、概述

这篇说说如何通过 TokenHub 调用 MiniMax 的四款视频模型：minimax-video-v2.3、minimax-video-v2.3-fast、minimax-video-h3、minimax-video-h3-max。

注意：说明：

注意：MiniMax 视频在 TokenHub 上有两套提交端点，分别对应两种传参风格，提交与查询的响应结构也不同，请按模型选择对应端点：

注意：其中 v2.3 / v2.3-fast 使用扁平参数（prompt、first_frame_image 等）；h3 / h3-max 使用 content 多模态数组传参，详见各接口章节。提交与查询必须使用同一端点组。

二、前提条件

·已 注册腾讯云 账号并开通 TokenHub 服务。

·已在 TokenHub 控制台 获取 API Key。

·在控制台-在线推理-视觉模型 处开启对应模型的后付费。

注意：说明：

注意：下文所有示例中的 YOUR_API_KEY 均需替换为你自己的 API Key，鉴权方式为请求头 Authorization: Bearer YOUR_API_KEY。

三、调用流程

视频生成为耗时任务（通常 1~3 分钟），接口采用异步调用模式，统一分两步：

1. 提交任务：调用 POST /v1/wand/minimax-video/generation，成功返回 task_id。

2. 轮询结果：携带 task_id 调用 查询任务结果 接口，直至任务状态为成功，从结果中获取视频地址。

注意：所有接口响应均包含 request_id（顶层，用于排查问题）；查询接口额外返回 tokenhub_usage（用量消耗，含 tokenhub_usage.total_tokens）。任务状态枚举以实际返回为准：v2.3 / v2.3-fast 参照为 Preparing / Queueing / Processing / Success / Fail；h3 参照为 queued / running / succeeded / failed / cancelled。

四、模型列表

注意：说明：

六、1. 接口描述

仅凭文本提示词生成视频。支持模型：minimax-video-v2.3（扁平参数）、minimax-video-h3、minimax-video-h3-max（content 数组）。v2.3 支持 [指令] 运镜语法，请参见 附录：运镜指令语法。

接口： POST https://tokenhub.tencentmaas.com/v1/wand/minimax-video/generation

接口： POST https://tokenhub.tencentmaas.com/v1/wand/minimax-video-v2/generation

八、v2.3（扁平参数）：

九、h3 / h3-max（content 数组）：

十一、模型：minimax-video-v2.3

curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/minimax-video/generation' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "minimax-video-v2.3", "prompt": "一只橙色小猫在窗台上看向镜头"}'

十二、模型：minimax-video-h3

curl -X POST 'https://tokenhub.tencentmaas.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"}'

十三、4. 输出参数

V1（minimax-video-v2.3 / v2.3-fast）：

V2（minimax-video-h3 / h3-max）：

注意：说明：

注意：V2 提交响应不含 base_resp（与 V1 不同），提交是否成功以 HTTP 状态码与是否返回 task_id 为准。

十四、5. 响应示例

V1（minimax-video-v2.3）：

{ "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d", "base_resp": { "status_code": 0, "status_msg": "success" }, "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"}

V2（minimax-video-h3 / h3-max）：

{ "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d", "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"}

十五、6. 错误码

请求失败时返回错误码，具体错误码及处理建议请参见 附录：统一错误码。任务提交成功后，生成阶段的任务状态通过 查询任务结果 接口获取。

十七、1. 接口描述

以图片为首帧（v2.3 可选尾帧）结合文本提示词生成视频。支持模型：minimax-video-v2.3、minimax-video-v2.3-fast（扁平参数）、minimax-video-h3、minimax-video-h3-max（content 数组）。输出画幅跟随输入图片。

接口： POST https://tokenhub.tencentmaas.com/v1/wand/minimax-video/generation

接口： POST https://tokenhub.tencentmaas.com/v1/wand/minimax-video-v2/generation

十八、2. 输入参数

v2.3 / v2.3-fast（扁平参数）：

h3 / h3-max（content 数组）：

十九、3. 请求示例

模型：minimax-video-v2.3-fast（首帧）

curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/minimax-video/generation' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "minimax-video-v2.3-fast", "first_frame_image": "https://example.com/input.jpg"}'

模型：minimax-video-h3（首尾帧）

curl -X POST 'https://tokenhub.tencentmaas.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}'

20、4. 输出参数

同 文生视频 输出参数。

21、5. 响应示例

{ "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d", "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"}

22、6. 错误码

请求失败时返回错误码，具体错误码及处理建议见 附录：统一错误码。任务状态说明同 文生视频。

24、1. 接口描述

以文本 + 参考图片 / 参考视频 / 参考音频的组合为参考生成视频，minimax-video-h3 与 minimax-video-h3-max 均支持。不可仅输入音频，须至少包含 1 个参考视频或图片。

接口： POST https://tokenhub.tencentmaas.com/v1/wand/minimax-video-v2/generation

25、2. 输入参数

content 数组元素子字段：

26、3. 请求示例

curl -X POST 'https://tokenhub.tencentmaas.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"}'

27、4. 输出参数

同 文生视频 输出参数。

28、5. 响应示例

{ "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d", "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"}

29、6. 错误码

请求失败时返回错误码，具体错误码及处理建议见 附录：统一错误码。任务状态说明同 文生视频。

31、1. 接口描述

各生成接口共用的任务查询方式：提交任务返回 task_id 后，通过统一的任务查询端点轮询任务状态，成功后从结果中获取视频地址。

接口： GET https://tokenhub.tencentmaas.com/v1/wand/minimax-video/tasks/{task_id}

接口： GET https://tokenhub.tencentmaas.com/v1/wand/minimax-video-v2/tasks/{task_id}

注意：说明：

注意：路径中的 {task_id} 即提交任务时返回的 task_id（示例中以 YOUR_TASK_ID 占位）。视频生成约需 1~3 分钟，建议每 3~5 秒轮询一次。

32、2. 输入参数

33、3. 请求示例

模型：minimax-video-v2.3

curl -X GET 'https://tokenhub.tencentmaas.com/v1/wand/minimax-video/tasks/YOUR_TASK_ID' \\ -H 'Authorization: Bearer YOUR_API_KEY'

模型：minimax-video-h3

curl -X GET 'https://tokenhub.tencentmaas.com/v1/wand/minimax-video-v2/tasks/YOUR_TASK_ID' \\ -H 'Authorization: Bearer YOUR_API_KEY'

34、4. 输出参数

V1（minimax-video-v2.3 / v2.3-fast）：

注意：V1 查询的视频地址在 content.url（非顶层 url）；base_resp.status_code 恒为 0，任务成败以 status 为准，失败原因读 base_resp.status_msg。

V2（minimax-video-h3 / h3-max）：

注意：V2 查询响应为 task 对象，无 base_resp、无顶层 status；任务标识与状态在 task.id / task.status。

35、5. 响应示例

V1（minimax-video-v2.3）生成成功：

{ "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d", "status": "Success", "content": { "url": "https://aigc-video.cos.myqcloud.com/xxx/result.mp4" }, "video_width": 1366, "video_height": 768, "base_resp": { "status_code": 0, "status_msg": "success" }, "tokenhub_usage": { "total_tokens": 102655 }, "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"}

V2（minimax-video-h3 / h3-max）生成成功：

{ "task": { "id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d", "model": "MiniMax-H3-Max", "task_type": "generation", "modality": "video", "status": "succeeded", "created_at": 1772345678, "updated_at": 1772345810, "resolution": "768P", "duration": 5, "ratio": "16:9", "content": { "url": "https://aigc-video.cos.myqcloud.com/xxx/result.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"}

36、6. 错误码

请求级错误码见 附录：统一错误码。

38、统一错误码

39、运镜指令语法

v2.3 / v2.3-fast 支持在 prompt 中通过 [指令] 格式添加运镜指令（h3 使用自然语言描述即可）：

·左右移：[左移]、[右移]；左右摇：[左摇]、[右摇]；推拉：[推进]、[拉远]

·升降：[上升]、[下降]；上下摇：[上摇]、[下摇]；变焦：[变焦推近]、[变焦拉远]

·其他：[晃动]、[跟随]、[固定]

使用规则：

·组合运镜：同一组 [] 内的多个指令同时生效，如 [左摇,上升]，建议组合不超过 3 个。

·顺序运镜：prompt 中前后出现的指令依次生效，如 “…[推进]，然后…[拉远]”。

·自然语言：也支持自然语言描述运镜，但使用标准指令能获得更准确的响应。

40、素材通用约束

图片（v2.3 / v2.3-fast）：JPG / JPEG / PNG / WebP；< 20MB；短边 > 300px；宽高比 2:5 ~ 5:2；支持公网 URL 或 Base64 图片数据（Data URL 形式，如 data:image/jpeg;base64,…）。

图片（h3）：JPG / JPEG / PNG / WEBP / HEIC / HEIF；≤ 30MB；宽高 [256, 5760]px；宽高比 [0.4, 2.5]；首帧 ≤ 1、尾帧 ≤ 1、参考图 ≤ 9。

视频（h3 参考视频）：MP4 / MOV（H.264 / H.265，音频 AAC / MP3）；≤ 50MB；≤ 3 段；单段 2~15 秒、总时长 ≤ 15 秒；宽高 [256, 5760]px；宽高比 [0.4, 2.5]；帧率 [23.976, 60]。

音频（h3 参考音频）：WAV / MP3；≤ 15MB；≤ 3 段；单段 2~15 秒、总时长 ≤ 15 秒。

注意：h3 请求体总大小 ≤ 64MB，大文件请使用公网 URL，勿用 Base64。

42、1. 四款模型如何选择？

·通用场景、要强物理表现与指令遵循：minimax-video-v2.3（文生图生均可）。

·图生场景、速度与成本优先（批量创作最高可降 50% 成本）：minimax-video-v2.3-fast（仅图生）。

·要 2K 直出、多模态参考（参考图/视频/音频）、最长 15 秒：minimax-video-h3。

·要更快出片、成本更低，且不要求 2K（h3-max 最高仅 768P，不支持 2K）：minimax-video-h3-max。另支持 extra.prompt_expansion_mode 提示词扩写，h3 不支持该参数。

43、2. minimax-video-v2.3-fast 能用于文生视频吗？

不能。v2.3-fast 仅支持图生视频（首帧），文生视频请使用 minimax-video-v2.3 或 minimax-video-h3。

44、3. 时长和分辨率的组合有什么限制？

·v2.3 / v2.3-fast：768P 可选 6 或 10 秒，1080P 仅支持 6 秒。

·h3：时长 4~15 秒，768P / 2K 均可。

·h3-max：时长 5~15 秒（不支持 4 秒），仅 480P / 768P，不支持 2K。

45、4. 生成结果视频链接会过期吗？

会过期。生成结果为临时地址，有效期 12 小时，请在任务成功后及时下载视频文件并转存到自有存储，不要长期依赖该链接。