TranslateBase

视频翻译 API 概述

视频翻译开放 API 快速开始：创建项目、上传视频、发起翻译、字幕处理与成品下载的完整流程说明与通用约定

视频翻译 API 概述

视频翻译开放 API 提供短剧视频翻译的完整能力：创建项目、上传视频、发起自动翻译（擦除、校准、翻译、压制四阶段）、字幕查看与编辑、成品下载。

业务流程总览

一次完整的视频翻译流程如下，每一步标注了对应的接口：

1. 创建项目（指定源语言/目标语言，创建后不可修改）
   └─ 新增项目  GET /project/add.html

2. 上传视频（COS 直传三步链路）
   ├─ 获取 COS 直传临时密钥  GET /project/video/uploadCredentials.html
   ├─ 前端使用 cos-js-sdk-v5 直传文件至 COS（不经过服务端）
   ├─ 直传完成回调入库        GET /project/video/uploadComplete.html
   └─ 批量新增视频            GET /project/video/add.html

3. （可选）设置字幕区域（影响 OCR 字幕检测范围，建议在开始翻译前设置）
   └─ 批量设置字幕区域  GET /project/video/subtitleRegion/save.html

4. 开始翻译（异步任务）
   └─ 开始翻译  GET /project/video/translate.html

5. 轮询翻译进度（四阶段：擦除 → 校准 → 翻译 → 压制）
   └─ 视频列表  GET /project/video/data.html

6. （可选）字幕查看与编辑
   ├─ 获取源字幕 / 获取翻译后字幕
   └─ 更新源字幕 / 更新翻译后字幕

7. （按需）失败重试 / 取消队列任务
   ├─ 重试      GET /project/video/retry.html
   └─ 取消翻译  GET /project/video/cancelTranslate.html

8. 下载成品
   ├─ 单集文件签名下载  GET /file/signFile.html
   └─ 整剧打包下载      GET /project/downloadEo.html

上传与发起翻译之间可通过 视频列表 接口确认视频已入库；翻译过程中四阶段状态也通过该接口轮询。

认证说明

开放接口基于应用的签名认证机制：

  • 请求需携带 X-App-Id 请求头标识应用身份；
  • 请求参数参与 HMAC-SHA256 签名校验，含时间戳（有效期 ±5 分钟）与随机数 nonce 防重放；
  • 应用在签名认证通过后作为请求主体，所有资源按应用隔离（项目、视频等均归属创建应用）。

appKey 的申请流程与签名算法细节待补充。

通用约定

统一返回结构

所有接口返回统一结构 BaseReturnModel：

名称类型说明
idstring请求 ID
codeinteger返回码，0 表示成功，非 0 表示失败
msgstring提示信息
dataobject业务数据，结构视具体接口而定

本教程各接口的返回示例中 data 为占位空对象，实际结构以对应接口的后端实现为准。

分页与过滤参数

列表类接口（项目列表、视频列表）支持以下通用参数：

名称类型必选说明
pageinteger否页码，从 1 开始
limitinteger否每页数量
sortstring否排序字段
orderstring否排序方向
dataEqualstring否精确过滤条件，JSON 串，如 {"projectId":"xxx"}
dataLikestring否模糊过滤条件，JSON 串
dataRangestring否范围过滤条件，JSON 串

列表接口返回分页结构，包含 records（当前页记录）、total（总数）、size（每页数量）、current（当前页码）、pages（总页数）。

翻译四阶段状态

视频翻译为异步任务，依次经历四个阶段，每个阶段有独立的状态字段：

阶段状态字段说明
擦除（erase）eraseStatus擦除原视频字幕
校准（review）reviewStatusVLM 校准 OCR 结果
翻译（translate）translateStatus字幕翻译
压制（embed）embedStatus将翻译字幕压制回视频

各阶段状态枚举一致：

状态值说明
init未开始
queue队列中
processing处理中
success成功
fail失败

付费与重试

  • 付费状态 isPaid：unpaid-未付费、paid-已付费、refunded-已退款；
  • 翻译成功后可重新翻译（重试），有免费重试次数上限（remainingFreeRetryCount 为剩余免费次数），超出后重新扣费，详见 重试接口。

文档导航

文档内容
项目管理 API项目的创建、查询、编辑、删除
视频上传 APICOS 直传三步链路、视频入库、视频查询/编辑/删除
视频翻译任务 API发起翻译、取消任务、失败重试、四阶段进度说明
字幕处理 API源/译字幕的获取与更新、批量设置字幕区域
成品下载 API单集签名下载、整剧打包下载