批量接入前，先定义一集怎样变成任务
网页端处理几条样片时，操作人可以看到失败并重新点击。接入几十集后，上传、识别、擦除、翻译、配音和合成可能分别运行几分钟到几小时；如果系统只保存一个“处理中”，团队既不知道卡在哪一步，也无法判断重新提交会不会制造两份结果。 同一集可能同时有两种语言在处理，其中一种已经改过字幕，另一种还在等待配音。调用方需要知道每个任务用了哪份源文件、哪版参数，以及最终要交付哪个结果，否则晚完成的旧任务就可能覆盖新版。先把剧集、语言和源版本对应起来，再保存服务返回的任务 ID，查询、回调和人工修改才都能落回同一条记录。执行完成与内容获准交付也要分开，避免把可下载结果直接送去发布。
自动化译配最难排查的时刻，通常不是接口返回报错，而是请求超时后任务其实已经创建。若系统再次提交同一集，可能得到两份成片、两笔费用和两个回调；运营看到的却只是一个“处理中”。所以任务状态、业务编号和实际文件必须分开记录。
联调时确认标识、状态和结果保存方式
联调前先画出业务对象和状态机，尤其确认源文件由谁保存、回调发送到哪里、结果保存多久，以及局部返工是否会生成新版本。
跑通提交、查状态和归档，再扩大批次
先接最短闭环：创建任务、查询状态、接收回调、下载结果。闭环稳定后再加批量、局部返工和多语言，不要第一天就把所有业务分支塞进一个巨大接口。
处理步骤
幂等的意思是重复处理同一请求时，不再创建一份新业务结果。如果服务支持幂等键，就按文档传递；不支持时，调用方需用提交记录和唯一约束防止并发重复，但这仍不能消除“服务已接收、响应却丢失”的不确定状态。遇到这种超时，先按已有任务标识或服务方提供的查询方式核对，并把任务标记为待处理，等人工看过提交记录后再决定是否补发。回调若有签名，按协议验签；没有签名时，把通知当作查询提示，通过已鉴权的状态接口确认结果，不凭回调直接批准交付。 先把一集的提交、查询、回调、下载和失败补偿串起来，再扩到整部剧。回调只负责通知状态，不能代替结果查询；接收端按业务编号去重，处理端按供应商任务 ID 查询。这样网络重试不会变成视频重做，编辑也能从原任务继续查到具体版本。
超时以后，先查原任务再决定是否重试
最危险的 API 问题不是明确报错，而是调用方和服务方对任务是否成功理解不同。重试策略要围绕业务结果，而不是只围绕 HTTP 状态码。
| 看到的问题 | 更可能的原因 | 先做什么 |
|---|---|---|
| 同一集出现两份扣费任务 | 超时后直接重新创建，缺少重复提交保护 | 查本地提交记录及已知任务 ID，标记待核对后再决定是否补发 |
| 回调显示完成却下载不到 | 结果链接过期或产物暂不可用 | 回查任务，按服务支持的方式重新获取结果 |
| 整批停在一集 | 调用方把批次与单集状态绑死 | 隔离失败集，让合格集继续 |
| 改一条字幕重做整集 | 未保存中间产物，或接口不支持对应局部操作 | 先查可复用产物与支持的重做粒度，再选择处理范围 |
在测试环境模拟超时、重复通知和漏通知，检查同一任务是否只归档一次。再让一个坏文件与正常集数同批提交，确认失败不会阻塞合格结果。旧任务的延迟回调只能更新旧任务记录，不能覆盖后来选定的发布版本；结果链接过期时，按服务支持的方式重新获取地址或补交文件，不能把下载失败当成重新生产的理由。
下载成功后，还要核对并长期归档
交付记录应包含源文件校验值、请求参数摘要、任务 ID、各步骤时间、目标语言、产物列表、版本号和失败明细。结果文件最好由业务方转存到自己的长期存储，不把临时下载地址当作归档。 每天只处理少量视频、没有内部研发或不需要系统间同步时，网页端更直接。API 不是成熟度勋章；当异常处理和监控成本高于人工操作，它反而会增加维护负担。
让 API 任务能回到剧集和人工处理流程
GhostCut 的整剧工作流适合把多集任务、字幕、角色、翻译、声音和成片关系留在同一项目里。团队通过 API 接入时，仍应在自己的系统保存业务 ID、权利信息和最终交付记录，并对失败重试和人工审核负责。 接口跑通后，下一项测试不是更高并发，而是局部修改：改一个人名或一条配音，系统能否只重做真正受影响的结果。