字幕烧录

把已有的字幕文件（.srt / .ass）烧进视频画面，输出带字幕的视频。

不想写代码？在同合智创工具箱里直接上传文件处理，登录即用，结果与本接口一致。打开「字幕压制」→

本能力不做语音识别。要从视频里识别字幕并烧录，请用智能字幕识别；要先把字幕换成另一种语言，请用智能字幕翻译。

	智能字幕识别	智能字幕翻译	字幕烧录（本页）
输入	音视频	字幕文件	视频 + 字幕文件
产出	识别出的字幕（可烧录）	译文字幕	烧好字幕的视频
计费	按视频分钟数	按千字符	按视频分钟数

手上已经有校对好的字幕时用本能力：字幕原样烧录，不会被重新识别或改写。

创建任务

基本信息

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

请求参数（Body）

参数名	类型	必填	默认值	说明
`file_id`	`string`	是	—	已上传视频的 ID，时长不超过 120 分钟
`subtitle_file_id`	`string`	是	—	已上传字幕文件的 ID，仅支持 `.srt` / `.ass`，不超过 8 MB，至少有一条有效字幕
`subtitle_type`	`string`	否	`"default"`	字幕样式：`default` / `outline` / `cinema_yellow` / `immersive_box` / `wide_spacing` / `deep_shadow` / `boxed`。只对 SRT 生效
`subtitle_color`	`string`	否	样式自带颜色	描边颜色（`boxed` 样式里是底框颜色）：`雅黑` / `淡绿` / `森林绿` / `湖蓝` / `道奇蓝` / `钢蓝` / `浅粉红` / `深橙` / `珊瑚橙` / `橙红` / `土豪金`。只对 SRT 生效

SRT 与 ASS 的处理

输入	怎么烧
`.srt`	按 `subtitle_type` / `subtitle_color` 选定的平台样式，结合视频实际宽高（横屏、竖屏各有一套字号与边距）生成 ASS 后烧录。一条字幕里的换行会保留，双语 SRT（每条两行）按两行显示
`.ass`	按文件自带的样式烧录，`subtitle_type` / `subtitle_color` 不生效；双语或多层 ASS 可以直接烧。文件里指定、而服务器上没有的字体会换成思源黑体（否则中日韩文字可能显示成方块），换了哪些见结果里的 `font_replaced`

两种输入都会在结果里给出实际烧录用的 .ass，方便核对样式与断行。

请求示例

curl -X POST https://api.ai-mcn.tv:10000/task/video_subtitle_burn \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "537489015178246",
    "subtitle_file_id": "537489015178247",
    "subtitle_type": "boxed",
    "subtitle_color": "湖蓝"
  }'

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178248",
    "task_type": "video_subtitle_burn",
    "status": "queued"
  }
}

查询任务结果

基本信息

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

响应参数（output_result）

参数名	类型	说明
`file_id`	`string`	烧录后的视频文件 ID
`download_url`	`string`	烧录后的视频下载链接
`subtitle_file_id`	`string`	实际烧录所用的 `.ass` 文件 ID（SRT 输入时是按样式生成的那份）
`subtitle_file_download_url`	`string`	实际烧录所用的 `.ass` 下载链接
`input_format`	`string`	输入字幕格式：`srt` / `ass`
`font_replaced`	`array`	ASS 输入时，因服务器上没有而换成思源黑体的字体名（最多 10 个；没有替换为空数组）
`font_check`	`string`	字体核对情况：`checked` 已按服务器字体核对；`skipped` 没取到字体清单，按原样烧录；`not_applicable` SRT 输入，字体由样式决定

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178248",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "file_id": "537489015178249",
      "download_url": "https://api.ai-mcn.tv:9000/cloud/file/ba/537489015178249.mp4",
      "subtitle_file_id": "537489015178250",
      "subtitle_file_download_url": "https://api.ai-mcn.tv:9000/cloud/file/5a/537489015178250.ass",
      "input_format": "ass",
      "font_replaced": ["MyFancyFont"],
      "font_check": "checked"
    },
    "create_time": "2026-10-21T05:33:01Z",
    "update_time": "2026-10-21T05:33:14Z"
  }
}

计费

按视频时长计费，单价 1 积分 / 分钟，按实际时长折算后向上取整，每个任务至少 1 积分。字幕文件不计费。

所有在创建任务阶段被拒绝的请求（参数错误、文件类型不对、视频超时长、字幕文件过大或读不出）均不扣费；处理失败自动退回。

错误码

错误码	HTTP 状态码	说明	解决方案
`6013`	400	缺少 `file_id` / `subtitle_file_id`	补充必填参数
`6014`	400	文件类型不匹配：`file_id` 不是视频，或 `subtitle_file_id` 不是 `.srt` / `.ass`	检查两个文件是否传反
`6016`	400	参数取值非法（样式、颜色不在列表里）、视频超过 120 分钟、字幕文件超过 8 MB 或读不出有效字幕	按错误信息调整，均不扣费
`6004`	404	文件不存在	检查文件 ID 是否正确
`6502`	401	鉴权失败	检查 `Authorization` 请求头
`6201`	402	余额不足	前往仪表盘充值