Skill: minimax-music-gen

MiniMax Music 3 × AutoDL 实例 音乐生成

在 AutoDL 应用实例的 ComfyUI 里跑 MiniMax Music 3（DiT + 专属 text encoder + DAV VAE）， 一键完成 开机 → 提交 → 轮询 → scp 下载 → ffprobe 校验 → 关机。单首曲目全程约 2~4 分钟。

• 开关机/SSH 通道来自 autodl-app-instance 与 minimax-h3 技能的 connect_server.py，本技能只管音乐生成。
• 视频生成走 minimax-h3，两者共用同一实例批次时遵循 autodl-app-instance 的批次契约：整批只开一次机、全部完成后只关一次机。

前置条件

依赖	说明
AUTODL_TOKEN	autodl.com → 设置 → 开发者 Token。脚本自动读环境变量或 ~/.config/autodl.env，缺 Token 时向用户转述脚本的申请指引
实例	MINIMAX-H3 应用镜像自带全部音乐模型。已验证可用：pro-7880531ea6b3（RTX 5090，2.88 元/小时）。账号下有多台同名 MINIMAX-H3 实例，必须用 --uuid 或 AUTODL_INSTANCE_UUID 显式指定；都不给时脚本会列出候选让你选
本机工具	expect（macOS 自带，scp/SSH 密码通道必需）、可选 ffprobe（时长校验）、可选 afplay/mpv（播放）

实例上的模型（缺失说明镜像不对，不要现下载大文件，直接换实例）： diffusion_models/minimax_music3/（DiT 三精度）、text_encoders/minimax_music3_text_encoder_bf16.safetensors、 vae/minimax_music3_dav.safetensors。

生成一条音乐（核心命令）

python3 "${ZCODE_HOME:-$HOME/.zcode}/skills/minimax-music-gen/scripts/generate_music.py" \
  --uuid pro-7880531ea6b3 \
  --caption "<英文三段式曲风描述，见 references/prompt_guide.md>" \
  --lyrics "<中文歌词，含 [verse]/[chorus]/[bridge]/[outro] 标记>" \
  --duration 180 \
  --slug "女声情歌" \
  --out "/绝对路径/成品.mp3"          # 可省，默认 ~/Music/minimax-gen/时间戳_slug.mp3

• 人声歌：给 --lyrics（可中文）。纯音乐：不给 --lyrics（caption 里写明 "No vocals"）。
• --duration 是 max_duration 上限，模型可能提前收尾——时长控制经验见下节。
• 脚本自动处理：无库存开机重试（每 30s 一次，默认 6 次）、提交、每 10s 轮询、scp 回传、 ffprobe 校验、成功后立即关机（--keep-on 跳过关机，用于同批次连做多首； 环境变量 AUTODL_KEEP_ON=1 等效）。
• 输出关键行：SAVED: <路径> <字节>、DURATION: <秒>、终态 success，耗时 <秒>s—— 这些就是要转述给用户的交付信息。

交互流程

1. 判断类型：人声歌（有/无歌词都行）还是纯音乐；casual 一句话就直接按 Basic 生成， 不必追问。
2. 预览再生成（除非用户催促直接出）：用用户语言展示——类型、曲风描述（本地化转述， 英文 caption 是内部实现不用贴原文）、歌词全文、目标时长。用户确认或改完再跑。
3. 歌词创作（用户没给歌词时）：默认用用户的语言写原创歌词。段落标记 [intro] [verse] [chorus] [bridge] [outro]；主歌每段 4 行、每行 7~12 字、 押韵（中文常用 an/ang/iu 等宽韵）；副歌重复但有变化。更多模板与完整示例 → references/prompt_guide.md。
4. 生成：跑上面的命令。长歌词用 --lyrics-file，长 caption 用 --caption-file。
5. 播放 + 交付：afplay <路径>（macOS）后台播放，报告绝对路径和实测时长。
6. 反馈迭代：满意即收工；不满意按用户意见改歌词/改 caption/换 seed 重跑，旧文件加 _v1 后缀保留对比。每首都是独立生成，旧版不会自动覆盖。

时长控制与耗时（RTX 5090 实测，2026-08-31）

max_duration 是上限不是保证：模型按内容密度自己决定实际长度，实测给 30s 上限 + 稀疏编排只出了 15s。控制手段是把 caption 的 ### Arrangement 按小节规划写满 （明确 Bar 1-2 / Bar 3-5 … 的段落与内容，并写 "finishing cleanly at exactly N seconds. Do not end before N seconds"）——实测同一 30s 目标从 15s 提到 27.6s。

目标时长	实测成品	合成耗时（提交→完成）
30s 纯音乐	15.1s / 27.6s	65.8s / 77.1s
3min 女声情歌（上限 210s）	2 分 03 秒	约 150s

粗略估算：合成时间 ≈ 成品时长 × 1.2 + 首任务 30~60s 模型加载；开机到可提交 <1 分钟 （遇到"当前算力规格暂无库存"由脚本自动重试）。每首成本约 0.3~0.5 元 GPU 费。

硬规则（踩过的坑）

1. 保存节点必须用 SaveAudioMP3。不要用工作流 UI 里的 SaveAudioAdvanced——它的 COMFY_DYNAMICCOMBO_V3 格式参数经 /prompt API 提交会丢 format，报 TypeError: missing 1 required positional argument: 'format'（采样结果会白算）。
2. 成品用 scp 拉回（脚本已内置）。不要用 base64 | cat 走 expect SSH 通道—— 大文件会被 expect 缓冲截断导致 base64 解码失败。远端路径含 audio/ 子目录 （/root/ComfyUI/output/audio/<file>），路径写错会得到 0 字节文件。
3. 批次结束必须关机（GPU 按秒计费）。多首连做：中间曲目 --keep-on，最后一首不加； 任何失败路径也要走 try/finally 关机，除非用户明确要求保持开机。
4. 不要打印 AUTODL_TOKEN / SSH 密码；不要调 release 接口（那是释放实例）。
5. ComfyUI 在实例内 127.0.0.1:6006；外网 8443 面板域名不透传 API。提交/轮询都走 SSH 内网 curl。
6. 采样节点有 ComfyUI 缓存：只改保存节点重提，秒级出结果，不会重算采样。

故障排查

现象	处理
当前算力规格暂无库存	脚本已自动每 30s 重试；连续失败告知用户稍后再跑
提交被拒（无 prompt_id）	看返回 JSON：节点参数名不符或模型文件缺失；对照脚本里 build_prompt 的参数
execution_error	读 history 里的 node_type 与 exception_message 定位节点
成品 0 字节 / scp 失败	远端路径少了 audio/ 子目录，或实例 SSH 端口已变（重取 snapshot）
时长远短于预期	Arrangement 按小节写满 + 显式 "exactly N seconds"，重生成
想要的音色/曲风不像	caption 的 Vocal Details 写具体（性别、音区、气声、副歌处理），换 seed 再试

视频流水线内的跳过策略

本技能在视频生产流水线（如 short-drama-production）中是可选增强：H3 视频自带音轨。 实例不可用（无 Token / 抢不到库存 / 生成失败）时不要阻塞交付，明确告知用户哪几段音乐 未生成、原因是什么，后续补配即可。旧的 TokenHub/腾讯云 API 路径（含其 402/429 错误码表） 已于 2026-08-31 全部移除，不要再用。