文章目录1.简介2.快速上手3.工作流介绍4.API 快速接入4.1 两步快速跑通4.2 实例探活4.3 使用 SDK 接入4.4 生产任务采用异步模式5. 性能与成本实测数据6. 常见问题及处理建议7. 扩展功能图生视频与参考生视频7.1 图生视频I2V7.2 参考生视频R2V7.3 三种模式模型对照1.简介MiniMax H3 是 MiniMax Hailuo 视频系列中的最新模型。它可生成最长 15 秒、24 FPS 的视频支持原生 32 kHz 立体声音频覆盖 11 种语言最高分辨率可达 2K。该模型由 33.1B 密集单流全能变压器omni transformer驱动并配备 Qwen3-VL-32B 文本编码器。服务支持三种生成模式均已适配 turbo 4 步加速和满血模型工作流文生视频一段文字直接出带音频的视频图生视频一张首帧图片驱动画面与运镜参考生视频最多 9 张参考图 3 段参考视频 3 段参考音频锁定角色形象、画风或音色三种模式的模型与用法差异见第 7 节。2.快速上手首先我们进入 https://console.suanli.cn/serverless/create 创建任务推荐选用内存较大的 5090 机器。选择 MiniMax-H3 预制镜像后发布任务集群有镜像缓存时 1~2分钟 任务即可启动成功任务启动成功后点击 8188 端口进入 comfyui webui 界面 选择对应工作流即可开始生成视频3.工作流介绍video_minimax_h3_t2v.json输入文字描述输出带原生音频的视频最长15秒/24FPS/最高2K。提示词可写镜头运动、场景内容、对白和音效模型同步生成画面和声音。支持多镜头剪辑标记、中文对白标签、屏幕文字渲染。采样器 res_multistep20步画质最高速度最慢。video_minimax_h3_t2v_turbo4step_zh.json功能与原版相同加载4步蒸馏LoRA SigmaShift噪声调度采样器改 euler、步数降到4步速度约5倍。日常使用推荐。不要在 turbo 档下手动加步数蒸馏LoRA按4步训练加步数不会提升画质只会更慢。video_minimax_h3_i2v.json上传一张起始图作为视频首帧配合文字描述驱动镜头运动和动态变化同步生成音频。LoadImage 选图后接到 first_frame 输入口尾帧引导接 last_frame可同时使用。输入图片长宽比尽量与生成分辨率一致。res_multistep20步。video_minimax_h3_i2v_turbo4step_zh.json功能与原版相同加载 fl2v turbo 4步LoRA SigmaShifteuler/4步速度约5倍。日常使用推荐。video_minimax_h3_r2v.json把参考图片、参考视频、参考音频融入生成锁定角色身份、画风、动作风格或音色。最多9张参考图 3段参考视频可各带音轨 3段独立音频。提示词里用Picture 1、Video 1、Audio 1标签引用素材标签序号对应输入口序号不是上传顺序。使用 ref2va 模型与 T2V/I2V 的 fl2va 不同不可混用res_multistep20步。video_minimax_h3_r2v_turbo4step_zh.json功能与原版相同加载 ref2v 专用4步LoRAv0.1勿与 fl2v 版混用 SigmaShifteuler/4步速度约5倍。ref_image_size 参数可选 match参考图缩放到生成分辨率快或 max保留最高2048px短边身份保真更强但慢。4.API 快速接入4.1 两步快速跑通第 1 步在共绩算力控制台开一台 GPU 实例镜像选预置 ComfyUI 0.31.0 和 MiniMax H3 全套模型的组合模型不用自己下载GPU 建议 RTX 5090 126GB 档。开通后会拿到两个地址形如deployment-xxxx-8188.550w.link和deployment-xxxx-3000.550w.link代码调用走子域名带 3000 的那个。第 2 步把下面的脚本整个复制存成quickstart.py换成你自己的实例地址运行。纯 Python 标准库不用 pip install也不用下载任何文件。# quickstart.py —— MiniMax H3 视频生成最小接入示例纯标准库Python 3.8# 用法: python quickstart.py 你的实例地址# 示例: python quickstart.py https://deployment-xxxx-3000.550w.linkimportjson,time,random,base64,os,sysimporturllib.request,urllib.error# 换成你自己的实例地址控制台里子域名带 3000 的那个BASE_URLsys.argv[1]iflen(sys.argv)1elsehttps://deployment-xxxx-3000.550w.linkPROMPT(A ginger cat stretches lazily on a windowsill, sunlight filtering through white sheer curtains onto its fur, macro close-up, shallow depth of field, warm and cozy)# MiniMax H3 文生视频工作流turbo 4 步加速 / 720p 横屏 / 5 秒# 改分辨率: 节点 6 的 width/height必须 32 的倍数如 1080p 竖屏 1088x1920# 改时长: 节点 6 的 length帧数124≈5s243≈10s362≈15s# 改画质: 删掉节点 15LoRA和节点 5SigmaShift节点 8 的 model 改接 [1, 0]、# steps 改 20、sampler_name 改 res_multistepcfg 保持 1.0 不变workflow{1:{class_type:UNETLoader,inputs:{unet_name:minimax_h3_fl2va_pruned_int8_convrot.safetensors,weight_dtype:default}},2:{class_type:CLIPLoader,inputs:{clip_name:qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors,type:minimax}},3:{class_type:VAELoader,inputs:{vae_name:minimax_h3_video_vae_fp16.safetensors}},4:{class_type:VAELoader,inputs:{vae_name:minimax_h3_audio_vae_fp32.safetensors}},15:{class_type:LoraLoaderModelOnly,inputs:{model:[1,0],lora_name:minimax_h3_fl2v_turbo_4step_v1.0_768p_comfyui_bf16.safetensors,strength_model:1.0}},5:{class_type:MiniMaxH3SigmaShift,inputs:{model:[15,0],shift_video:12.0,shift_audio:3.0}},6:{class_type:MiniMaxH3ImageToVideo,inputs:{clip:[2,0],vae:[3,0],prompt:PROMPT,width:1280,height:736,length:124}},7:{class_type:ConditioningZeroOut,inputs:{conditioning:[6,0]}},8:{class_type:KSampler,inputs:{seed:random.randint(0,2**32-1),steps:4,cfg:1.0,sampler_name:euler,scheduler:simple,model:[5,0],positive:[6,0],negative:[7,0],latent_image:[6,1],denoise:1.0}},9:{class_type:VAEDecode,inputs:{samples:[8,0],vae:[3,0]}},10:{class_type:VAEDecodeAudio,inputs:{samples:[8,0],vae:[4,0]}},13:{class_type:CreateVideo,inputs:{images:[9,0],fps:24.0,audio:[10,0]}},11:{class_type:SaveVideo,inputs:{video:[13,0],filename_prefix:quickstart,format:auto,codec:auto}},12:{class_type:SaveAudio,inputs:{audio:[10,0],filename_prefix:quickstart}},}defpost_json(url,payload,timeout600,retries8):POST JSON实例休眠唤醒期间返回 503自动重试bodyjson.dumps(payload).encode(utf-8)forattemptinrange(retries):try:requrllib.request.Request(url,databody,headers{Content-Type:application/json},methodPOST)withurllib.request.urlopen(req,timeouttimeout)asr:returnjson.loads(r.read())excepturllib.error.HTTPErrorase:ife.code503andattemptretries-1:time.sleep(3)continueraiseos.makedirs(output,exist_okTrue)print(生成中720p / 5 秒 / turbo 档热启动约 75 秒首次运行要等模型加载1 到 5 分钟...)resultpost_json(BASE_URL/prompt,{prompt:workflow})fori,iteminenumerate(result.get(images,[])):rawbase64.b64decode(item)ifraw[:4]bfLaC:extflac# 独立音轨成片 mp4 里已内嵌可忽略elifraw[4:8]bftyp:extmp4# 成片音轨已内嵌else:extbinpathos.path.join(output,quickstart_%d.%s%(i,ext))withopen(path,wb)asf:f.write(raw)print(已保存 %s (%.2f MB)%(path,len(raw)/1048576))热启动约 75 秒出片首次运行要等模型加载进显存1 到 5 分钟属于正常冷启动。跑完output/目录里出现一个 MP4音轨已内嵌直接播放和一个 FLAC独立音轨可忽略。想改分辨率、时长、画质脚本里的注释写了对应改哪里。这段脚本就是全部的接入代码直接复制走就能用。跑通后再往下看后面讲实例怎么开、SDK 怎么省掉手写参数、生产环境怎么换异步模式以及实测的性能和成本数据。4.2 实例探活如果需要验证服务就绪跑两条命令。curl-shttps://deployment-xxxx-3000.550w.link/health#{version:1.17.1,status:healthy}curl-shttps://deployment-xxxx-3000.550w.link/ready#{version:1.17.1,status:ready}/health热身完成后返回 200/ready在队列没满时返回 200队列满了会返回 503。生产环境探活建议两个都查。4.3 使用 SDK 接入在快速开始示例中手写工作流 JSON 时需要手动将宽高调整为 32 的倍数、并将帧数换算至符合17k5网格的合法值操作繁琐且易出错。为此我们提供了一个纯标准库实现的 Python SDK无需安装任何第三方依赖Python 3.8 直接导入使用可从文末仓库下载comfyui_minimax_h3_sdk.py并放入项目目录即可使用。SDK 内部自动处理宽高补齐、帧数网格映射等模型约束上层调用仅需关心语义化参数。使用 SDK 重写快速开始中的视频生成任务代码如下fromcomfyui_minimax_h3_sdkimportgenerate_video filesgenerate_video(A cat playing piano in a jazz club,base_urlhttps://deployment-xxxx-3000.550w.link,resolution1080p,# 480p / 720p / 1080p / 768paspect9:16,# 16:9 / 9:16 / 4:3 / 1:1duration10,# 秒数SDK 自动换算成合法帧数qualityturbo,# turbo默认快 5 倍/ standard20 步原版)quality参数作为一项综合开关会自动调整三组配置turbo加载 4 步蒸馏 LoRA采样步数设为 4CFG 设为 1.0standard移除 LoRA采样步数恢复为 20CFG 恢复为 7.0。如需更高画质应切换quality档位而非在 turbo 模式下人为增加步数。因为蒸馏 LoRA 已重新训练了去噪轨迹使其适应 4 步生成额外增加步数不会提升画质只会延长等待时间。SDK 内置了针对 503 状态码的重试机制可自动处理实例休眠唤醒期间的临时抖动。同步调用上述generate_video函数在热启动状态下例如 720p/5s/turbo约等待 75 秒即可获得本地落盘的 MP4 和 FLAC 文件。注意若连续两次提交完全相同的参数包括种子、提示词、尺寸第二次请求可能在 23 秒内立即返回。这是因为 ComfyUI 的执行缓存命中了先前的结果并未触发重新生成。因此进行性能基准测试时请务必更换种子seed避免缓存数据干扰实测结果。若需要绕过 SDK 直接通过 HTTP 接口接入例如使用非 Python 语言完整的工作流 JSON 结构、所有端点和参数说明均可在仓库的 API 文档中查阅。该 JSON 即为 SDK 每次组装并提交给服务端的标准内容。SDK 源代码及文档地址https://github.com/shaozheng0503/minimax-h3-video-api4.4 生产任务采用异步模式同步请求方式下客户端连接会持续保持直至请求完成。根据网关实测连接超时阈值约为 193 秒因此同步模式仅适用于生成耗时在此范围内的任务。参考性能数据480p 全档及 720p/5s 任务均在安全区内720p/10s 任务耗时约 168 秒虽接近上限但仍可尝试而 1080p 或 15 秒时长的视频生成耗时可达 25 分钟远超同步连接可维持的时间一旦客户端超时断开即便服务端仍在处理结果亦无法正常回收。针对生产环境应采用异步提交模式。调用时需额外提供webhook_v2参数服务端收到请求后立即返回 HTTP 202 状态码及任务 ID待生成完成后服务端将主动通过 HTTP POST 回调用户指定的接口。fromcomfyui_minimax_h3_sdkimportComfyUI,build_t2v_workflow clientComfyUI(https://deployment-xxxx-3000.550w.link)workflowbuild_t2v_workflow(prompt_textA cat playing piano,resolution720p,duration5,)resultclient.async_submit(workflow,webhook_urlhttps://your-server.com/callback,task_idmy-task-001,)print(任务已提交:,result[id])回调消息体分为两种类型成功时事件为prompt.complete内容包含 Base64 编码的视频、音频数据以及耗时统计信息失败时为prompt.failed附带错误详情。若回调请求失败如目标地址不可达服务端将自动重试最多 3 次因此回调接口需设计为幂等处理确保同一任务多次回调不产生副作用。若服务端配置了WEBHOOK_SECRET环境变量回调请求将附带符合 Standard Webhooks 规范的 HMAC 签名。SDK 内置verify_webhook(body, headers, secret)验签函数纯标准库实现验证失败时将抛出异常便于在生产环境中安全校验回调来源。此外需注意两项生产约束单个实例同时只处理一个任务多个任务将自动排队。如需并行处理应部署多个实例多 GPU 实例如双 5090可显著提升吞吐量但单任务执行速度与单卡实例一致不会因卡数增加而加速。请求体大小默认上限为 100 MB若采用图生视频模式并需上传大尺寸图片请确保输入数据不超出此限制。5. 性能与成本实测数据使用4步lora工作流测试不同分辨率时长下生成时间如下表分辨率5s10s15s480p~38s~65s~117s720p~75s~168s~375s1080p~228s~584s~1472s费用估算以 RTX 5090 按卡时计费 3.25 元、秒级结算为标准720p/5s 视频生成耗时 75 秒约 0.07 元/条480p/5s 视频生成耗时 38 秒约 0.03 元/条1080p/15s 视频生成耗时 1472 秒约 1.3 元/条。6. 常见问题及处理建议503 状态码频繁出现实例休眠或扩缩容期间返回 503 属于正常行为。客户端应实现自动重试机制间隔数秒重试通常 23 次内即可成功。首条请求响应缓慢冷启动需将模型加载至显存耗时约 15 分钟。生产环境中可在服务就绪后先提交一个 480p、2 秒的最小任务进行预热使模型常驻显存后续正式任务可避免冷启动延迟。第二次请求响应异常迅速前述执行缓存机制导致若前后两次提交的 seed 及全部参数完全一致第二次将直接命中缓存23 秒内返回。测试及生产环境中均需注意每次更换 seed避免缓存结果干扰性能评估或业务逻辑。同步模式下长任务无法获取结果网关同步连接超时阈值实测约为 193 秒。超出此量级的任务应切换至异步模式不应通过调大客户端超时参数强行维持同步连接。已提交的任务从队列中消失弹性实例在休眠唤醒或自动重启时会清空执行队列与 history已排队未执行的任务会直接丢失客户端表现为提交成功但长时间无结果。建议关键任务使用异步模式回调驱动便于发现丢失并重提轮询模式下若发现任务 ID 从/history消失且队列为空应立即重提而非继续等待。另外实例重启也会清空已上传的输入图片——图生视频/参考生视频遇到Invalid image file报错时重新上传图片再提交即可。7. 扩展功能图生视频与参考生视频除文生视频外本服务还支持图生视频I2V与参考生视频R2V两种模式均已完成适配。7.1 图生视频I2V传入一张首帧图片可选尾帧模型以该图为视频起点按提示词驱动镜头运动、画面变化与音频。接入三步上传图片POST到 8188 端口的/upload/imagemultipart/form-data字段名image返回{name: xxx.png, subfolder: , type: input}工作流中LoadImage节点的image参数填上传返回的文件名将LoadImage的 IMAGE 输出接到MiniMaxH3ImageToVideo节点的first_frame输入口尾帧引导接last_frame其余模型链与文生视频完全一致。注意事项输入图片长宽比尽量与生成分辨率一致否则首帧会被裁切或拉伸请求体上限 100MB见 4.4 节超大图片先压缩再上传实例重启后已上传图片会丢失遇到图片校验失败重新上传即可见第 6 节。7.2 参考生视频R2V支持最多 9 张参考图、3 段参考视频可各带音轨、3 段独立参考音频模型将参考素材融入生成用于锁定角色形象、画风、动作风格或音色。与文生/图生视频的两个关键差异模型不同R2V 使用专用主模型minimax_h3_ref2va_pruned_int8_convrot.safetensors和专用加速 LoRAminimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors注意当前版本为 v0.1不能与 fl2v 那套混用提示词必须用标签引用参考素材按参考输入的连接顺序写Picture 1、Video 1、Audio 1——标签序号对应素材接入的输入口序号而不是上传先后顺序。ref_image_size参数match默认参考图缩放到生成分辨率速度快max参考图保留最高 2048px 短边身份与风格保真更强但参考 token 参与每一步采样耗时明显增加。实测turbo 档、RTX 50900.3MP736×416/ 5 秒 / 2 张参考图约 104 秒含模型冷加载音频输出正常。standard 档下参考素材较多时beta或normal调度器通常比simple效果更好。7.3 三种模式模型对照模式主模型加速 LoRA核心节点文生视频 T2Vfl2vafl2v_turbo_4step v1.0MiniMaxH3ImageToVideo不接首尾帧图生视频 I2Vfl2vafl2v_turbo_4step v1.0MiniMaxH3ImageToVideo接 first_frame / last_frame参考生视频 R2Vref2varef2v_turbo_4step v0.1MiniMaxH3ReferenceToVideo提示词编写可参考 MiniMax 官方结构化格式支持多镜头剪辑标记、中文对白标签及屏幕文字渲染上述功能均已实测可用。完整 API 文档、SDK 源码、27 个基准测试用例原始数据及全部生成视频均存放于以下仓库https://github.com/shaozheng0503/minimax-h3-video-api