共绩科技
共绩科技

预制服务

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 接 24
  • 20-24 采样链:4 步 euler,CFG 隐含 1.0(BasicGuider 只接 positive 就是 CFG=1);BasicScheduler 必须带 denoise: 1.0,缺了提交报 400
  • 30-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%):

分辨率5s10s15s
480p38s65s117s
720p75s168s375s
768p81~138s243s452s(接近显存边界,慎用)

(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_namefl2vaminimax_h3_ref2va_pruned_int8_convrot.safetensors
11 lora_namefl2v_turbo…v1.0minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors
16 class_typeMiniMaxH3ImageToVideoMiniMaxH3ReferenceToVideo

节点 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/filemultipart 直传视频提交超分
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” / 缺 file422 + 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 errorpayload 结构错 / 客户端重编码 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 生成 OOM32G 卡放不下 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 后退出部署后冒烟验证(一次性容器)

C. 相关链接