Subtitle - WAND Documentation

영상에서 음성 인식(ASR) 또는 화면 텍스트 인식(OCR)으로 자막을 생성하고, 30개 이상의 언어로 번역합니다. VTT/SRT 자막 파일 출력과 이중 자막(원문+번역)을 지원합니다.

요청 방법

항목	값
API Action	`ProcessMedia`
엔드포인트	`mps.tencentcloudapi.com`
API 버전	`2019-06-12`
인증	TC3-HMAC-SHA256 (SecretId/SecretKey 서명)
요청 방식	HTTP POST, JSON

비동기 태스크입니다. 호출 즉시 TaskId가 발급되며, 결과는 DescribeTaskDetail로 조회하거나 TaskNotifyConfig로 완료 콜백을 받을 수 있습니다.

요청 파라미터

파라미터	타입	필수 여부	예시	설명
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. RawParameter를 쓰지 않을 때 필수. 커스텀 모드에서는 `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`	요청 식별자

호출 예시

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())

# OCR 하드 자막 인식 + 영어/일본어 다중 번역
params["SmartSubtitlesTask"] = {
    "Definition": 0,
    "RawParameter": {
        "ProcessType": 2,
        "VideoSrcLanguage": "zh_en",
        "TranslateSwitch": "ON",
        "TranslateDstLanguage": "en/ja",
        "SubtitleType": 2,
        "SubtitleFormat": "vtt"
    }
}

응답 예시

{
  "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로 진행 상태를 조회합니다.

Last modified on August 16, 2026

⌘I