智能字幕翻译

把已有的字幕文件翻译成另一种语言，可选套用平台自带的字幕样式与颜色，也可输出双语字幕。

本能力不做语音识别、不接受音视频输入。要从视频或音频里生成字幕，请用智能字幕识别。

	智能字幕识别	智能字幕翻译（本页）
输入	音视频文件	字幕文件 `.ass` / `.srt`
做什么	语音识别生成字幕（可顺带翻译）	翻译已有字幕
计费	按视频分钟数	按字符数（千字符）

手上已经有校对好的字幕、想换个语种时用本能力：不必重跑语音识别，也不会覆盖掉已有的校对结果。

⚠️ 行为变更公告（2026-08-22）：自 2026-08-22 起，本接口默认去除译文字幕文本中的中英逗号句号（strip_punctuation 缺省 true，见下方参数说明），相同请求产出的字幕文本会与升级前不同；时码、行数与其余出参零变化。需要升级前的旧行为，请显式传 strip_punctuation: false。

创建任务

基本信息

项目	值
请求方法	`POST`
请求路径	`/task/subtitle_translate`
Content-Type	`application/json`
鉴权方式	`Authorization` 请求头（直接传 API Key）

请求参数（Body）

参数名	类型	必填	默认值	说明
`file_id`	`string`	是	—	已上传字幕文件的 ID。仅支持 `.ass` / `.srt`，提交音视频文件会被拒绝
`language`	`string`	是	—	字幕源语言代码，完整列表见下方“支持的语言代码”
`translate_language`	`string`	是	—	翻译目标语言代码，支持范围与 `language` 相同
`output_format`	`string`	否	跟随输入	产物格式：`ass` / `srt`。不填时 `.ass` 进 `.ass` 出、`.srt` 进 `.srt` 出
`line_mode`	`string`	否	`"resegment"`	翻译粒度，见下方“翻译粒度”
`lingual_type`	`string`	否	`"monolingual"`	`monolingual`（单语）/ `bilingual`（双语，原文与译文同框）。仅 `ass` 输出有效
`subtitle_type`	`string`	否	`"default"`	字幕样式：`default` / `outline` / `cinema_yellow` / `immersive_box` / `wide_spacing` / `deep_shadow` / `boxed`。仅 `ass` 输出有效
`subtitle_color`	`string`	否	`"雅黑"`	字幕颜色：`雅黑` / `淡绿` / `森林绿` / `湖蓝` / `道奇蓝` / `钢蓝` / `浅粉红` / `深橙` / `珊瑚橙` / `橙红` / `土豪金`。仅 `ass` 输出有效
`video_size`	`array`	否	`[1920, 1080]`	画布几何 `[宽, 高]`，决定译文按哪一档折行。见下方“画布几何”
`strip_punctuation`	`boolean`	否	`true`	字幕文本去标点开关：缺省去标点（标点在字幕里不好看）——中文 `，` `。` 与英文 `,` `.` 替换为空格，词内形态豁免（小数 `3.5`、域名 `example.com`、千分位 `1,000` 不动），其余标点（引号、问号、感叹号、破折号等）一律保留；连续空格折一、行首尾裁净。只影响字幕文本，时码、行数与其余出参零变化。显式传 `false` 时完整保留标点

支持的语言代码

language 与 translate_language 使用与智能字幕识别同一组语言代码，支持以下 11 种语言互译：

语言代码	语言名称
`zh-CHT`	中文繁体
`zh-CHS`	中文简体
`zh-CN`	中文
`ja-JP`	日文
`en-US`	英文
`es-ES`	西班牙文
`ru-RU`	俄文
`ko-KR`	韩文
`fr-FR`	法文
`pt-PT`	葡萄牙文
`vi-VN`	越南文

翻译粒度（`line_mode`）

字幕文件里的一句话经常被拆在相邻几行里。怎么处理这些断行，决定了译文的通顺程度与时间轴能否保持原样——两者不可兼得，按需要选。

取值	做法	得到什么	代价
`resegment`（默认）	先把相邻字幕行合并回自然句再翻译，然后按目标语言重新断行	译文更通顺，断句符合目标语言习惯	行数与时间轴会变，不再与输入一一对应
`keep`	严格逐行翻译，不跨行合并	时间轴与输入逐条一致，可直接替换原字幕轨	逐行翻译缺少上下文，且会保留原有的短行间空隙

要把译文轨直接套回既有剪辑工程、时间码必须对得上时，用 keep；只是想要一份读起来顺的译文字幕，用默认的 resegment。

画布几何（`video_size`）

译文的长度与原文往往不同，需要按画面宽度重新折行，因此需要知道画布尺寸。取值优先级：

本参数 video_size
.ass 文件头里的 PlayRes
服务端缺省 1920x1080（横屏）

.srt 文件里没有画布信息，无法从文件推断。竖屏场景请务必显式传入 video_size，否则会按横屏折行，行偏长、可能超出画面。

字幕样式与格式的关系

subtitle_type / subtitle_color / lingual_type 三个参数都靠 ASS 格式承载，SRT 格式本身不携带样式信息。

因此当 output_format 为 srt 时若同时传了这三者中的任意一个，请求会在创建任务阶段就被拒绝，不产生扣费。

判断依据是输出格式，不是输入格式。用 .srt 作输入、请求 ass 输出并套样式，是完全合法的组合——这正是把纯文本字幕升级成带样式字幕的常规用法。

规模上限

单次任务的字幕规模有上限，超出会在创建任务阶段被拒绝且不扣费：

维度	上限
字幕条数	`2000` 条
总字符数	`80000` 字符
文件体积	`8 MB`

超出时请拆分后分批提交。作为参照：一部 90 分钟影片的字幕通常在 1200–1800 条之间。

请求示例

curl -X POST https://api.ai-mcn.tv:10000/task/subtitle_translate \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "537489015178246",
    "language": "zh-CN",
    "translate_language": "en-US",
    "output_format": "ass",
    "line_mode": "resegment",
    "lingual_type": "bilingual",
    "subtitle_type": "boxed",
    "subtitle_color": "珊瑚橙",
    "video_size": [1920, 1080]
  }'

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178247",
    "task_type": "subtitle_translate",
    "status": "queued"
  }
}

查询任务结果

基本信息

项目	值
请求方法	`GET`
请求路径	`/task/subtitle_translate/{task_id}`
鉴权方式	`Authorization` 请求头（直接传 API Key）

响应参数（output_result）

参数名	类型	说明
`subtitle_file_id`	`string`	译文字幕文件 ID
`subtitle_file_download_url`	`string`	译文字幕下载链接
`output_format`	`string`	实际产物格式（`ass` / `srt`）
`line_mode`	`string`	实际使用的翻译粒度
`stats`	`object`	条数统计，见下
`degraded`	`object`	降级标记，见下

stats 对象

参数名	类型	说明
`input_lines`	`integer`	输入字幕条数
`output_lines`	`integer`	产物字幕条数（`resegment` 下与输入不同属正常）
`skipped_total`	`integer`	各环节跳过条目的合计

skipped_total 含读入时丢弃的零时长条目与畸形块、重折行后新产生的零时长条目、以及写出时的空文本段。该值不为 0 时建议核对产物。

degraded 对象

三个布尔标记，任一为 true 表示本次产物存在可感知但不报错的质量差异，可据此决定是否重跑：

参数名	含义
`summary`	上下文摘要求取失败，全篇术语一致性可能下降
`width_budget`	渲染宽度预算算不出，本次仅按语义长度折行，个别行可能超出画面
`translation`	翻译链路退化到分片重试或机器翻译兜底，译文质量可能下降

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178247",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "subtitle_file_id": "537489015178249",
      "subtitle_file_download_url": "https://api.ai-mcn.tv:9000/cloud/file/ef/537489015178249.ass",
      "output_format": "ass",
      "line_mode": "resegment",
      "stats": {
        "input_lines": 420,
        "output_lines": 386,
        "skipped_total": 2
      },
      "degraded": {
        "summary": false,
        "width_budget": false,
        "translation": false
      }
    },
    "create_time": "2026-04-05T08:00:00Z",
    "update_time": "2026-04-05T08:01:30Z"
  }
}

计费

按字符数计费，单价 1 积分 / 千字符。

计费单位数 = 字幕总字符数 ÷ 1000（保留小数）
字符数按 Unicode 码点计，一个中日韩字符算 1 个字符
最终扣费向上取整到整积分，任何非空字幕至少 1 积分

字幕总字符数	扣费
1000	1 积分
1500	2 积分
50000	50 积分
80000（上限）	80 积分

计费只统计字幕正文字符，时间码与序号不计入。所有在创建任务阶段被拒绝的请求（参数错误、格式冲突、超出规模上限、字幕文件无法采纳）均不扣费。

错误码

错误码	HTTP 状态码	说明	解决方案
`6013`	400	缺少 `file_id` / `language` / `translate_language`	补充必填参数
`6014`	400	文件类型不匹配	本能力只接受 `.ass` / `.srt`；音视频请改用智能字幕识别
`6016`	400	参数取值非法、`srt` 输出与样式冲突、超出规模上限，或字幕文件无法采纳（空文件 / 畸形 / 多层双语字幕）	按错误信息调整，均不扣费
`5202`	404	文件不存在	检查 `file_id` 是否正确
`6502`	401	鉴权失败	检查 `Authorization` 请求头
`6201`	402	余额不足	前往仪表盘充值

若提交的是双语字幕（同一时间区间有两条字幕），会被拒绝：无法可靠判断哪一层是原文，猜错会把译文当原文再翻一遍。请先拆分出需要翻译的那一层。

智能字幕翻译

创建任务

基本信息

请求参数（Body）

支持的语言代码

翻译粒度（line_mode）

画布几何（video_size）

字幕样式与格式的关系

规模上限

请求示例

成功响应示例

查询任务结果

基本信息

响应参数（output_result）

stats 对象

degraded 对象

成功响应示例

计费

错误码

翻译粒度（`line_mode`）

画布几何（`video_size`）