AI Subtitle Recognition

The enum values printed on this page are a snapshot. The machine-readable source of truth is the Enum Catalog — where the two disagree, that one wins.

Run speech recognition on audio or video, generate subtitles automatically, and choose from several subtitle styles and colors. Subtitles can optionally be burned into the video.

This API supports both video and audio files as input. A video upload gets the full feature set; an audio upload (for example, audio extracted locally so a multi-GB source shrinks to tens of MB) goes through the same recognition and subtitle pipeline and produces the same .ass subtitle file, full transcription, and content summary. Audio has no picture, so the burn-in (need_render) and subtitle-removal (need_pure) parameters are unavailable — see "Input Files and Supported Formats" below.

Subtitles can also be translated in the same pass (translate_language), producing translated or bilingual subtitles.

Already have a subtitle file? You do not need this capability — re-running speech recognition is slower and would discard your existing proofreading. Use AI Subtitle Translation instead: it takes .ass / .srt directly and is billed per character.

In one line: use this page to recognize subtitles from audio or video; use AI Subtitle Translation to move existing subtitles into another language.

⚠️ Behavior change (2026-08-22): As of 2026-08-22, this API strips Chinese and English commas and periods from subtitle text by default (strip_punctuation defaults to true, see the parameter table below), so identical requests produce different subtitle text than before the upgrade; timecodes, line counts, and all other output fields are unchanged. To keep the previous behavior, pass strip_punctuation: false explicitly.

Create Task

Basic Information

Item	Value
Request Method	POST
Request Path	/task/video_ai_subtitle
Content-Type	application/json
Authentication	Raw API key in the Authorization header

Request Body

Parameter	Type	Required	Default	Description
file_id	string	Yes	-	Uploaded video or audio file ID. See "Input Files and Supported Formats" below
language	string	Yes	-	Subtitle source language code. See the full supported list below
translate_language	string	No	-	Subtitle target language code for translation. It uses the same supported set as language
need_render	boolean	No	false	Whether to burn subtitles into the video. Video input only: passing true with an audio input is rejected at task creation (HTTP 400, error code 6016)
need_pure	boolean	No	false	Whether to remove existing subtitles before generating new ones. Video input only: passing true with an audio input is rejected at task creation (HTTP 400, error code 6016)
video_size	array	No	-	Source canvas geometry [width, height] (two positive integers). Effective for audio input only: when uploading locally extracted audio, pass the source video's real dimensions so the server picks the matching subtitle style tier and ASS canvas (PlayResX/Y); without it the server falls back to 1920x1080 (a source with a different aspect ratio will land on the wrong style tier). For video input the probed dimensions win and this field is ignored
lingual_type	string	No	"bilingual"	monolingual or bilingual. See the gallery below for examples
subtitle_type	string	No	"default"	Subtitle style preset: default, outline, cinema_yellow, immersive_box, wide_spacing, deep_shadow, or boxed. See the gallery below for examples
subtitle_color	string	No	"雅黑"	Subtitle color preset: 雅黑, 淡绿, 森林绿, 湖蓝, 道奇蓝, 钢蓝, 浅粉红, 深橙, 珊瑚橙, 橙红, or 土豪金
strip_punctuation	boolean	No	true	Punctuation stripping for subtitle text: stripping is on by default (punctuation looks poor in subtitles) — Chinese ， 。 and English , . are replaced with spaces, in-word forms are exempt (decimals 3.5, domains example.com, thousands separators 1,000 stay intact), and all other punctuation (quotes, question marks, exclamation marks, dashes, etc.) is kept; consecutive spaces collapse to one and line edges are trimmed. Only the subtitle text is affected — timecodes, line counts, and all other output fields are unchanged. Pass false explicitly to keep punctuation intact
subtitle_format	string	No	"ass"	Subtitle output format: ass returns only .ass, srt returns only .srt, both returns both. Style parameters (subtitle_type / subtitle_color) affect the .ass file and the burned-in video only — .srt is a plain-text timecode format and carries no outline, box, or color. Passing them alongside srt is not an error, but the resulting .srt has no styling. Burn-in (need_render) always uses the styled .ass regardless of this setting. For bilingual output the .srt is a single file with two lines per cue (translation on top, source below) rather than two per-language files. Values outside the enum fall back to the default ass without an error

Input Files and Supported Formats

This API accepts both video and audio uploads; the server detects the type from the file extension:

Input type	Supported formats
Video	.mp4 .avi .mpg .mov .flv .mxf .mpeg .3gp .wmv .h264 .m4v .ts
Audio	.wav .mp3 .m4a .ape .aac .ogg .flac .wma

.ogg is a common container for both audio and video; this API always treats it as audio.

Behavior differences for audio input (all other parameters and outputs match video exactly):

• Outputs: the .ass subtitle file, full transcription JSON, and content summary are produced as usual; rendered_file_id and pure_file_id (and their download URLs) are always empty strings.
• need_render / need_pure unavailable: both are picture operations. Passing true with an audio input is rejected at task creation (HTTP 400, error code 6016, with the rejected parameters named in the message); passing false explicitly, or omitting them, is accepted as usual.
• Pass video_size when you can: audio has no picture to probe, so send the source video's real [width, height] to keep the subtitle style tier and canvas aligned with the source.
• Same billing: billed by media duration in minutes, identical to video.

Typical usage: for a large video, extract the audio locally and upload only the audio together with video_size — the subtitle output matches a full-video upload while the upload shrinks from several GB to tens of MB.

Supported Language Codes

language (the source language for recognition) and translate_language (the translation target language) are drawn from the same code table, but their available sets differ — recognition requires a matching speech recognition engine, translation does not. The table below marks availability per parameter:

Language code	Language name	As language (source language)	As translate_language (translation target)
zh-CHT	Traditional Chinese	✅	✅
zh-CHS	Simplified Chinese	✅	✅
zh-CN	Chinese	✅	✅
ja-JP	Japanese	✅	✅
en-US	English	✅	✅
es-ES	Spanish	✅	✅
ru-RU	Russian	✅	✅
ko-KR	Korean	✅	✅
fr-FR	French	✅	✅
pt-PT	Portuguese	✅	✅
vi-VN	Vietnamese	✅	✅

All 11 codes above are usable in both parameter positions. Passing a code outside the table returns error code 6015 synchronously at submission — no charge, no queueing.

Tip: When lingual_type is bilingual, explicitly pass translate_language and make sure it also comes from the list above.

Subtitle Style Gallery

The gallery below covers all 7 currently supported subtitle_type presets, with examples for:

• monolingual and bilingual
• 1080x1920, 1920x1080, 2160x3840, 3840x2160, 480x848, and 848x480

Use the matching subtitle_type parameter value shown in each style section.

Optional content Object

You can pass extra context through content to improve subtitle accuracy.

Parameter	Type	Description
content.video_title	string	Video title
content.video_info	string	Summary or description of the video

Request Example

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": "雅黑"
  }'

Success Example

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

---

Query Task Result

Basic Information

Item	Value
Request Method	GET
Request Path	/task/video_ai_subtitle/{task_id}
Authentication	Raw API key in the Authorization header

Output Result (output_result)

Parameter	Type	Description
rendered_file_id	string	Video file ID with burned-in subtitles, non-empty only when need_render: true
rendered_file_download_url	string	Download URL of the rendered video
pure_file_id	string	Cleaned (subtitle-removed) video file ID, non-empty only when need_pure: true
pure_file_download_url	string	Download URL of the cleaned video
subtitle_file_id	string	ASS subtitle file ID. Always refers to the .ass file; its meaning does not change with subtitle_format. Empty string when subtitle_format is srt
subtitle_file_download_url	string	Download URL of the ASS subtitle file
srt_file_id	string	SubRip (.srt) subtitle file ID. Non-empty when subtitle_format is srt or both, empty string otherwise
srt_file_download_url	string	Download URL of the SubRip subtitle file
summary	string	Video content summary (at most 500 characters)
asr_file_id	string	File ID of the full transcription JSON (word-level timestamps word_tc_list plus full text asr_text)
asr_download_url	string	Download URL of the full transcription JSON

The full transcription is delivered as a JSON file instead of being inlined in output_result. Output files share the same lifecycle as other media outputs (cleaned up on expiry); download and archive them promptly after the task completes.

For audio input, rendered_file_id / pure_file_id and their download URLs are always empty strings (audio has no picture to burn into or clean up).

Success Example

{
  "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": "A short demo video about the test clip.",
      "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"
  }
}

Error Codes

Error Code	HTTP Status	Description	Resolution
6013	400	Missing file_id or language	Add the required fields
6015	400	Unsupported language code	Use one of the supported language codes listed above
6016	400	Invalid parameters: need_render / need_pure passed as true with an audio input, or malformed video_size	For audio input, drop the two parameters to get subtitles only (or upload a video instead); pass video_size as two positive integers [width, height]
6014	400	File extension does not match this task type	Use a video or audio format listed under "Input Files and Supported Formats"
6004	404	File not found	Verify the file_id
6502	401	Authentication failed	Check the Authorization header
6202	402	Insufficient balance	Recharge in the Dashboard