Orientation Conversion

기존 영상의 화면 방향을 양방향으로 변환합니다. 가로에서 세로(알고리즘 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`	요청 식별자

호출 예시

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

# 가로 → 세로 (알고리즘 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())

# 얼굴 시나리오 가로 → 세로 (알고리즘 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"}
})

응답 예시

{
  "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보다 과금이 높습니다.

Getting Started

WAND AIGC

MPS Features

TokenHub

Appendix

요청 방법

요청 파라미터

응답 파라미터

호출 예시

응답 예시

주의사항

​요청 방법

​요청 파라미터

​응답 파라미터

​호출 예시

​응답 예시

​주의사항

요청 방법

요청 파라미터

응답 파라미터

호출 예시

응답 예시

주의사항