🎯 一句话总结：把声音与画面拆开，MiniMax 负责克隆声音和生成配音，HeyGen 负责驱动人像，Codex 负责检查素材、控制生成顺序并记录任务状态。整条流程最重要的一步，是先做 15 秒样片，确认后再生成完整版。
📌 整条链路怎么分工
这套流程适合知识口播、课程讲解、产品介绍、多语言内容、短视频批量生产，以及需要长期维护固定形象的数字人账号。
核心思路不是让一个平台包办所有环节，而是把声音和画面分开处理：
| 环节 | 工具 | 负责内容 |
|---|---|---|
| 声音 | MiniMax | 声音克隆、TTS 配音、输出 MP3 |
| 画面 | HeyGen | 人像驱动、口型、表情、动作与视频生成 |
| 流程 | Codex | 素材检查、API 调用、样片确认、状态记录与风险控制 |
完整链路如下：
- 检查文案、人像和声音样本。
- 用 MiniMax 克隆声音并生成完整配音。
- 截取配音前 15 秒，交给 HeyGen 生成竖屏样片。
- 人工检查声音、口型、脸部稳定性和构图。
- 样片确认后，再生成完整视频。
- 下载成片并检查音画、时长和文件完整性。
- 把
voice_id、asset_id、video_id和任务状态写入状态文件。
⚠️ MiniMax 已经生成配音后，应把这段音频直接上传给 HeyGen 驱动画面。不要再切回 HeyGen 的
script + voice_id配音方式，否则最终声音可能不再是原来的克隆音色。
🎙️ MiniMax 声音克隆怎么准备
声音克隆质量不好，很多时候不是模型的问题，而是样本里混入了背景音乐、混响、电流声或多人对话。
MiniMax 当前支持的克隆样本要求如下：
| 项目 | 要求 |
|---|---|
| 文件格式 | MP3、M4A、WAV |
| 样本时长 | 10 秒至 5 分钟 |
| 文件大小 | 不超过 20 MB |
| 可选提示音频 | 少于 8 秒，并提供完全对应的文字 |
虽然 10 秒即可提交，实际录制建议控制在 30 至 90 秒：
- 只保留一个人的声音；
- 不加背景音乐；
- 避免明显混响和电流声；
- 音量保持稳定；
- 语速接近日常口播；
- 不使用过度降噪、变速或多次压缩的音频。
第一次测试可以先用海外版 Voice Clone 建立音色，再通过 TTS 输出 MP3。重视质量时可先试 speech-2.8-hd；批量预览或追求速度时，可用 speech-2.8-turbo 跑小样。模型名称和可用范围可能调整，调用前应以账户控制台返回结果为准。
🖼️ HeyGen 模式与人像要求
第一次操作，适合从 Image-to-Video 开始。它不要求先训练完整 Avatar，只需一张人像和一段音频，就能检查口型、表情、脸部稳定性与构图。
| 使用场景 | 推荐方式 |
|---|---|
| 单条测试、验证效果 | Image-to-Video |
| 固定账号长期生产 | Photo Avatar |
| 尚未确认人像与声音 | 暂不训练 Avatar |
人像素材不用复杂，但必须清晰：
- 正脸看向镜头，五官无遮挡；
- 画面包含头部、肩部和上半身；
- 人物约占画面 50% 至 70%；
- 嘴部不要被头发、手或滤镜遮挡；
- 竖屏短视频优先选择 9:16 或接近 9:16 的图片。
HeyGen Image-to-Video 支持通过公开图片 URL 或已上传资产使用 PNG、JPEG 人像。标准 Assets API 还支持视频、音频和 PDF，普通代理上传单文件上限为 32 MB；更大文件应使用直传流程。
HeyGen 允许两种音频输入方式：
script + voice_id：由 HeyGen 选择声音并生成配音；audio_url或audio_asset_id：直接使用外部生成的音频。
两种方式互斥。如果要保留 MiniMax 克隆音色，应选择第二种。
⚙️ 放进 Codex 执行
建议每个项目都使用同一套目录：
project/
├── inputs/
│ ├── portrait.jpg
│ ├── voice-source.mp3
│ └── script.md
├── work/
│ ├── voiceover-full.mp3
│ ├── preview-15s.mp3
│ └── job-state.json
└── outputs/
├── preview-15s.mp4
└── final-1080p.mp4
可以把下面这段任务说明直接交给 Codex：
请用 MiniMax 海外版声音克隆和 HeyGen API 制作数字人口播。
输入：
- 文案：inputs/script.md
- 人像：inputs/portrait.jpg
- 声音样本：inputs/voice-source.mp3
- MiniMax 密钥来自环境变量 MINIMAX_API_KEY
- HeyGen 密钥来自环境变量 HEYGEN_API_KEY
流程：
1. 先检查素材。
2. 先生成 15 秒样片。
3. 样片明确确认后再生成完整版。
4. 所有任务 ID 写入 work/job-state.json。
5. 不要在日志、脚本或文档中显示完整密钥。
配套 Codex Skill 可从 GitHub 仓库 获取。复制到 Codex skills 目录后，可以这样调用：
用 $rachel-digital-human-production 做这条视频，先只做 15 秒样片。
需要补充独立 AI API 上游做流程测试时，可以使用 APIMart API 聚合平台。MiniMax 与 HeyGen 的具体接口仍以各自官方账户和文档为准，不要把聚合上游当成同一服务。
🛡️ Skill 应固定哪些规则
自动化的价值不只是少敲几条命令，而是让每次生产都遵循同一套边界：
- 固定项目目录；
- 调用付费 API 前先检查素材；
- MiniMax 负责声音，HeyGen 负责画面；
- 永远先生成 15 秒样片；
- 没有明确确认，不生成完整版；
- 记录
voice_id、asset_id、video_id和任务状态； - 失败后先读取状态，不盲目重试；
- 完整检查最终 MP4；
- 不把 API Key、Authorization Header、签名下载链接写入日志；
- 人像、声音样本和客户视频不进入公开 Skill 包。
API Key 应通过环境变量传入：
export MINIMAX_API_KEY="..."
export HEYGEN_API_KEY="..."
.env、真实密钥、私人人像、声音样本和生成视频都应加入忽略规则。若密钥曾在聊天、截图或日志中明文出现，应立即在对应后台轮换，而不是只删除本地记录。
数字人还涉及肖像、声音和发布授权。只处理自己拥有或已获明确许可的素材，不要克隆他人声音或冒用他人形象。
⚠️ 15 秒样片检查清单
数字人成片最常见的问题包括：
- 声音不像本人；
- 中文口型跟不上；
- 脸部轻微变形；
- 嘴角和下巴运动异常；
- 眨眼与肩部动作不自然；
- 竖屏构图不适合发布平台；
- 音频结尾被截断；
- 失败重试导致重复扣费。
样片阶段逐项检查：
| 检查项 | 合格标准 |
|---|---|
| 声音 | 音色接近样本，无明显噪声和断句错误 |
| 口型 | 中文发音与嘴部动作基本同步 |
| 脸部 | 五官稳定，无持续扭曲或漂移 |
| 动作 | 眨眼、头部和肩部动作不过度 |
| 构图 | 人物位置、留白和竖屏比例可用 |
| 时长 | 样片约 15 秒，开头和结尾完整 |
| 状态 | ID、费用阶段和输出路径已记录 |
样片没有通过时，只修改一个变量再重跑，例如先换人像，或只调整声音样本。一次同时改动多项，很难判断问题来自哪里。
❓ 常见问题
Q：为什么一定要先做 15 秒样片？
完整视频会消耗更多额度。先看 15 秒，能以较低成本发现音色、口型、脸部和构图问题，也能减少错误重试。
Q：能不能直接把文案交给 HeyGen 配音？
可以，但这会使用 HeyGen 的声音方案。若目标是保留 MiniMax 克隆音色，应先生成 MP3，再用 audio_url 或 audio_asset_id 驱动画面。
Q：第一次就需要训练 Photo Avatar 吗？
不需要。先用 Image-to-Video 验证人像和声音，确认能稳定生产后，再考虑长期使用的 Photo Avatar。
Q：任务失败后为什么不能直接重试？
上一次请求可能已经创建任务或产生费用。先读取 job-state.json 和远端任务状态，确认没有重复任务后再继续。
Q：能把人像和声音样本放进公开仓库吗？
不建议。Skill 只应保存流程、脚本和模板。私人人像、声音、API Key、签名 URL 与客户成片应留在项目目录，并设置忽略规则。
