智能字幕识别

本页印出的枚举值是快照。机器可读的真相源是 枚举清单 —— 两边若有出入，以那份为准。

对音视频进行语音识别，自动生成字幕，并提供多种字幕样式和颜色选择。可选择将字幕渲染烧录到视频中。

本接口支持视频与音频文件两类输入：上传视频可用全部能力；上传音频（例如在本地抽出音频后只传音频，几 GB 的片子降到几十 MB）走同一条识别与字幕链，产出同样的 .ass 字幕、全量转写与内容概括。音频没有画面，烧录（need_render）与去字幕（need_pure）两个参数不可用，详见下方「输入文件与支持格式」。

生成字幕时也可以顺带翻译（translate_language），产出译文或双语字幕。

手上已经有字幕文件了？ 那不必走本能力——重跑一遍语音识别既慢，也会覆盖掉已有的校对结果。 请用智能字幕翻译：它直接吃 .ass / .srt，按字符数计费。

一句话分界：从音视频里认出字幕，用本页；把已有字幕换个语种，用智能字幕翻译。

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

创建任务

基本信息

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

请求参数（Body）

参数名	类型	必填	默认值	说明
file_id	string	是	—	已上传的视频或音频文件 ID，支持格式见下方“输入文件与支持格式”
language	string	是	—	字幕源语言代码，完整列表见下方“支持的语言代码”
translate_language	string	否	—	字幕翻译目标语言代码，支持范围与 language 相同；不填则不翻译
need_render	boolean	否	false	是否将字幕烧录到视频中。仅视频输入可用：音频输入传 true 会在创建任务时被拒绝（HTTP 400，错误码 6016）
need_pure	boolean	否	false	是否先去除原视频中已有的字幕。仅视频输入可用：音频输入传 true 会在创建任务时被拒绝（HTTP 400，错误码 6016）
video_size	array	否	—	原片画布几何 [宽, 高]（两个正整数）。仅音频输入生效：本地抽音频上传时把原片真实尺寸回传，服务端据此选字幕样式档与 ASS 画布（PlayResX/Y）；不传按 1920x1080 兜底（原片宽高比与兜底值不同时，字幕样式档会落错）。视频输入以服务端实测为准，该字段被忽略
lingual_type	string	否	"bilingual"	字幕语言类型：monolingual（单语）/ bilingual（双语，需设置翻译语言），示例见下方“字幕样式示例”
subtitle_type	string	否	"default"	字幕样式：default / outline / cinema_yellow / immersive_box / wide_spacing / deep_shadow / boxed，示例见下方“字幕样式示例”
subtitle_color	string	否	"雅黑"	字幕颜色：雅黑 / 淡绿 / 森林绿 / 湖蓝 / 道奇蓝 / 钢蓝 / 浅粉红 / 深橙 / 珊瑚橙 / 橙红 / 土豪金
strip_punctuation	boolean	否	true	字幕文本去标点开关：缺省去标点（标点在字幕里不好看）——中文 ， 。 与英文 , . 替换为空格，词内形态豁免（小数 3.5、域名 example.com、千分位 1,000 不动），其余标点（引号、问号、感叹号、破折号等）一律保留；连续空格折一、行首尾裁净。只影响字幕文本，时码、行数与其余出参零变化。显式传 false 时完整保留标点
subtitle_format	string	否	"ass"	字幕产物格式：ass 只返回 .ass、srt 只返回 .srt、both 两个都返回。样式参数（subtitle_type / subtitle_color）只作用于 .ass 与烧录视频——.srt 是纯文本时码格式，不承载描边、底框与配色；传 srt 时这两个参数不会报错，但产出的 .srt 无样式。烧录（need_render）恒使用带样式的 .ass，与本参数取值无关。双语时 .srt 是单个文件、每条字幕两行（译文在上、原文在下），不产两个分语种文件。传枚举外的值按缺省 ass 处理，不报错

输入文件与支持格式

本接口同时接受视频与音频两类上传物，服务端按文件后缀自动识别：

输入类型	支持格式
视频	.mp4 .avi .mpg .mov .flv .mxf .mpeg .3gp .wmv .h264 .m4v .ts
音频	.wav .mp3 .m4a .ape .aac .ogg .flac .wma

.ogg 同时是常见的音频与视频容器，本接口一律按音频处理。

音频输入的行为差异（其余参数与产物与视频完全一致）：

• 产物：照常产出 .ass 字幕文件、全量转写 JSON 与内容概括；rendered_file_id 与 pure_file_id（及对应下载链接）恒为空字符串。
• need_render / need_pure 不可用：两者都是画面操作，音频输入传 true 会在创建任务时被拒绝（HTTP 400，错误码 6016，文案点名被拒参数）；显式传 false 或不传均照常受理。
• 建议回传 video_size：音频没有画面可探测，把原片真实 [宽, 高] 一并传入，字幕样式档与画布才与原片对齐。
• 计费同口径：按媒体时长（分钟）计费，与视频一致。

典型用法：对大体积视频，在本地抽出音频后只上传音频，同时回传 video_size——字幕产物与整片上传一致，上传量从几 GB 降到几十 MB。

支持的语言代码

language（识别源语种）与 translate_language（翻译目标语）取自同一张代码表。下表逐码标出两个参数位各自的可用性：

语言代码	语言名称	作 language（识别源语种）	作 translate_language（翻译目标语）
zh-CHT	中文繁体	✅	✅
zh-CHS	中文简体	✅	✅
zh-CN	中文	✅	✅
ja-JP	日文	✅	✅
en-US	英文	✅	✅
es-ES	西班牙文	✅	✅
ru-RU	俄文	✅	✅
ko-KR	韩文	✅	✅
fr-FR	法文	✅	✅
pt-PT	葡萄牙文	✅	✅
vi-VN	越南文	✅	✅

上表 11 项在两个参数位上均可用。传入表外代码会在建单时同步返回错误码 6015，不计费、不排队。

提示：当 lingual_type 为 bilingual 时，建议显式传入 translate_language，并确保它也来自上表。

字幕样式示例

以下展示智能字幕当前支持的全部 7 种 subtitle_type 样式，并覆盖：

• monolingual 与 bilingual
• 1080x1920、1920x1080、2160x3840、3840x2160、480x848、848x480

请求中请直接使用对应的 subtitle_type 参数值。

content 对象（可选）

可通过 content 字段补充视频上下文信息，帮助提升字幕准确率：

参数名	类型	说明
content.video_title	string	视频标题
content.video_info	string	视频内容摘要描述

请求示例

curl -X POST https://api.ai-mcn.tv:10000/task/video_ai_subtitle \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "537489015178246",
    "language": "zh-CN",
    "translate_language": "en-US",
    "need_render": true,
    "lingual_type": "bilingual",
    "subtitle_type": "outline",
    "subtitle_color": "雅黑"
  }'

成功响应示例

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

---

查询任务结果

基本信息

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

响应参数（output_result）

参数名	类型	说明
rendered_file_id	string	烧录字幕后的视频文件 ID（仅 need_render: true 时非空）
rendered_file_download_url	string	烧录视频下载链接
pure_file_id	string	去字幕纯净视频文件 ID（仅 need_pure: true 时非空）
pure_file_download_url	string	纯净视频下载链接
subtitle_file_id	string	ASS 字幕文件 ID。恒指 .ass，语义不随 subtitle_format 变化；传 subtitle_format: "srt" 时该字段为空字符串
subtitle_file_download_url	string	ASS 字幕文件下载链接
srt_file_id	string	SubRip 字幕文件（.srt）ID。subtitle_format 取 srt 或 both 时非空，否则为空字符串
srt_file_download_url	string	SubRip 字幕文件下载链接
summary	string	视频内容概括（不超过 500 字符）
asr_file_id	string	全量转写 JSON 文件 ID（内容含字级时间戳 word_tc_list 与全文 asr_text）
asr_download_url	string	全量转写 JSON 文件下载链接

全量转写落为 JSON 文件返回，不再内联在 output_result 里。产物文件与其他媒体产物 同生命周期（到期自动清理），请在任务完成后及时下载归档。

音频输入时 rendered_file_id / pure_file_id 及对应下载链接恒为空字符串（音频没有画面可烧录/净化）。

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178247",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "rendered_file_id": "537489015178248",
      "rendered_file_download_url": "https://api.ai-mcn.tv:9000/cloud/file/cd/537489015178248.mp4",
      "pure_file_id": "",
      "pure_file_download_url": "",
      "subtitle_file_id": "537489015178249",
      "subtitle_file_download_url": "https://api.ai-mcn.tv:9000/cloud/file/ef/537489015178249.ass",
      "srt_file_id": "",
      "srt_file_download_url": "",
      "summary": "一段关于测试语音的演示视频。",
      "asr_file_id": "537489015178250",
      "asr_download_url": "https://api.ai-mcn.tv:9000/cloud/file/ab/537489015178250.json"
    },
    "create_time": "2026-04-05T08:00:00Z",
    "update_time": "2026-04-05T08:01:30Z"
  }
}

错误码

错误码	HTTP 状态码	说明	解决方案
6013	400	file_id 或 language 缺失	补充必填参数
6015	400	不支持的语言代码	使用上表中的受支持语言代码
6016	400	参数无效：音频输入传了 need_render / need_pure（取 true），或 video_size 形态非法	音频输入去掉这两个参数只产字幕（或改传视频文件）；video_size 传 [宽, 高] 两个正整数
6014	400	文件后缀与本任务类型不匹配	使用「输入文件与支持格式」中列出的视频或音频格式
6004	404	文件不存在	检查 file_id 是否正确
6502	401	鉴权失败	检查 Authorization 请求头
6202	402	余额不足	前往仪表盘充值