Hypit 常见问题排查：安装、素材、生成和导出

先保存版本、任务和消耗证据

不要先重装或重复提交。记录版本、系统、Profile/Endpoint、最后成功步骤、任务 ID、模型、时间、消耗变化和脱敏错误。公开问题报告过参考帧处理阶段耗尽余额但尚无维护者结论，不能把原因写死。

先定位失败发生在哪一步

同一个“不能用”可能出现在 Skill 加载、素材读取、模型请求或成片导出阶段。先记录最后一个成功步骤，能避免重装整个环境。以下是通用诊断路径，不是对某个版本缺陷的断言。

不要把网络超时当作一定没生成

提交请求后连接中断，服务端可能已经接收任务。先查原任务或请求记录，再决定重试，尤其不要同时开多个窗口重复提交可能付费的任务。把请求 ID 和时间放在同一条诊断记录中。

字幕或声音不对时，先缩小范围

用一个短片段对照原台词：是文字本身错、发音错，还是时间位置错？分别描述问题，保留一处可复现的时间点。中文标点、人名和数字读法应在脚本阶段确认。

• 文字错误：修正脚本并检查字幕是否来自旧版本。
• 时间错误：对照声音与字幕出现时刻，记录偏移。
• 声音问题：检查原素材与导出文件是否都有音轨。
• 样式问题：在目标手机尺寸检查字号和安全区域。

发送一份可用的问题报告

提供最少但足以定位的信息。日志中先移除密钥、签名 URL 和私人素材地址。

目标：
系统与 Agent：
Hypit 版本／检查日期：
输入类型：
最后成功步骤：
失败步骤及错误原文：
请求 ID（如有）：
期望结果／实际结果：
已尝试的排查：

恢复后再验证一次

修复后先用最小片段确认问题消失，再扩大项目。记录哪些文件或设置改变了，避免下一次更新时重复同样的排查。关于版本特有问题，以官方维护记录为准。

区分本地项目与托管 API 错误

下面的状态码属于 Hypit 官方托管 API，不是每个第三方 Provider 的统一约定。先确认失败发生在哪个服务，再保留脱敏错误码和请求 ID。

重试前找到原任务

官方异步任务接口支持 Idempotency-Key，重复提交应保留同一个键；425 admission_in_progress 表示原提交仍在准备中。本地新 Build 与托管任务重试是不同操作。先查已完成输出，再决定恢复路径。

Studio 预览素材加载或拖动进度异常

官方 0.2.10 修复了 Studio 按媒体元素请求的字节范围提供编排素材的问题。遇到素材加载或拖动进度异常时，先记录 CLI 版本、素材格式和复现步骤，再核对该修复是否适用。更新相关安装后重启 Studio，并用同一素材检查播放与跳转；这条修复不代表所有黑屏或解码错误都有相同原因。

Seedance 提示缺少人物参考标记

0.2.8 要求每个图片或视频参考明确标注是否含人物；含人物为 true，不含人物为 false，音频不加该字段。让 Agent 检查每个视觉 Reference 的 person-reference，以及 FrameVideo 的首尾帧标记。直接 API 请求对应 fields.personReference。补齐后再提交。

字幕重叠或最后合成阶段采样数不符

官方 0.2.6 已修复相邻字幕边界重叠，以及 AAC 最终合成的采样误差容忍问题。遇到同类症状先核对版本并保留原工程。X 旧帖中的降级 FFmpeg、替换 ALAC 属于作者当时的绕行做法，不作为当前默认修复。更新后仍失败时，再记录完整错误与最小复现。

0.2.x 常见边界检查表

先匹配症状，再恢复。