Subtitle Burn-in

Burn an existing subtitle file (.srt / .ass) into a video's picture and get the video with subtitles.

This capability does not perform speech recognition. To recognize subtitles from a video and burn them in, use AI Subtitle Recognition; to translate subtitles into another language first, use AI Subtitle Translation.

	AI Subtitle Recognition	AI Subtitle Translation	Subtitle Burn-in (this page)
Input	Audio or video	Subtitle file	Video + subtitle file
Output	Recognized subtitles (optionally burned in)	Translated subtitles	Video with burned-in subtitles
Billing	Per video minute	Per 1,000 characters	Per video minute

Use this capability when you already have proofread subtitles: they are burned in as they are, never re-recognized or rewritten.

Create Task

Basic Information

Item	Value
Method	POST
Path	/task/video_subtitle_burn
Content-Type	application/json
Auth	Authorization header (the API key itself)

Request Body

Parameter	Type	Required	Default	Description
file_id	string	Yes	—	ID of an uploaded video, up to 120 minutes
subtitle_file_id	string	Yes	—	ID of an uploaded subtitle file, .srt or .ass only, up to 8 MB, with at least one valid cue
subtitle_type	string	No	"default"	Subtitle style: default / outline / cinema_yellow / immersive_box / wide_spacing / deep_shadow / boxed. SRT only
subtitle_color	string	No	The style's own color	Outline color (box color for boxed): 雅黑 / 淡绿 / 森林绿 / 湖蓝 / 道奇蓝 / 钢蓝 / 浅粉红 / 深橙 / 珊瑚橙 / 橙红 / 土豪金. SRT only

How SRT and ASS Are Handled

Input	How it is burned in
.srt	An ASS is generated with the platform style chosen by subtitle_type / subtitle_color, sized to the video's actual width and height (landscape and portrait have their own font sizes and margins), then burned in. Line breaks inside a cue are kept, so bilingual SRT (two lines per cue) shows as two lines
.ass	Burned in with the file's own styles; subtitle_type / subtitle_color have no effect. Bilingual or layered ASS can be burned in directly. Fonts the file names but the server doesn't have are replaced with Source Han Sans (otherwise CJK text may show as boxes); see font_replaced in the result

For both inputs the result includes the .ass actually used for burning, so you can check styles and line breaks.

Request Example

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": "湖蓝"
  }'

Success Example

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

---

Query Task Result

Basic Information

Item	Value
Method	GET
Path	/task/video_subtitle_burn/{task_id}
Auth	Authorization header (the API key itself)

Response Fields (output_result)

Field	Type	Description
file_id	string	File ID of the video with burned-in subtitles
download_url	string	Download URL of that video
subtitle_file_id	string	File ID of the .ass actually used (for SRT input, the generated one)
subtitle_file_download_url	string	Download URL of that .ass
input_format	string	Input subtitle format: srt / ass
font_replaced	array	For ASS input, font names replaced with Source Han Sans because the server lacks them (up to 10; empty when nothing was replaced)
font_check	string	Font check: checked = checked against the server's fonts; skipped = the font list was unavailable, burned in as is; not_applicable = SRT input, fonts come from the style

Success Example

{
  "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"
  }
}

Billing

Billed by video length at 1 credit per minute, prorated and rounded up, at least 1 credit per task. The subtitle file is not billed.

Requests rejected at task creation (bad parameters, wrong file type, video too long, subtitle file too large or unreadable) are not charged; failed tasks are refunded automatically.

Error Codes

Code	HTTP Status	Description	Solution
6013	400	Missing file_id / subtitle_file_id	Add the required parameters
6014	400	File type mismatch: file_id is not a video, or subtitle_file_id is not .srt / .ass	Check whether the two files are swapped
6016	400	Invalid value (style or color not in the list), video longer than 120 minutes, subtitle file over 8 MB or with no readable cues	Adjust as the message says; never charged
6004	404	File not found	Check the file IDs
6502	401	Authentication failed	Check the Authorization header
6201	402	Insufficient balance	Top up in the dashboard