# 短剧工作流 API 怎么接：任务、回调、重试与交付

先把一部剧怎样变成任务、作品和版本说清，再写接口。短剧批量接入真正难的是失败以后还能从正确位置继续。

作者：提莫 · 鬼手剪辑 GhostCut

![视频译配 API、异步任务的文章总览图](https://cn.jollytoday.com/assets/ghostcut-insights/images/short-drama-localization-api-tasks-callbacks-retries-overview-v1.webp) _先把一部剧怎样变成任务、作品和版本说清，再写接口。短剧批量接入真正难的是失败以后还能从正确位置继续。_

**先说结论**

视频译配通常采用异步任务：提交后保存任务 ID，再查询状态或接收回调。调用方要把任务对应到剧集、源文件和语言版本，设计重复提交保护，并按接入协议验证回调来源。超时先查原任务，输入错误先补文件；结果下载、校验和归档后才算交付。

## 批量接入前，先定义一集怎样变成任务

网页端处理几条样片时，操作人可以看到失败并重新点击。接入几十集后，上传、识别、擦除、翻译、配音和合成可能分别运行几分钟到几小时；如果系统只保存一个“处理中”，团队既不知道卡在哪一步，也无法判断重新提交会不会制造两份结果。 同一集可能同时有两种语言在处理，其中一种已经改过字幕，另一种还在等待配音。调用方需要知道每个任务用了哪份源文件、哪版参数，以及最终要交付哪个结果，否则晚完成的旧任务就可能覆盖新版。先把剧集、语言和源版本对应起来，再保存服务返回的任务 ID，查询、回调和人工修改才都能落回同一条记录。执行完成与内容获准交付也要分开，避免把可下载结果直接送去发布。

自动化译配最难排查的时刻，通常不是接口返回报错，而是请求超时后任务其实已经创建。若系统再次提交同一集，可能得到两份成片、两笔费用和两个回调；运营看到的却只是一个“处理中”。所以任务状态、业务编号和实际文件必须分开记录。

## 联调时确认标识、状态和结果保存方式

联调前先画出业务对象和状态机，尤其确认源文件由谁保存、回调发送到哪里、结果保存多久，以及局部返工是否会生成新版本。

**稳定标识**

在调用方为剧、集、源文件、语言和版本保存业务 ID，并关联服务返回的任务 ID。

**异步状态**

按实际接口状态建立映射；批次部分成功由单集结果汇总，不假定服务提供取消或所有中间状态。

**失败责任**

区分网络、限流、输入损坏和参数错误，并约定哪些状态需要人工处理。

**交付边界**

确认结果 URL 有效期、产物字段和错误信息；接口未提供的校验值由下载方计算留存。

## 跑通提交、查状态和归档，再扩大批次

先接最短闭环：创建任务、查询状态、接收回调、下载结果。闭环稳定后再加批量、局部返工和多语言，不要第一天就把所有业务分支塞进一个巨大接口。

### 处理步骤

*01*

**登记源资产**

保存源文件校验值、业务 ID 和请求参数版本

*02*

**保护重复提交**

记录提交意图与返回任务 ID；超时进入待核对，不立即重建

*03*

**查询补偿回调**

验证通知来源并去重，再查询任务确认结果

*04*

**按错误类别恢复**

限流退避重试，坏文件停下补源，并设置重试上限

*05*

**验收并固化版本**

下载并核对产物，把文件关联回剧集和语言版本

 __

幂等的意思是重复处理同一请求时，不再创建一份新业务结果。如果服务支持幂等键，就按文档传递；不支持时，调用方需用提交记录和唯一约束防止并发重复，但这仍不能消除“服务已接收、响应却丢失”的不确定状态。遇到这种超时，先按已有任务标识或服务方提供的查询方式核对，并把任务标记为待处理，等人工看过提交记录后再决定是否补发。回调若有签名，按协议验签；没有签名时，把通知当作查询提示，通过已鉴权的状态接口确认结果，不凭回调直接批准交付。 先把一集的提交、查询、回调、下载和失败补偿串起来，再扩到整部剧。回调只负责通知状态，不能代替结果查询；接收端按业务编号去重，处理端按供应商任务 ID 查询。这样网络重试不会变成视频重做，编辑也能从原任务继续查到具体版本。

![短剧工作流 API 怎么接：任务、回调、重试与交付正文重点流程与判断示意图](https://cn.jollytoday.com/assets/ghostcut-insights/images/short-drama-localization-api-tasks-callbacks-retries-highlight-v2.webp) _先接最短闭环：创建任务、查询状态、接收回调、下载结果。_

## 超时以后，先查原任务再决定是否重试

最危险的 API 问题不是明确报错，而是调用方和服务方对任务是否成功理解不同。重试策略要围绕业务结果，而不是只围绕 HTTP 状态码。

| 看到的问题 | 更可能的原因 | 先做什么 |
| --- | --- | --- |
| 同一集出现两份扣费任务 | 超时后直接重新创建，缺少重复提交保护 | 查本地提交记录及已知任务 ID，标记待核对后再决定是否补发 |
| 回调显示完成却下载不到 | 结果链接过期或产物暂不可用 | 回查任务，按服务支持的方式重新获取结果 |
| 整批停在一集 | 调用方把批次与单集状态绑死 | 隔离失败集，让合格集继续 |
| 改一条字幕重做整集 | 未保存中间产物，或接口不支持对应局部操作 | 先查可复用产物与支持的重做粒度，再选择处理范围 |

在测试环境模拟超时、重复通知和漏通知，检查同一任务是否只归档一次。再让一个坏文件与正常集数同批提交，确认失败不会阻塞合格结果。旧任务的延迟回调只能更新旧任务记录，不能覆盖后来选定的发布版本；结果链接过期时，按服务支持的方式重新获取地址或补交文件，不能把下载失败当成重新生产的理由。

## 下载成功后，还要核对并长期归档

交付记录应包含源文件校验值、请求参数摘要、任务 ID、各步骤时间、目标语言、产物列表、版本号和失败明细。结果文件最好由业务方转存到自己的长期存储，不把临时下载地址当作归档。 每天只处理少量视频、没有内部研发或不需要系统间同步时，网页端更直接。API 不是成熟度勋章；当异常处理和监控成本高于人工操作，它反而会增加维护负担。

## 让 API 任务能回到剧集和人工处理流程

GhostCut 的整剧工作流适合把多集任务、字幕、角色、翻译、声音和成片关系留在同一项目里。团队通过 API 接入时，仍应在自己的系统保存业务 ID、权利信息和最终交付记录，并对失败重试和人工审核负责。 接口跑通后，下一项测试不是更高并发，而是局部修改：改一个人名或一条配音，系统能否只重做真正受影响的结果。

## 需要把这一步接入整剧生产时

GhostCut 可以把字幕、净版、角色、翻译、声音和成片版本放在同一部剧下继续处理，适合多集、多语言和需要局部返工的项目。

[查看整剧译配工作流 →](https://cn.jollytoday.com/technology/ai-video-localization-studio-series-production/)

接下来可以继续问

## [一部几十集的短剧，为什么不能一集一集单独翻译？](https://cn.jollytoday.com/insights/topics/localization-studio/)

人物、术语、声音和画面版本会跨集复用，逐集单做容易改名、换译法和用错净版。

## 常见问题

### 视频 API 为什么一定要异步？

 识别、画面处理、翻译和合成耗时较长，同步连接不适合承载完整任务。

### 有回调还需要查询接口吗？

 需要。回调可能延迟或丢失，查询接口用于恢复和核对当前状态。

### 哪些错误不应自动重试？

 输入损坏、权利或内容不允许、参数不支持和需人工确认的问题不应无限重试。

## 资料来源与说明

- [GhostCut Insights：短剧出海工作流](https://cn.jollytoday.com/insights/topics/workflow/)
- [GhostCut Insights：译配生产与质量](https://cn.jollytoday.com/insights/topics/production-quality/)
- [FFmpeg Documentation](https://ffmpeg.org/documentation.html)

发现资料过期或表述有误？请参照[勘误说明](https://cn.jollytoday.com/insights/editorial-policy/#corrections)告诉我们。