> ## 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. # Orientation Conversion > 가로/세로 영상 비율 양방향 지능 변환 API Reference 기존 영상의 화면 방향을 양방향으로 변환합니다. 가로에서 세로(알고리즘 2/3/5/6), 세로에서 가로(알고리즘 7)를 지원합니다. 단순 회전이 아니라 기본 tier는 ROI(관심 영역)를 감지해 지능적으로 크롭하고, AIGC tier는 부족한 영역을 AI로 생성해 확장합니다. ## 요청 방법 | 항목 | 값 | | ---------- | --------------------------------------- | | 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/landscape.mp4"}}` | 입력 미디어 정보. `Type`은 `URL` 또는 `COS`. AWS S3는 미지원 | | OutputStorage | Object | URL 입력 시 필수 | `{"Type":"COS","CosOutputStorage":{"Bucket":"mybucket-125xxx","Region":"ap-guangzhou"}}` | 출력 저장소. URL 입력 시 반드시 지정(공식 제약) | | OutputDir | String | 선택 | `/output/orientation/` | 출력 디렉터리. `/`로 시작하고 `/`로 끝나야 함 | | AiAnalysisTask.Definition | Integer | 필수 | `28` | AI 분석 태스크 템플릿 ID. 고정값 `28`(프리셋 가로/세로 변환 템플릿). 커스텀 템플릿 미지원 | | AiAnalysisTask.ExtendedParameter | String | 필수 | `{"htv":{"AlgorithmType":2,"SmoothWeight":0.75,"Ratio":"9:16"}}` | 변환 설정(JSON 문자열). 아래 htv 표 참조 | | TaskNotifyConfig.NotifyUrl | String | 선택 | `https://example.com/callback` | 태스크 완료 콜백 URL. NotifyType은 `URL` | | SessionId | String | 선택 | - | 중복 제거용 ID. 최대 50자. 3일 내 동일 ID 요청은 오류 반환 | ExtendedParameter의 `htv` 객체 필드는 다음과 같습니다. | 파라미터 | 타입 | 필수 여부 | 예시 | 설명 | | -------------------------------------------- | ------- | ----- | --------------------- | ----------------------------------------------------------------------- | | AlgorithmType | Integer | 필수 | `2` | 알고리즘 유형. `2` / `3` / `5` / `6` / `7`. 아래 알고리즘 표 참조 | | Ratio | String | 선택 | `9:16` | 목표 화면 비율. `9:16`(기본) / `16:9` / `3:4` 등. 파싱 실패 시 `9:16`으로 폴백 | | SmoothWeight | Number | 선택 | `0.75` | 스무딩 속도. 0\~1 실수. 작을수록 카메라 무빙이 빠름. 기본 `0.75` | | BlurWeight | Integer | 선택 | `50` | 블러 강도. 클수록 흐림. 알고리즘 `5` 전용. 너무 크면 처리가 느려짐 | | OutputPattern | String | 선택 | `htv-{sessionId}` | 출력 파일명 패턴. `{sessionId}` / `{timestamp}` 플레이스홀더 지원 | | FaceDetectConfig.FaceScoreThd | Integer | 선택 | `60` | 얼굴 감지 점수 임계값. 알고리즘 `3` 전용 | | FaceDetectConfig.FaceAccuracy | String | 선택 | `Balance` | 얼굴 감지 패스 수. `Balance`(기본) / `Efficiency` / `Precision` | | FaceDetectConfig.FallbackConfig.NoFaceDetect | String | 선택 | `ScaleWithoutBlur` | 얼굴 미검출 시 폴백. `Scale` / `ScaleWithoutBlur`(기본) | | FaceDetectConfig.FallbackConfig.DoubleFace | String | 선택 | `SplitScreenVertical` | 얼굴 2개 검출 시 폴백. `Scale` / `ScaleWithoutBlur` / `SplitScreenVertical`(기본) | 알고리즘 유형은 변환 방향에 따라 선택합니다. | AlgorithmType | 방향 | 설명 | 과금 tier | | ------------- | ------- | ------------------------------------- | -------- | | `2` | 가로 → 세로 | 멀티 모델 알고리즘, 맞춤 최적화(권장 기본) | Basic | | `3` | 가로 → 세로 | 정밀 얼굴 감지. 얼굴 2개 시 상하 분할 후 얼굴 중앙 배치 | Basic | | `5` | 가로 → 세로 | 세로 캔버스에 축소 중앙 배치, 배경은frosted-glass 블러 | Basic | | `6` | 가로 → 세로 | AIGC 모드. 가로 영상을 9:16 세로로 확장 | Advanced | | `7` | 세로 → 가로 | AIGC 모드. 세로 영상을 16:9 가로로 확장 | Advanced | 폴백 동작 의미: `Scale`은 프레임을 축소 중앙 배치하고 배경을 frosted-glass 블러로 채우며, `ScaleWithoutBlur`는 배경을 검정으로 채우고, `SplitScreenVertical`은 화면을 상하로 분할해 각 얼굴을 배치합니다. ## 응답 파라미터 | 파라미터 | 타입 | 필수 여부 | 예시 | 설명 | | --------- | ------ | ----- | -------------------------------------- | --------------------- | | TaskId | String | 항상 | `2600011633-WorkflowTask-xxxxx` | 발급된 태스크 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)) # 가로 → 세로 (알고리즘 2, 기본 설정) params = { "InputInfo": { "Type": "COS", "CosInputInfo": { "Bucket": "mybucket-125xxx", "Region": "ap-guangzhou", "Object": "/input/landscape.mp4" } }, "OutputStorage": { "Type": "COS", "CosOutputStorage": {"Bucket": "mybucket-125xxx", "Region": "ap-guangzhou"} }, "OutputDir": "/output/orientation/", "AiAnalysisTask": { "Definition": 28, "ExtendedParameter": json.dumps({ "htv": {"AlgorithmType": 2, "SmoothWeight": 0.75, "Ratio": "9:16"} }) } } req = models.ProcessMediaRequest() req.from_json_string(json.dumps(params)) resp = client.ProcessMedia(req) print(resp.to_json_string()) ``` ```python theme={null} # 얼굴 시나리오 가로 → 세로 (알고리즘 3, 얼굴 감지 세부 설정) params["AiAnalysisTask"]["ExtendedParameter"] = json.dumps({ "htv": { "AlgorithmType": 3, "Ratio": "9:16", "SmoothWeight": 0.75, "FaceDetectConfig": { "FaceScoreThd": 60, "FaceAccuracy": "Precision", "FallbackConfig": { "NoFaceDetect": "ScaleWithoutBlur", "DoubleFace": "SplitScreenVertical" } } } }) # AIGC 세로 → 가로 (알고리즘 7, 반드시 16:9 지정) params["AiAnalysisTask"]["ExtendedParameter"] = json.dumps({ "htv": {"AlgorithmType": 7, "Ratio": "16:9"} }) ``` ## 응답 예시 ```json theme={null} { "TaskId": "2600011633-WorkflowTask-xxxxx", "RequestId": "3c140219-cfe9-470e-b241-907877d6fb03" } ``` ## 주의사항 `AlgorithmType`은 필수이며 변환 방향을 먼저 확인한 뒤 선택합니다. 알고리즘 `7`(세로 → 가로)을 사용할 때는 `Ratio`를 반드시 `16:9`로 지정하세요. 기본값 `9:16`은 세로 → 가로 의도와 충돌합니다. 오프라인 파일만 지원하며 라이브 스트림은 불가합니다. 입력 소스는 URL과 Tencent Cloud COS만 지원하고 AWS S3는 지원하지 않습니다. `Definition`은 `28`로 고정이며, 커스텀 지능 분석 템플릿에 이 기능을 얹으려면 Tencent Cloud에 문의해야 합니다. 입력은 MPEG/H.264/H.265 인코딩의 mp4/avi/mkv/mov/mpg 컨테이너를 지원하고, 출력은 H.264 인코딩 mp4로 통일됩니다. 출력 디렉터리에서 `htv-`로 시작하는 파일이 결과입니다. 결과 경로는 `DescribeTaskDetail` 응답의 `AiAnalysisResultSet` 아래 `HorizontalToVerticalTask` → `Output`에서 확인합니다. 알고리즘 `6`/`7`은 Advanced tier로 Basic보다 과금이 높습니다.