Subtitle Processing
On this page
영상에서 음성 인식(ASR) 또는 화면 텍스트 인식(OCR)으로 자막을 생성하고, 30개 이상의 언어로 번역합니다. VTT/SRT 자막 파일 출력과 이중 자막(원문+번역)을 지원합니다.
API 정보
| 항목 | 값 |
|---|---|
| 서비스 | MPS |
| API Action | ProcessMedia |
| 엔드포인트 | mps.tencentcloudapi.com |
| API 버전 | 2019-06-12 |
| 처리 방식 | 비동기 (TaskId 발급 후 결과 조회) |
인증은 모든 API가 공통으로 TC3-HMAC-SHA256(SecretId/SecretKey) 서명을 사용합니다. 서명 생성 방법은 Quick Start의 TokenHub 문서를 참고하세요.
결과 조회는 DescribeTaskDetail 또는 완료 콜백으로 받을 수 있습니다.
요청 파라미터
| 파라미터 | 타입 | 필수 | 예시 | 설명 |
|---|---|---|---|---|
| InputInfo | Object | 필수 | {"Type":"COS","CosInputInfo":{"Bucket":"mybucket-125xxx","Region":"ap-guangzhou","Object":"/input/video.mp4"}} |
입력 미디어 정보. Type은 URL 또는 COS |
| OutputStorage | Object | 선택 | {"Type":"COS","CosOutputStorage":{"Bucket":"mybucket-125xxx","Region":"ap-guangzhou"}} |
출력 저장소. COS Bucket과 Region 지정 |
| OutputDir | String | 선택 | /output/subtitle/ |
출력 디렉터리. /로 시작하고 /로 끝나야 함 |
| SmartSubtitlesTask.Definition | Integer | 조건부 필수 | 110167 |
프리셋 모드의 템플릿 ID. 커스텀 모드는 0으로 지정 |
| SmartSubtitlesTask.RawParameter | Object | 조건부 필수 | 아래 호출 예시 참조 | 커스텀 자막 파라미터. Definition=0과 함께 사용하거나 Definition 모드에서 오버라이드 용도로 사용 |
| RawParameter.ProcessType | Integer | 필수 | 0 |
처리 유형. 0=ASR 음성 인식, 1=순수 번역, 2=OCR 화면 텍스트 인식 |
| RawParameter.VideoSrcLanguage | String | 필수 | zh |
영상 원어. ASR 기본 zh, 순수 번역 기본 auto, OCR 기본 zh_en. ASR 지원: zh / en / ja / ko / zh-PY / yue / zh_dialect / prime_zh / vi / ms / id / th / fr / de / es / pt / ru / ar 등. OCR 지원: zh_en / multi |
| RawParameter.TranslateSwitch | String | 선택 | ON |
번역 활성화 여부. ON / OFF |
| RawParameter.TranslateDstLanguage | String | 번역 시 필수 | en/ja |
번역 대상 언어. /로 구분해 다중 지정 가능. zh / en / ja / ko / fr / es / de / it / ru / pt / ar / th / vi / id / ms / tr / nl / pl / sv 등 30개 이상 지원 |
| RawParameter.SubtitleType | Integer | 선택 | 2 |
자막 언어 유형. 0=원어, 1=번역어, 2=이중 자막(번역 활성화 시 기본) |
| RawParameter.SubtitleFormat | String | 선택 | vtt |
자막 파일 포맷. vtt / srt / original |
| RawParameter.AsrHotWordsConfigure | Object | 선택 | {"Switch":"ON","LibraryId":"hwd-xxxxx"} |
ASR 핫워드 라이브러리. 전문 용어 인식률 향상 |
| RawParameter.SelectingSubtitleAreasConfig | Object | 선택 | {"AutoAreas":[{"LeftTopX":0,"LeftTopY":0.7,"RightBottomX":1,"RightBottomY":1,"Unit":1}],"SampleWidth":1920,"SampleHeight":1080} |
OCR 인식 영역(0~1 비율 좌표). SampleWidth/SampleHeight는 샘플 영상 크기(픽셀) |
| RawParameter.ExtInfo | String | 선택 | - | 확장 정보(JSON 문자열, 고급 옵션) |
| SmartSubtitlesTask.UserExtPara | String | 선택 | - | 사용자 정의 확장 파라미터(JSON 문자열, 고급 옵션) |
| SmartSubtitlesTask.OutputObjectPath | String | 선택 | /output/{inputName}_subtitle.{format} |
출력 자막 파일 경로 |
| TaskNotifyConfig.NotifyUrl | String | 선택 | https://example.com/callback |
태스크 완료 콜백 URL. NotifyType은 URL |
응답 파라미터
| 파라미터 | 타입 | 필수 | 예시 | 설명 |
|---|---|---|---|---|
| TaskId | String | 항상 | 1250017490-20260318152230-abcdef123456 |
발급된 태스크 ID. 결과 조회에 사용 |
| RequestId | String | 항상 | 3c140219-cfe9-470e-b241-907877d6fb03 |
요청 식별자 |
호출 예시
LANGUAGE
import json
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.mps.v20190612 import mps_client, models
cred = credential.Credential("<SecretId>", "<SecretKey>")
http_profile = HttpProfile()
http_profile.endpoint = "mps.tencentcloudapi.com"
client = mps_client.MpsClient(cred, "ap-guangzhou", ClientProfile(httpProfile=http_profile))
# ASR + 영어 번역(이중 자막, VTT)
params = {
"InputInfo": {
"Type": "URL",
"UrlInputInfo": {"Url": "https://example.com/video.mp4"}
},
"OutputStorage": {
"Type": "COS",
"CosOutputStorage": {"Bucket": "mybucket-125xxx", "Region": "ap-guangzhou"}
},
"OutputDir": "/output/subtitle/",
"SmartSubtitlesTask": {
"Definition": 0,
"RawParameter": {
"ProcessType": 0,
"VideoSrcLanguage": "zh",
"TranslateSwitch": "ON",
"TranslateDstLanguage": "en",
"SubtitleType": 2,
"SubtitleFormat": "vtt"
}
}
}
req = models.ProcessMediaRequest()
req.from_json_string(json.dumps(params))
resp = client.ProcessMedia(req)
print(resp.to_json_string())LANGUAGE
# OCR 하드 자막 인식 + 영어/일본어 다중 번역
params["SmartSubtitlesTask"] = {
"Definition": 0,
"RawParameter": {
"ProcessType": 2,
"VideoSrcLanguage": "zh_en",
"TranslateSwitch": "ON",
"TranslateDstLanguage": "en/ja",
"SubtitleType": 2,
"SubtitleFormat": "vtt"
}
}응답 예시
LANGUAGE
{
"TaskId": "1250017490-20260318152230-abcdef123456",
"RequestId": "3c140219-cfe9-470e-b241-907877d6fb03"
}사용 안내
번역 언어는 TranslateDstLanguage에 지정하며 여러 언어는 en/ja처럼 /로 구분합니다. 번역 모드의 기본 SubtitleType은 2(이중 자막)입니다.
ProcessType 선택 기준: 음성 내용을 텍스트로 변환하면 0(ASR), 화면에 박힌 자막/텍스트를 인식하면 2(OCR, 원어는 zh_en 또는 multi), 기존 자막 번역만 필요하면 1입니다. ASR에 번역을 얹으려면 ProcessType 0에 TranslateSwitch를 ON으로 설정합니다.
OCR 인식 영역 좌표는 0~1 사이 비율 값이며, SelectingSubtitleAreasConfig에 여러 영역을 지정할 수 있습니다. 결과 자막 파일은 태스크 완료 후 OutputDir에 기록되며 Task Query로 진행 상태를 조회합니다.