预制服务
用 Agent Skills 跑 MiniMax H3：一句话生成视频，跑完自动关机
适用镜像：h3vsr-merge:0.1.4-5090（预制镜像：MiniMax H3 生成 8188 + RTX VSR 超分 8001）
适用人群：想在共绩算力上批量生成视频的开发者、内容创作者、工作室
预期效果：一句自然语言 → Agent 自动租卡、生成、超分、下载、关机。768p / 5 秒成片约 ¥0.08，2K 约 ¥0.09
MiniMax H3 是当前开源生态里少有的「音画一体」视频模型：写画面、写镜头、写台词、写 BGM，一条提示词直接生成带完整音轨的视频。配合共绩的 h3vsr-merge 预制镜像，单张 5090 就能跑通「768p 生成 → 2K 超分」全链路。
但跑过的人都知道，从「模型能跑」到「稳定量产」之间还隔着不少活：租卡、轮询、下载、重试、防缓存、显存调度、用完关机……每一步都要人盯着。
suanli-h3-video 这个开源 Agent Skill 把这些全部封装掉了。它遵循 共绩 Agent Skills 规范，装进 Cursor、Claude Code 等任意支持 Skills 约定的 AI 助手后，你对它说一句话，剩下的全自动。
这篇文章分两部分：第一部分给人看——它能做什么、效果如何、怎么开始；第二部分给 Agent 看——装好之后 AI 是按什么流程干活的（也可以当作你自己写集成代码的参考）。
第一部分：给人看
它能做什么
| 模式 | 你给什么 | 产出 | 实测耗时 |
|---|---|---|---|
| 文生视频 T2V | 一句话描述画面 + 声音 | 带音频成片 | ~85s / 条（768p/5s 热态） |
| 图生视频 I2V | 一张首帧图 | 以图为起点驱动运镜与动态 | ~112s / 条 |
| 参考生视频 R2V | 最多 9 张角色/产品图 | 锁定形象生成新场景 | ~122s / 条 |
| 2K 超分 | 已生成的 768p 视频 | 2688×1536，音轨原样保留 | ~10s / 条 |
批量是内建能力：多提示词清单、同提示词多 seed 挑优、断点续跑、失败自动分类——这些在第二部分展开。
成本账
| 产物 | 耗时 | 成本 |
|---|---|---|
| 768p / 5s | ~85s 热态 | ~¥0.08 |
| 768p / 10s | ~243s | ~¥0.22 |
| 768p / 5s + 2K 超分 | +10s | ~¥0.09 |
| 冷启动（每次开实例） | 1~3 分钟 | ~¥0.10 |
实例按秒计费，Skill 在全部任务完成后会自动暂停实例停止扣费——这是它和「手动跑」最大的区别：你不需要记得关机，也不为闲置付费。
典型场景与开场白
| 场景 | 示例：直接对 Agent 说 |
|---|---|
| 灵感速验 | 「生成一条 5 秒视频：日出时热气球升起的卡帕多奇亚。Audio: 晨风与鸟鸣」 |
| 素材批量 | 「这个提示词出 6 条，768p，我挑一条发抖音」 |
| 多平台矩阵 | 「按这 10 条文案各出一条竖屏视频，全部超分 2K」 |
| 角色 / IP 内容 | 「用这张角色设定图生成雨中撑伞漫步的竖屏视频」 |
| 动态封面 | 「让这张海报动起来：镜头缓慢推近，粒子飘散」 |
| 电商展示 | 「用产品白底图生成 360° 旋转展示视频，超分 2K」 |
| 工作室量产 | 「按清单跑 50 条，中断了记得续跑，跑完给我 manifest」 |
三步开始
① 安装 Skill
npx skills add shaozheng0503/suanli-h3-video --skill suanli-h3-video② 配置密钥
cp suanli-h3-video/skill/.env.example suanli-h3-video/skill/.env
# 填入 SUANLI_TOKEN：console.suanli.cn → 右上角头像 → API 密钥（推荐简易模式）③ 对 Agent 说一句话
用 suanli-h3-video 生成一条 768p 5 秒视频：雨夜霓虹街头，一只机械狗叼着
玫瑰花穿过斑马线，缓慢跟拍，赛博朋克。Audio: 雨声与低沉合成器约 90 秒（含冷启动）后，带音轨的成片落在本地的 jobs 目录里。
写提示词的关键：H3 是音画一体模型，画面和声音一起写——镜头怎么动、场景是什么、Audio: 后面接环境音和对白。只写画面不写声音，生成的视频可能静音。
常见问题
Q：必须先手动开好一台实例吗？
A：不用。Agent 会先查库存、自动创建部署任务、等 ComfyUI 就绪后才开始生成。你也可以用自己在跑的实例——把 8188 端口域名告诉它即可。
Q：批量跑一半中断了？
A：重新执行同样的命令即可，已完成的任务自动跳过（断点续跑）。
Q：1080p 可以吗？
A：32G 的 5090 跑 1080p 长片会显存溢出。推荐 768p 生成 + VSR 超分到 2K，效果更好且更稳。
Q：和官方按条计费的 API 比呢？
A：官方 2K 约 ¥0.13/秒；本方案 5 秒 2K 约 ¥0.09，约为官方的 1/7——代价是出片要等约 95 秒。
第二部分：给 Agent 看（与集成参考）
以下内容 Skill 安装后会被 Agent 自动读取（SKILL.md 与 api/ 目录）。如果你不用 Skills 规范、想直接写代码集成，这部分就是完整的接口参考。
镜像与服务端口
| 项 | 值 |
|---|---|
| 镜像 | harbor.suanleme.cn/public-hub/h3vsr-merge:0.1.4-5090 |
| 8188 | ComfyUI（H3 生成，工作流级 API） |
| 8001 | RTX VSR 超分（FastAPI，简单 REST） |
| 推荐机型 | 5090，宿主内存 ≥128GB（58GB 廉价档跑批量会 OOMKilled） |
生成链路（8188）
POST /prompt 提交工作流 JSON → {"prompt_id", "node_errors"}
GET /history/{id} 轮询 → status_str: success | error
GET /view?filename=... 下载 mp4
POST /upload/image 上传首帧/参考图（multipart，超时 ≥600s）工作流要点（turbo 4 步链，RandomNoise → BasicGuider → KSamplerSelect → BasicScheduler → SamplerCustomAdvanced）：
| 模式 | unet | LoRA | 核心节点 |
|---|---|---|---|
| T2V / I2V | minimax_h3_fl2va_pruned_int8_convrot | minimax_h3_fl2v_turbo_4step_v1.0_768p | MiniMaxH3ImageToVideo |
| R2V | minimax_h3_ref2va_pruned_int8_convrot | minimax_h3_ref2v_turbo_4step_v0.1_768p | MiniMaxH3ReferenceToVideo（必填 audio_vae、ref_images 列表、ref_image_size） |
硬约束（违反不报错但结果异常）：
width/height必须是 32 的倍数：768p = 1344×768（推荐）、1080p 长片会 OOMlength必须满足(length-5) % 17 == 0且124 ≤ length ≤ 362：5s=124 / 10s=243 / 15s=362；非法值静默取整BasicScheduler必须带denoise: 1.0（缺了报 400）- 批量每条必须随机 seed——相同参数会命中 ComfyUI 执行缓存，2~3 秒返回旧结果
MiniMaxH3SigmaShift(12.0, 3.0)与 CFG=1.0 勿动（turbo LoRA 按 4 步训练，加步数不提升画质）
超分链路（8001）
GET /healthz 探活
POST /api/v1/upscale/file multipart：file + scale + quality + vcodec + bitrate
GET /api/v1/tasks/{id} 轮询 → queued/running/done/error
GET /api/v1/tasks/{id}/result 下载 mp4 二进制流quality推荐 HIGH（AI 生成源）；vcodec在共绩平台必须libx264（节点 NVENC 不可用）quality非法值异步暴露：提交返回 200，轮询时才见 error- 生成与超分严禁同卡并行（27.8G + 10.5G > 32G）——先生成完一批，再统一超分
实例生命周期（Open API）
GET https://openapi.suanli.cn/api/deployment/resource/search 查库存（核 memory ≥128GB）
POST /api/deployment/task/create 创建（镜像 + 8188/8001 端口 + 资源 mark）
GET /system_stats（8188） 探活（ComfyUI 无 /health；冷启动 1~3 分钟需重试）
POST /api/deployment/task/pause 暂停（停止计费）
POST /api/deployment/task/recover 恢复Header：token + timestamp（毫秒）+ version: 1.0.0。计费：1 元 = 1,000,000 点。
批量执行器（开箱即用）
scripts/h3_batch.py 纯标准库实现，封装了上述全部链路：
# 单条 / 批量（随机 seed 防缓存）
python3 scripts/h3_batch.py submit --comfy $COMFY --prompt "..." --resolution 768p --duration 5
python3 scripts/h3_batch.py submit --comfy $COMFY --prompt-file tasks.txt --count 8
# 断点续跑（done 任务自动跳过）
python3 scripts/h3_batch.py submit --comfy $COMFY --job jobs/<ts>/ ...
# 失败重试（timeout/网络错误可重试；参数错误属 fatal）
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 3571477状态账本在 jobs/<ts>/job.json（含每条的 prompt/seed/mode/resolution/duration/产物路径），中断续跑与事后审计都靠它。
稳定性设计（实测教训沉淀）
- 任务间隔 8s：单卡长队列会累积宿主内存导致 OOMKilled（Exit 137），实测换来的节奏
- 滑动窗口：批量内部同时在途 2 条，126GB 实例实测安全，比纯串行快 6%
- 原子下载：
.part临时文件 + 原子改名，半截文件不会混入交付 - 错误分类：retryable（超时/网络）与 fatal（参数错误）分开，
retry只重试前者 - i2v/r2v 限制：实例重启会清空已上传图片，这类失败任务需带图重新
submit --job
完整测试与基准数据见 GitHub 仓库（28 项回归测试 + 真机性能表）。
相关链接：GitHub 仓库 · Agent Skills 规范 · h3vsr-merge 镜像文档 · MiniMax H3