> ## Documentation Index > Fetch the complete documentation index at: https://wand.tencentpoc.com/llms.txt > Use this file to discover all available pages before exploring further. # Subtitle > 자막 추출, 번역, 음성 인식(ASR), OCR 자막 인식 API Reference 영상에서 음성 인식(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` | 요청 식별자 | ## 호출 예시 ```python theme={null} 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("", "") 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()) ``` ```python theme={null} # OCR 하드 자막 인식 + 영어/일본어 다중 번역 params["SmartSubtitlesTask"] = { "Definition": 0, "RawParameter": { "ProcessType": 2, "VideoSrcLanguage": "zh_en", "TranslateSwitch": "ON", "TranslateDstLanguage": "en/ja", "SubtitleType": 2, "SubtitleFormat": "vtt" } } ``` ## 응답 예시 ```json theme={null} { "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](/mps/task-query)로 진행 상태를 조회합니다.