轮询超时不等于失败:rachel-digital-human-production失败恢复策略完全指南(断点续传与签名URL过期处理)
轮询超时不等于失败:rachel-digital-human-production失败恢复策略完全指南(断点续传与签名URL过期处理)
在数字人视频制作中,HeyGen 视频任务轮询(polling)超时是最常见也最容易被误判的故障。开源项目 rachel-digital-human-production 是一套面向 MiniMax 海外版声音克隆 + HeyGen Image-to-Video 的数字人口播视频生产工作流 Skill,它内置了一套完整的失败恢复策略:轮询超时不等于失败、签名 URL(signed URL)过期不等于任务丢失、下载失败不等于要重新生成。本指南带你用最小成本走完这套「断点续传 + 过期补救」流程,避免白白烧掉计费额度。
为什么「轮询超时」经常被误判为失败
数字人视频生成通常要等数分钟,而轮询请求的超时时间往往短于任务耗时。项目文档明确给出了一条核心原则:
视频任务应按
video_id轮询;超时(timeout)并不等于任务失败(failed)。
- 超时:只是「这次查询没等到结果」,服务端任务多半还在跑;
failed状态:是 API 明确返回的失败结论,需要记录原因后再决定是否重试。
把两者混淆的后果,是误判失败后重新提交任务——同一份 1080p 视频被生成两次,费用翻倍。
失败恢复四步决策表:先诊断,再动手
SKILL.md 的 Failure Policy 章节定义了四条恢复规则,可以直接当作排障决策表使用:
| 故障现象 | 是否真的失败 | 正确动作 | 为什么要这样做 |
|---|---|---|---|
| ⏳ 轮询超时 | ❌ 不等于失败 | 凭 video_id 继续轮询(Resume polling) |
任务大概率仍在服务端排队/生成 |
⚠️ API 明确返回 failed |
✅ 确认失败 | 记录失败原因,先向用户确认再重试 | 付费生成需显式批准,避免盲目重扣费 |
| 📥 下载失败 / MP4 损坏 | ❌ 视频还在 | 先重试下载,再谈重新生成 | 重新生成 = 二次付费,下载 = 免费 |
| 🔗 签名 URL 过期 | ❌ 任务还在 | 重新拉取任务状态或资产元数据 | 拿到新链接即可,无需新建付费任务 |
一句话记忆:只要没拿到 failed 状态,就一律按「任务还在」处理。
断点续传核心:用 job-state.json 恢复生产
这套失败恢复策略能成立的前提,是项目要求「每个外部任务阶段前后都要写 work/job-state.json」,把关键 ID 全部落盘:
voice_id:MiniMax 克隆音色,稳定命名如brand_person_yyyymmdd;asset_id/image_asset_id/audio_asset_id:HeyGen 上传的形象图与音频资产;video_id:HeyGen 视频任务 ID,断点续传的「钥匙」;status与outputs:预览/成片进度及产物路径。
状态模板见 references/checklists.md。没有状态文件时,可用辅助脚本一键生成骨架:
scripts/init_job_state.py --project demo --out work/job-state.json
断点续传的关键规则(SKILL.md):
如果已存在状态文件,且对应源文件没有变化,就复用现有的
voice_id、asset_id、video_id。
这意味着:中断后恢复时,你不用重新克隆音色(省一次克隆)、不用重新上传素材(省资产额度),只需拿 video_id 回到轮询环节。恢复生产时,项目还准备了可直接复用的提示词模板「Reusable Prompt: Final After Approval」,见 references/checklists.md。
签名URL过期怎么办:重新拉取,而不是新建任务
签名 URL(如 HeyGen 返回的视频下载地址)带有有效期,隔一段时间再点就是 403/404。新手最常见的错误是:链接失效 → 以为视频丢了 → 重新提交付费生成。
正确姿势分两步:
- 重新拉取任务状态:用同一个
video_id查询任务状态接口,任务仍为completed时会返回一个新的有效下载链接; - 或重新获取资产元数据:通过 HeyGen Assets 接口刷新该资产对应的临时链接。
整个过程不产生任何新付费任务。项目文档同时建议:成片要「足够快地下载」,避免链接过期(见 references/api-facts.md);下载支持时用断点续传(retry/resume)方式,且下载后要对整段 MP4 做解码检查,而不是只看文件大小或前几秒。
下载失败与 MP4 损坏:先重试下载,再谈重生成
把「下载侧问题」和「生成侧问题」分开,是省钱的第二道保险:
- 下载失败 / 文件损坏:先换重试或断点续传方式重新下载,视频本体在服务端仍在;
- 解码校验:下载完成后整段校验 MP4(如用 ffprobe 检查时长是否完整),确认无误才把
status置为完成。
前置预检脚本 scripts/preflight_assets.py 则负责在付费 API 调用之前拦截素材问题(音色文件需 10 秒~5 分钟、≤20MB,格式限 MP3/M4A/WAV;头像需 PNG/JPEG,常规上传 ≤32MB),从源头减少「生成到一半才发现素材不合规」这类浪费:
scripts/preflight_assets.py --script inputs/script.md --portrait inputs/portrait.jpg --voice inputs/voice-source.mp3
恢复流程速查清单
按顺序走一遍,覆盖 95% 的中断场景:
- [ ] 1️⃣ 确认是「超时」还是
failed?超时 → 直接跳到第 3 步; - [ ] 2️⃣ 若是
failed:把失败原因写入 work/job-state.json,征得用户确认后再决定重试; - [ ] 3️⃣ 打开状态文件,取出
video_id,继续轮询至completed; - [ ] 4️⃣ 若拿到的是过期的签名 URL:重新拉取任务状态/资产元数据换新链接,不要新建任务;
- [ ] 5️⃣ 下载失败:先重试下载,再做整段 MP4 解码校验;
- [ ] 6️⃣ 校验通过:更新
status与outputs,流程闭环。
配套质检项(口型、眨眼、构图等)见 references/checklists.md 的 Preview Review Checklist。
常见问题
Q:轮询到底该等多久才算超时?
项目文档刻意不写死超时阈值,只强调「超时后按 video_id 续轮询」。实际以你的网络与 HeyGen 队列状况为准,恢复动作永远是「续轮询」而非「重建任务」。
Q:状态文件里能不能存签名 URL? 不能。references/checklists.md 明确要求:绝不把完整 API key、Authorization 头或临时签名 URL 写进状态文件——它们会过期、会泄密,而且过期了正好说明你应该「重新拉取」而不是「翻旧账」。
Q:批量生产时怎么避免一次超时全批崩?
批量模式下每个脚本一条独立状态记录(一条 video_id 一把钥匙),单条超时只影响自己,其余任务照常轮询,见 SKILL.md 的 Batch Mode 章节。
关键文件索引
- 失败策略与生产闸门:SKILL.md
- API 事实基线(含轮询原则):references/api-facts.md
- 状态模板 / 质检清单 / 可复用提示词:references/checklists.md
- 状态骨架初始化脚本:scripts/init_job_state.py
- 付费调用前素材预检:scripts/preflight_assets.py
- 项目说明与目录约定:README.md
记住核心口诀:超时不是失败,过期不是丢失,下载不是生成——按 video_id 续轮询、按状态文件续生产,是这套数字人工作流里最省钱的两条纪律。