EN
文档 / 字幕翻译 API 协议说明 | 第三方翻译服务开发指南

字幕翻译 API 协议说明

1. 概述

本文档面向第三方集成，描述字幕翻译相关的两个 HTTP 接口，开发者可据此自行实现翻译服务端：

  • GET /api/languages —— 获取支持的目标语言列表（带本地化显示名）
  • POST /api/translate —— 上传字幕文件并翻译

两个接口配套使用：先用 /api/languages 拉取语言列表渲染下拉框，用户选择后将其 code 作为 targetLang 提交给 /api/translate。

翻译能力通常由上游大模型（如阿里云 DashScope 的 qwen-mt-flash、DeepSeek 等）提供，本服务端负责协议适配、分批调度与格式生成。

2. 通用约定

2.1 Base URL

  • 直连：http(s)://<host>:<port>
  • 反向代理：可能带路径前缀，如 https://<host>/subtitle-api

下文示例以 http://localhost:3000 为准，请按实际部署替换。端口由服务端 .env 的 PORT / HTTPS_PORT 决定。

2.2 编码与格式

  • 请求/响应均为 UTF-8。
  • /api/translate 使用 multipart/form-data（含文件上传）。
  • 所有 JSON 响应统一结构：成功为 { "success": true, "data": ... }，失败为 { "success": false, "error": "..." }。

3. 支持的目标语言

共 13 种目标语言，每种语言有一个稳定的 code（ISO 639-1），作为提交给 /api/translate 的契约值。显示名随 UI 语言变化，但 code 恒定不变。

code 中文显示名 原生名称
zh 中文 中文
en 英语 English
ja 日语 日本語
ko 韩语 한국어
fr 法语 Français
de 德语 Deutsch
es 西班牙语 Español
ru 俄语 Русский
pt 葡萄牙语 Português
it 意大利语 Italiano
ar 阿拉伯语 العربية
th 泰语 ไทย
vi 越南语 Tiếng Việt

提交给 /api/translate 的 targetLang 必须是上表中的 code（如 en），而非显示名（如「英语」「English」）。提交旧版中文名会被拒绝。

4. GET /api/languages

获取支持的目标语言列表，可按 UI 语言本地化显示名。

4.1 请求

参数 位置 必填 说明
lang query 否 UI 语言 code，决定 name 的显示语言；支持上述 13 种 code；未提供或为未知值时回退 zh；大小写不敏感

4.2 响应

data 为数组，每项形如 { "code": string, "name": string }：

  • code —— 稳定语言代码，作为 /api/translate 的 targetLang 契约值
  • name —— 在 lang 指定的 UI 语言下的显示名

示例：GET /api/languages?lang=zh（默认）

{
  "success": true,
  "data": [
    { "code": "zh", "name": "中文" },
    { "code": "en", "name": "英语" },
    { "code": "ja", "name": "日语" },
    { "code": "ko", "name": "韩语" },
    { "code": "fr", "name": "法语" },
    { "code": "de", "name": "德语" },
    { "code": "es", "name": "西班牙语" },
    { "code": "ru", "name": "俄语" },
    { "code": "pt", "name": "葡萄牙语" },
    { "code": "it", "name": "意大利语" },
    { "code": "ar", "name": "阿拉伯语" },
    { "code": "th", "name": "泰语" },
    { "code": "vi", "name": "越南语" }
  ]
}

示例：GET /api/languages?lang=en

{
  "success": true,
  "data": [
    { "code": "zh", "name": "Chinese" },
    { "code": "en", "name": "English" },
    { "code": "ja", "name": "Japanese" },
    { "code": "ko", "name": "Korean" }
  ]
}

示例：GET /api/languages?lang=ko

{
  "success": true,
  "data": [
    { "code": "zh", "name": "중국어" },
    { "code": "en", "name": "영어" },
    { "code": "ko", "name": "한국어" }
  ]
}

4.3 行为说明

场景 结果
缺省 / 空 lang 等同 lang=zh
已知 code（ko、ja、ru …） 返回该 UI 语言的译名
大写（KO、En） 大小写归一后查表，正常返回
未知 code（xx） 该项 name 回退为中文（names.zh）

5. POST /api/translate

上传 .srt / .vtt 字幕文件，返回翻译后的字幕内容。

5.1 请求

Content-Type: multipart/form-data

字段 类型 必填 说明
file File 是 字幕文件（.srt 或 .vtt，最大 10MB）
targetLang string 是 目标语言 code，如 en、zh、ja（取自 /api/languages 的 code）；大小写不敏感
apiKey string 否 翻译 API Key；不传则使用服务端 DEFAULT_API_KEY；两者皆无时返回 500
model string 否 翻译模型；不传则用服务端 DEFAULT_MODEL（默认 qwen-mt-flash）
batchSize number 否 每批翻译条数，范围 1–50，默认 20；超出范围会被夹紧到区间内
outputFormat string 否 输出格式：vtt（默认）或 srt；非 srt 一律按 vtt 处理

5.2 成功响应

{
  "success": true,
  "data": {
    "content": "WEBVTT\n\n1\n00:00:01.000 --> 00:00:03.000\nHello World\n\n",
    "format": "vtt",
    "totalSubtitles": 120,
    "filename": "movie.translated.vtt"
  }
}
字段 说明
content 翻译后的完整字幕文本
format 输出格式：vtt 或 srt
totalSubtitles 字幕条数
filename 建议的下载文件名（<原文件名>.translated.<格式>）

5.3 错误响应

{
  "success": false,
  "error": "错误描述信息"
}

5.4 状态码

HTTP 状态 触发条件
200 翻译成功
400 未上传文件；targetLang 为空；targetLang 不是合法 code（含提交了旧版中文名的情况）
422 字幕解析失败，或解析后内容为空
500 服务端未配置 DEFAULT_API_KEY 且请求未携带 apiKey
502 上游翻译 API 调用失败

非法 targetLang 的错误信息会列出全部有效 code，便于客户端提示，例如：

{
  "success": false,
  "error": "不支持的目标语言代码 \"英语\"，有效代码：zh、en、ja、ko、fr、de、es、ru、pt、it、ar、th、vi"
}

6. 典型集成流程

  1. 拉取语言列表：按客户端 UI 语言请求 GET /api/languages?lang=<ui-lang>，用返回的 {code, name} 渲染下拉框（显示 name，值为 code）。UI 语言应由用户显式选择并持久化，而非固定为中文或读取浏览器语言。
  2. 用户选择目标语言：下拉框选中项的 code 即为待提交的 targetLang。
  3. 提交翻译：POST /api/translate，file 为字幕文件，targetLang 为上一步的 code，按需附带 outputFormat / apiKey 等。
  4. 处理结果：成功后用 data.content 渲染或以 data.filename 提供下载；失败时读取 error 并按状态码分类处理。

翻译基于原文按批次调用上游模型，长字幕会分批处理，整体为同步阻塞请求——文件越长响应越慢，客户端应设置足够长的超时并给用户进度反馈。

7. curl 示例

# 1. 获取语言列表（按英文 UI 本地化显示名）
curl -s 'http://localhost:3000/api/languages?lang=en'

# 2. 翻译为英语（VTT 输出）
curl -X POST http://localhost:3000/api/translate \
  -F "file=@/path/to/subtitle.srt" \
  -F "targetLang=en" \
  -F "apiKey=sk-your-api-key"

# 3. 翻译为中文（SRT 输出，使用服务器默认 Key 与默认模型）
curl -X POST http://localhost:3000/api/translate \
  -F "file=@/path/to/subtitle.vtt" \
  -F "targetLang=zh" \
  -F "outputFormat=srt"

# 4. 大写 code 等价（与 targetLang=en 相同）
curl -X POST http://localhost:3000/api/translate \
  -F "file=@/path/to/subtitle.srt" \
  -F "targetLang=EN"

8. 与 ZWPlayer 对接

ZWPlayer 播放器通过初始化配置项 translateApi 指向翻译服务地址。该参数为服务的 base URL（即两个接口的共同前缀），播放器会在此基础上自动拼接 /languages 与 /translate 两个端点：

const player = new ZWPlayer({
    url: 'http://example.com/vod/movie.mp4',
    playerElm: '#player-holder',
    translateApi: 'https://your-translate-server.com/subtitle-api/api'
});

按上述配置，播放器实际请求的地址为：

  • GET https://your-translate-server.com/subtitle-api/api/languages
  • POST https://your-translate-server.com/subtitle-api/api/translate

配置后，播放器字幕菜单（CC 菜单）会自动出现「字幕翻译」入口，用户选择目标语言即可将当前字幕翻译后作为字幕轨道加载。字幕菜单的完整使用说明请参阅 字幕设置。

8.1 协议兼容性提示

本文档描述的是目标协议规范（使用 ISO 语言 code）。开发者在实现服务端时，需注意 ZWPlayer 客户端实际发送的 targetLang 取值以客户端版本为准：

  • 目标协议要求 targetLang 为语言 code（如 en、zh），并通过 GET /api/languages 获取可选列表。
  • 为保证服务端对各类客户端均健壮，建议在 /api/translate 的语言校验中同时兼容 code 与显示名：既能识别 en，也能兜底识别 英语 / English 这类旧格式输入，给出明确的错误信息（见 §5.4）。

服务端只要满足本文档的请求/响应结构即可被 ZWPlayer 调用。

上一页 快捷键 下一页 协议概述