WAND wiki
최근 문서

검색 결과가 없습니다. 모델명이나 다른 키워드로 검색해 보세요.

↑ ↓ 이동 ↵ 열기전체 결과 보기 →
UtilitiesLast Updated 2026-09-30

Orientation Conversion

On this page

기존 영상의 화면 방향을 양방향으로 변환합니다. 가로에서 세로(알고리즘 2/3/5/6), 세로에서 가로(알고리즘 7)를 지원합니다. 단순 회전이 아니라 기본 tier는 ROI(관심 영역)를 감지해 지능적으로 크롭하고, AIGC tier는 부족한 영역을 AI로 생성해 확장합니다.

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/landscape.mp4"}} 입력 미디어 정보. Type은 URL 또는 COS. URL/COS 입력 사용
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 선택 - 요청별 식별자. 최대 50자, 3일 동안 고유한 값 사용

ExtendedParameter의 htv 객체 필드는 다음과 같습니다.

파라미터 타입 필수 예시 설명
AlgorithmType Integer 필수 2 알고리즘 유형. 2 / 3 / 5 / 6 / 7. 아래 알고리즘 표 참조
Ratio String 선택 9:16 목표 화면 비율. 9:16(기본) / 16:9 / 3:4 등
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 요청 식별자

호출 예시

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

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

응답 예시

LANGUAGE
{
  "TaskId": "2600011633-WorkflowTask-xxxxx",
  "RequestId": "3c140219-cfe9-470e-b241-907877d6fb03"
}

사용 안내

AlgorithmType은 필수이며 변환 방향을 먼저 확인한 뒤 선택합니다. 알고리즘 7(세로 → 가로)을 사용할 때는 Ratio를 반드시 16:9로 지정하세요. 기본값 9:16은 세로 → 가로 의도와 충돌합니다.

입력은 공개 URL 또는 Tencent Cloud COS의 오프라인 파일을 사용합니다. 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보다 과금이 높습니다.

Contact us about WAND