预制服务
minimax-h3 turbo + RTX VSR 合并镜像使用说明
这个镜像做什么:一个容器里同时跑两个服务——MiniMax H3 视频生成(ComfyUI,端口 8188)和 AI 超分(RTX VSR,端口 8001)。单张 RTX 5090 从一句提示词到 2K 带音轨成片,全程不用换机器、不用传文件。
它适合谁:
| 你的情况 | 推荐路径 |
|---|---|
| 不想租卡、不想运维,直接调用生成接口 | 共绩 MaaS 大模型云服务正在内测 MiniMax H3 托管版——按量计费。内测期间联系客服对接销售即可开通 |
| 想要”一句话出片”,让 Agent 替你管租卡/生成/关机 | 开源 Agent Skill suanli-h3-video:npx skills add shaozheng0503/suanli-h3-video --skill suanli-h3-video,装好后对 AI 助手说「用 suanli-h3-video 生成一条 768p 5 秒视频:……」,四种模式真机验证、跑完自动关机 |
| 想把生成能力嵌进自己的代码 / 产品 | 本文档就是为你写的——往下读 |
阅读提示:只想先跑通一条,看第一节(6 步,约 10 分钟);要上生产,务必再看第三节的三个避坑要点(内存档位 / 计费 / 关机);完整的接口细节在第四、五节按需查阅。
本文档的全部命令与工作流已真机验证过端到端(部署 → 生成 155s → 超分 31.5s → 2K 2688×1536 → 关机),可放心照抄。
一、快速开始:6 步跑通全链路
前置:已按第二节部署实例,拿到两个公网地址(下文 $COMFY = 8188 域名,$VSR = 8001 域名)。
Step 1 — 确认两个服务都活着
curl -s $COMFY/system_stats # 返回 200 + JSON 即活(ComfyUI 没有 /health 端点)
curl -s $VSR/healthz # {"status":"ok","service":"rtxvsr",...}
刚启动 1~3 分钟内 ComfyUI 可能拒绝连接(模型链加载中),等 30 秒重试即可。
Step 2 — 提交一条生成任务(768p / 5 秒 / 4 步 turbo)
# 完整 workflow JSON 见第四节(可直接复制),此处示意提交方式:
curl -s -X POST $COMFY/prompt \
-H "Content-Type: application/json" \
-d '{"prompt": {…workflow…}, "client_id": "my-app-1"}'
# → {"prompt_id": "7498f8fe-…", "number": 1, "node_errors": {}}
⚠️ 返回的 node_errors 非空说明工作流本身有错、任务根本没入队——最常见的三个原因:帧数不在合法网格(见 4.4)、模型文件名抄错、BasicScheduler 缺 denoise: 1.0。
Step 3 — 等生成完成,下载 768p 成片
768p / 5 秒约 85~140 秒(冷启动取上限)。轮询到 "success" 后下载:
curl -s $COMFY/history/7498f8fe-… | jq '.[].status.status_str' # "success"
# 从 outputs 里拿 filename,然后:
curl -s -o h3_raw.mp4 "$COMFY/view?filename=<文件名>&subfolder=&type=output"
产物自带音轨(H3 音画一体,提示词里写 Audio: ... 才有声音)。
Step 4 — 提交超分任务(768p → 2K,即 2688×1536)
curl -s -X POST $VSR/api/v1/upscale/file \
-F "file=@h3_raw.mp4" -F "scale=2.0" -F "quality=HIGH" \
-F "vcodec=libx264"
# → {"task_id":"d1247542e667","status":"queued","poll":"/api/v1/tasks/…"}
⚠️ 共绩平台必须 vcodec=libx264(节点 NVENC 不可用,报 OpenEncodeSessionEx failed;本地自建机器可以用默认的 h264_nvenc)。
Step 5 — 等超分完成,下载 2K 成片
超分很快(HIGH 档约 10 秒 + 编码时间):
curl -s $VSR/api/v1/tasks/d1247542e667 # {"status":"done","meta":{"total_s":30.9,…}}
curl -s -o h3_2k.mp4 $VSR/api/v1/tasks/d1247542e667/result
⚠️ /result 返回的是 mp4 二进制流(带 Content-Disposition 头),不是 JSON——直接当文件下载,别用 jq 解析。音轨原样保留。
Step 6 — 暂停实例,停止计费
平台按秒计费,实例开着就扣费。 跑完务必暂停:
curl -s -X POST "https://openapi.suanli.cn/api/deployment/task/pause" \
-H "token: <你的API密钥>" -H "version: 1.0.0" -H "timestamp: <毫秒时间戳>" \
-H "Content-Type: application/json" \
-d '{"task_id": <你的任务ID>}'
下次要用时调 /api/deployment/task/recover 恢复(重新调度 + 冷启动,域名不变)。
二、部署
2.1 控制台部署(推荐新手)
在 共绩控制台 新增部署任务:服务配置选择本镜像(h3vsr-merge),GPU 选 RTX 5090,端口暴露 8188 与 8001。
⚠️ 选机型时盯一眼宿主内存:同为”5090”档位,宿主内存从 58GB 到 500GB+ 不等。本镜像的权重在显存和内存之间换页,跑批量任务请选 ≥128GB 的档位——58GB 档连发长队列会触发 OOMKilled(实测单实例连跑 90 条会被杀)。偶尔跑单条无碍。
2.2 Open API 部署(适合自动化)
① 查资源拿 mark(mark 是资源标识,随库存变动,每次部署前查):
curl -s "https://openapi.suanli.cn/api/deployment/resource/search" \
-H "token: <你的API密钥>" -H "version: 1.0.0" -H "timestamp: <毫秒时间戳>"
# 找 "device_name":"5090" 且 inventory>0 的条目,核 memory ≥ 128GB
# ⚠️ 注意嵌套:regions[k].mark 是一个对象,payload 里 "mark" 字段要填的是
# 它内部的 regions[k].mark.mark(一长串 base64 字符串),resource 对象用
# regions[k].mark.resource —— 直接把外层对象填进去会报 invalid type: map
② 创建任务(注意 env 是字符串,多行用 \n 分隔):
curl -s -X POST "https://openapi.suanli.cn/api/deployment/task/create" \
-H "token: <密钥>" -H "version: 1.0.0" -H "timestamp: <毫秒时间戳>" \
-H "Content-Type: application/json" --data-binary @payload.json
payload.json:
{
"task_name": "h3vsr_merge_014",
"points": 1,
"resources": [{
"mark": "<第①步查到的mark>",
"resource": {"device_name": "5090", "region": "<查到的region>", "gpu_name": "5090",
"gpu_count": 1, "gpu_memory": 32600, "memory": 64512, "cpu_cores": 16},
"region_name": null,
"weight": null
}],
"services": [{
"service_name": "container-01",
"service_image": "harbor.suanleme.cn/public-hub/h3vsr-merge:0.1.4-5090",
"env": "NVIDIA_DRIVER_CAPABILITIES=compute,utility,video",
"remote_ports": [{"service_port": 8188}, {"service_port": 8001}]
}]
}
③ 轮询到 Running,拿公网地址:
curl -s "https://openapi.suanli.cn/api/deployment/task/search?page=1&page_size=5" \
-H "token: …" -H "version: 1.0.0" -H "timestamp: …"
# data.results[].status == "Running",其 remote_ports[].url 即两个公网地址
# (形如 https://deployment-452-xxxx-8188.550w.link 与 …-8001.550w.link)
2.3 计费要点
- 按秒计费,1 元 = 1,000,000 点;5090 单卡约 ¥3.25/时(不同区域档位略有差异)
- 每次冷启动(创建/恢复实例)有 1~3 分钟模型加载时间,也计费——攒够一批任务再开实例更划算
- 任务全部结束就暂停(Step 6),别挂着过夜
三、上生产前必读:三个高频翻车点
这三条都来自真实压测,篇幅不长但每条都能省你几小时排查时间。
① 生成和超分不能同时跑(同卡显存叠加必 OOM)
生成峰值 ~27.8GB + 超分峰值 ~10.5GB > 32GB 显存。先生成完一批,再统一超分——两个服务在同一个镜像里不代表能并行用。
② 批量任务要换 seed,否则拿到的是旧片
ComfyUI 有执行缓存:完全相同的参数 + seed,第二次提交 2~3 秒就返回上一次的结果。批量跑每条换随机 seed(改 noise_seed)。
③ 帧数不合法不报错,而是静默取整length 必须落在 17k+5 网格(5s=124 / 10s=243 / 15s=362)。提交 245 这种非法值不会报错,节点会静默向上取整成 260 帧——多花时间、质量还下降。参数约束全表见 4.4。
四、服务 A:H3 生成(端口 8188)
4.1 三种生成模式
| 模式 | 输入 | 核心区别 | 实测耗时(768p/5s) |
|---|---|---|---|
| T2V 文生 | 一句提示词 | 基础模式 | ~85s 热态 |
| I2V 图生 | 一张首帧图 | 工作流加一个 LoadImage 节点接到 first_frame | ~112s(含传图) |
| R2V 参考生 | 最多 9 张参考图 | 换 ref2va 模型链(见 4.6),<Picture N> 引用 | ~122s |
4.2 T2V 工作流(权威版,可直接复制)
这是实测跑通的 turbo 4-step 工作流。为什么是这五个采样节点:H3 的 turbo LoRA 要求 CFG=1.0,此时不需要 negative 分支,用 SamplerCustomAdvanced 五节点链替代普通 KSampler——这套是官方 turbo 工作流的原版结构,参数语义最清晰。
{
"10": {"class_type": "UNETLoader", "inputs": {
"unet_name": "minimax_h3_fl2va_pruned_int8_convrot.safetensors",
"weight_dtype": "default"}},
"11": {"class_type": "LoraLoaderModelOnly", "inputs": {
"model": ["10", 0],
"lora_name": "minimax_h3_fl2v_turbo_4step_v1.0_768p_comfyui_bf16.safetensors",
"strength_model": 1.0}},
"12": {"class_type": "MiniMaxH3SigmaShift", "inputs": {
"model": ["11", 0], "shift_video": 12.0, "shift_audio": 3.0}},
"13": {"class_type": "CLIPLoader", "inputs": {
"clip_name": "qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors",
"type": "minimax", "device": "default"}},
"14": {"class_type": "VAELoader", "inputs": {"vae_name": "minimax_h3_video_vae_fp16.safetensors"}},
"15": {"class_type": "VAELoader", "inputs": {"vae_name": "minimax_h3_audio_vae_fp32.safetensors"}},
"16": {"class_type": "MiniMaxH3ImageToVideo", "inputs": {
"clip": ["13", 0], "vae": ["14", 0],
"prompt": "Cinematic anime style, a red sports car drifting through a neon-lit Tokyo street at night, rain-slick asphalt reflections, motion blur. Audio: engine roar, tire screech.",
"width": 1344, "height": 768, "length": 124}},
"20": {"class_type": "RandomNoise", "inputs": {"noise_seed": 123456}},
"21": {"class_type": "BasicGuider", "inputs": {"model": ["12", 0], "conditioning": ["16", 0]}},
"22": {"class_type": "KSamplerSelect", "inputs": {"sampler_name": "euler"}},
"23": {"class_type": "BasicScheduler", "inputs": {
"model": ["12", 0], "scheduler": "simple", "steps": 4, "denoise": 1.0}},
"24": {"class_type": "SamplerCustomAdvanced", "inputs": {
"noise": ["20", 0], "guider": ["21", 0], "sampler": ["22", 0],
"sigmas": ["23", 0], "latent_image": ["16", 1]}},
"30": {"class_type": "VAEDecode", "inputs": {"samples": ["24", 0], "vae": ["14", 0]}},
"31": {"class_type": "VAEDecodeAudio", "inputs": {"samples": ["24", 0], "vae": ["15", 0]}},
"32": {"class_type": "CreateVideo", "inputs": {"images": ["30", 0], "audio": ["31", 0], "fps": 24.0}},
"33": {"class_type": "SaveVideo", "inputs": {
"video": ["32", 0], "filename_prefix": "H3VSR", "format": "auto", "codec": "auto"}}
}
节点速读:
10-15加载器链:DiT(int8) → turbo LoRA → sigma shift(turbo 专用,shift 参数勿动)→ 文本编码器 → 双 VAE(视频/音频分开)16生成参数全在这里(见 4.4 参数表);它输出两个值:conditioning 接 21、latent 接 2420-24采样链:4 步 euler,CFG 隐含 1.0(BasicGuider 只接 positive 就是 CFG=1);BasicScheduler必须带denoise: 1.0,缺了提交报 40030-33解码成片:视频/音频分别解码 → 合成 mp4(fps=24,H3 原生帧率)
4.3 提交、轮询、下载(接口速查)
POST /prompt body: {"prompt": <workflow>, "client_id": "<任意ID>"}
→ {"prompt_id": "...", "node_errors": {}} # node_errors 非空=没入队
GET /history/{prompt_id}
→ status.status_str: "success" / "error" # error 详情看 status.messages.execution_error
GET /view?filename=<名>&subfolder=<子目录>&type=output → 文件流
POST /upload/image multipart,字段名 image(I2V 首帧 / R2V 参考图上传)
图片上传注意:客户端超时设 ≥600s(35MB 大图用默认 120s 会超时);实例重启会清空已上传图片,届时需重新上传。
4.4 生成参数表
| 参数 | 含义 | 可选值与约束 |
|---|---|---|
width/height | 分辨率 | 必须 32 的倍数:864×480(480p)/ 1280×720(720p)/ 1344×768(768p,推荐) / 1920×1080(1080p——32G 卡跑 10s/15s 会 OOM,用 768p+超分替代) |
length | 帧数(24fps) | 必须落在 17k+5 网格:5s=124、10s=243、15s=362。校验式 (length-5) % 17 == 0 且 124 ≤ length ≤ 362 |
prompt | 提示词 | 画面和声音一起写(Audio: … 后接环境音/对白),H3 生成同步音频 |
两个”不是 bug”的现象,先知道免得排查:
- 产物帧数 = 请求 +3(H3 帧数补偿):请求 124 实际 127 帧,正常
- 相同参数秒回旧结果:执行缓存命中,换 seed 即可
性能基准(5090 单卡 turbo 4-step,实测 P50;不同区域/机型档位 ±10%):
| 分辨率 | 5s | 10s | 15s |
|---|---|---|---|
| 480p | 38s | 65s | 117s |
| 720p | 75s | 168s | 375s |
| 768p | 81~138s | 243s | 452s(接近显存边界,慎用) |
(768p/5s 区间:本地热态 80.1s / 本地冷启动 110.2s / 共绩远程冷启动 138.2s。天津一区 16 核机型比新疆一区 12 核快约 11%——权重换页是 CPU 密集操作)
4.5 I2V 图生视频(改动最小)
在 T2V 工作流上加两个节点:
"201": {"class_type": "LoadImage", "inputs": {"image": "<上传后的文件名>"}},
并把节点 16 的输入加一条:"first_frame": ["201", 0]。其余全部不变(模型、LoRA、采样链同 T2V)。
先 POST /upload/image 传图拿文件名,再提交工作流。输入图长宽比尽量与生成分辨率一致,否则首帧会被裁切或拉伸。
4.6 R2V 参考生视频(换模型链)
T2V 换三处,其余不变:
| 节点 | T2V(默认) | R2V |
|---|---|---|
| 10 unet_name | fl2va | minimax_h3_ref2va_pruned_int8_convrot.safetensors |
| 11 lora_name | fl2v_turbo…v1.0 | minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors |
| 16 class_type | MiniMaxH3ImageToVideo | MiniMaxH3ReferenceToVideo |
节点 16 的 inputs 额外必填三项:
"audio_vae": ["15", 0],
"ref_images": [["201", 0], ["202", 0]],
"ref_image_size": "match"
ref_images是列表(写成ref_image_1会报 TypeError);ref_image_size必填(缺了 400):match(缩放到生成分辨率,快)/max(保留最高 2048px 短边,身份保真更强但慢)- 提示词用
<Picture 1>、<Picture 2>引用参考图(序号 = LoadImage 接入顺序,不是上传顺序) - fl2va ↔ ref2va 模型切换有 ~124s 冷加载——尽量按模型分组批量跑,别来回切
五、服务 B:VSR 视频超分(端口 8001)
交互式 API 文档:部署地址 + /docs(FastAPI 自带 Swagger,参数可以直接在线试)。
5.1 接口速查
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /healthz | 健康检查 |
| POST | /api/v1/upscale/file | multipart 直传视频提交超分 |
| GET | /api/v1/tasks/{id} | 轮询状态(queued → running → done/error) |
| GET | /api/v1/tasks/{id}/result | 下载 2K 产物(mp4 流,不是 JSON) |
5.2 提交参数
curl -X POST $VSR/api/v1/upscale/file \
-F "file=@input.mp4" \
-F "scale=2.0" \
-F "quality=HIGH" \
-F "vcodec=libx264" \
-F "bitrate=50M"
| 参数 | 说明 |
|---|---|
file | 输入视频(mp4/h264 最佳;带音轨会原样保留) |
scale | 放大倍数,支持小数(1.5 实测可用);768p→2K 用 2.0 |
quality | 见下表 |
vcodec | 共绩平台必须 libx264(NVENC 不可用);本地自建可用 h264_nvenc |
bitrate | 输出码率,2K 建议 50M |
quality 档位:
| 值 | 速度 | 用途 |
|---|---|---|
| BICUBIC | 最快 | 不跑模型,纯插值(自检用) |
| LOW / MEDIUM | 快 | 预览 |
| HIGH | 中 | 768p AI 生成源推荐 |
| ULTRA | 略慢 | 与 HIGH 差距很小(13.5s vs 10.1s),可选 |
| HIGHBITRATE_* | - | 高码率源专用 |
轮询响应(done 时):
{"task_id":"…","status":"done","progress":1.0,"error":null,
"meta":{"total_s":30.9,"size_mb":54.3,"quality":"HIGH","scale":2.0}}
5.3 错误行为(实测)
| 请求 | 响应 |
|---|---|
| scale=“abc” / 缺 file | 422 + detail 校验详情 |
| quality=“NOT_A_LEVEL” | ⚠️ 异步暴露:提交时返回 200 queued,轮询时才变 error——不要指望提交时被拦住 |
| task_id 不存在 | 404 |
5.4 并发
/healthz 显示 concurrency.max=3,但同卡 both 模式下实际安全并发 = 1(且仅在生成空闲时)——显存叠加约束(见第三节①)。queue_visible 只是「已提交未开始」数,别当队列深度监控用。
六、推荐客户端:suanli-h3-video(开源、纯标准库)
不想从零写集成代码的话,suanli-h3-video 的批量执行器 h3_batch.py 覆盖本镜像全部链路,零第三方依赖:
git clone https://github.com/shaozheng0503/suanli-h3-video.git
# 单条生成
python3 scripts/h3_batch.py submit --comfy $COMFY \
--prompt "A ginger cat stretches on a sunny windowsill. Audio: soft purring" \
--resolution 768p --duration 5
# 批量(自动随机 seed 防缓存 + 任务间隔防 OOM)
python3 scripts/h3_batch.py submit --comfy $COMFY --prompt-file tasks.txt --count 8
# 断点续跑(中断后重跑,已完成任务自动跳过)
python3 scripts/h3_batch.py submit --comfy $COMFY --job jobs/<ts>/ …
# 失败重试(只重试 timeout/网络错误,参数错误不会浪费时间重试)
python3 scripts/h3_batch.py retry --comfy $COMFY --job jobs/<ts>/ --only task003
# 批量 2K 超分(先跑完生成批,再执行这个)
python3 scripts/h3_batch.py upscale --vsr $VSR --job jobs/<ts>/ --scale 2.0 --quality HIGH
# 收尾:生成 manifest 清单 + 自动暂停实例
python3 scripts/h3_batch.py done --job jobs/<ts>/ --task-id <任务ID>
相比手写脚本,它把本文档提到的坑全部代码化:探活重试、帧数网格校验、防缓存 seed、生成/超分严格串行、8 秒任务间隔(防宿主内存累积)、原子下载(半截文件不会混进交付)。全部行为有 28 项回归测试守护;需要嵌入自己代码时,仓库 skill/api/ 有四个接口的完整参考文档。
七、故障排查速查表
按”你看到什么”组织,从上往下找:
| 症状 | 原因 | 解法 |
|---|---|---|
部署返回 C001 body is error | payload 结构错 / 客户端重编码 null | 按 2.2 模板;curl 用 --data-binary @file |
部署返回 A001 must need token… | header 缺失或时间戳过期 | token/version/timestamp 三件套每次现取 |
部署返回 A002 no permission | 端点拼写错或 key 无此接口权限 | 核对是 /api/deployment/task/create(语序别反) |
提交即 node_errors 非空 | 工作流参数错 | 最常见三个:length 不在网格、模型文件名抄错(comfyui_bf16 后缀勿截断)、BasicScheduler 缺 denoise: 1.0 |
| R2V 提交 400 required_input_missing | 缺 ref_image_size | 补 "ref_image_size": "match"(4.6) |
| 生成秒回但结果是旧片 | 执行缓存命中(同 seed) | 每条随机 seed |
| 生成中提交超分 → OOM | 同卡显存叠加(27.8+10.5>32G) | 严格串行:生成完再超分 |
| 批量长跑容器被杀(Exit 137 / OOMKilled) | 宿主内存档位太小 | 换 ≥128GB 档位(2.1);或减少连发、任务间留间隔 |
| 实例重启后任务消失 | 重启清空队列与 history | 断点续跑(第六节);i2v/r2v 需重新上传图片 |
| 视频没有声音 | 提示词没写音轨 | 补 Audio: …(H3 音画一体,不写可能静音) |
| 产物帧数比请求多 3 帧 | H3 帧数补偿 | 正常,不是 bug |
VSR 报 OpenEncodeSessionEx failed | 平台节点 NVENC 不可用 | vcodec=libx264(共绩);本地不受影响 |
| VSR 任务一直 pending | 用了 JSON 模式(video_url 拉取卡死) | 一律用 multipart /api/v1/upscale/file |
| quality 非法但提交时没报错 | 校验在 worker 层,异步暴露 | 轮询 status==error 看 error 字段 |
/result 下载后打不开 / jq 报错 | 它是 mp4 二进制流不是 JSON | 直接 curl -o 当文件存 |
| 1080p 生成 OOM | 32G 卡放不下 1080p 长片 | 用 768p 生成 + VSR 2K 超分替代(效果更好且更稳) |
附录
A. 内置模型清单
/comfyui/ComfyUI/models/diffusion_models/
minimax_h3_fl2va_pruned_int8_convrot.safetensors # T2V/I2V DiT (int8, ~21GB)
minimax_h3_ref2va_pruned_int8_convrot.safetensors # R2V DiT (int8, ~21GB)
/comfyui/ComfyUI/models/loras/
minimax_h3_fl2v_turbo_4step_v1.0_768p_comfyui_bf16.safetensors
minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors
/comfyui/ComfyUI/models/vae/
minimax_h3_video_vae_fp16.safetensors # 视频 VAE
minimax_h3_audio_vae_fp32.safetensors # 音频 VAE
/comfyui/ComfyUI/models/clip/
qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors # 文本编码器 (nvfp4, ~15.7GB)
B. 启动模式(进阶)
镜像 ENTRYPOINT 为 /entrypoint-merge.sh,CMD 可选:
| 模式 | 行为 | 什么时候用 |
|---|---|---|
both(默认) | ComfyUI(8188) + VSR(8001) 双进程 | 一体机(注意显存叠加) |
comfyui | 仅 ComfyUI | 纯生成节点 |
vsr | 仅 VSR API | 纯超分节点(可部署在便宜机器上) |
selftest | 依次自检 cupy→nvvfx→VSR→NVENC 后退出 | 部署后冒烟验证(一次性容器) |