Image ProcessingLast Updated 2026-09-30

Image Outpainting

On this page

입력 이미지의 바깥 영역을 AI로 생성해 캔버스를 확장합니다. 이커머스 대표 이미지 확장, 소셜 미디어 커버 비율 변환, 세로 사진의 가로 전환, 포스터 캔버스 확장에 사용합니다.

API 정보

항목	값
서비스	MPS
API Action	`ProcessImage`
엔드포인트	`mps.tencentcloudapi.com`
API 버전	`2019-06`-12
ScheduleId	`30010`
처리 방식	비동기 (TaskId 발급 후 결과 조회)

인증은 모든 API가 공통으로 TC3-HMAC-SHA256(SecretId/SecretKey) 서명을 사용합니다. 서명 생성 방법은 Quick Start의 TokenHub 문서를 참고하세요.

결과 조회는 DescribeImageTaskDetail 또는 완료 콜백으로 받을 수 있습니다.

요청 파라미터

파라미터	타입	필수	예시	설명
InputInfo	Object	필수	`{"Type":"URL","UrlInputInfo":{"Url":"https://example.com/photo.jpg"}}`	입력 이미지. `Type`은 `URL` 또는 `COS`, COS는 `CosInputInfo`에 Bucket/Region/Object 지정
OutputStorage	Object	필수	`{"Type":"COS","CosOutputStorage":{"Bucket":"mybucket-125xxx","Region":"ap-guangzhou"}}`	출력 저장소. COS Bucket과 Region 지정
OutputDir	String	선택	`/output/padding/`	출력 디렉터리. 기본값 `/output/padding/`
OutputPath	String	선택	`/output/padding/result.jpeg`	커스텀 출력 경로. 파일 확장자를 포함해야 함
ScheduleId	Integer	필수	`30010`	아웃페인팅 시나리오 ID
AddOnParameter	Object	필수	`{"OutputConfig":{"AspectRatio":"16:9"}}`	아웃페인팅 출력 설정
AddOnParameter.OutputConfig.AspectRatio	String	조건부 필수	`16:9`	목표 가로세로 비율. `ImageWidth`/`ImageHeight`와 합쳐 셋 중 하나 이상 필수
AddOnParameter.OutputConfig.ImageWidth	Integer	조건부 필수	`1920`	목표 너비(px)
AddOnParameter.OutputConfig.ImageHeight	Integer	조건부 필수	`1080`	목표 높이(px)

응답 파라미터

파라미터	타입	필수	예시	설명
TaskId	String	항상	`2600007696-WorkflowTask-bCDE2345FG6789`	발급된 태스크 ID. `DescribeImageTaskDetail` 조회에 사용
RequestId	String	항상	`3c140219-cfe9-470e-b241-907877d6fb03`	요청 식별자

DescribeImageTaskDetail 조회 결과의 주요 필드는 다음과 같습니다.

파라미터	타입	필수	예시	설명
Status	String	항상	`FINISH`	태스크 상태. `FINISH`면 처리 완료
ErrMsg	String	항상	-	처리 결과 메시지. 성공 시 빈 값
CreateTime	String	항상	`2025-05-21T10:00:00Z`	태스크 생성 시각
FinishTime	String	완료 시	`2025-05-21T10:00:15Z`	태스크 완료 시각
Outputs.N.Path	String	성공 시	`/output/padding/result.jpeg`	결과 이미지의 COS 경로

호출 예시

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

# 아웃페인팅 태스크 제출 (16:9 확장)
params = {
    "InputInfo": {
        "Type": "URL",
        "UrlInputInfo": {"Url": "https://example.com/photo.jpg"}
    },
    "OutputStorage": {
        "Type": "COS",
        "CosOutputStorage": {"Bucket": "mybucket-125xxx", "Region": "ap-guangzhou"}
    },
    "OutputDir": "/output/padding/",
    "ScheduleId": 30010,
    "AddOnParameter": {
        "OutputConfig": {"AspectRatio": "16:9"}
    }
}

req = models.ProcessImageRequest()
req.from_json_string(json.dumps(params))
resp = client.ProcessImage(req)
print(resp.to_json_string())

LANGUAGE
# 목표 크기를 픽셀로 지정하는 경우
params["AddOnParameter"] = {
    "OutputConfig": {"ImageWidth": 1920, "ImageHeight": 1080}
}

LANGUAGE
# 태스크 결과 조회
query = models.DescribeImageTaskDetailRequest()
query.from_json_string(json.dumps({"TaskId": "<TaskId>"}))
detail = client.DescribeImageTaskDetail(query)
print(detail.to_json_string())

응답 예시

ProcessImage 응답:

LANGUAGE
{
  "Response": {
    "TaskId": "2600007696-WorkflowTask-bCDE2345FG6789",
    "RequestId": "3c140219-cfe9-470e-b241-907877d6fb03"
  }
}

DescribeImageTaskDetail 조회 결과:

LANGUAGE
{
  "TaskId": "2600007696-WorkflowTask-bCDE2345FG6789",
  "Status": "FINISH",
  "CreateTime": "2025-05-21T10:00:00Z",
  "FinishTime": "2025-05-21T10:00:15Z",
  "Outputs": [
    {
      "bucket": "mps-bucket-125xxx",
      "region": "ap-guangzhou",
      "path": "/output/padding/result.jpeg",
      "cos_uri": "cos://mps-bucket-125xxx/output/padding/result.jpeg",
      "url": "https://mps-bucket-125xxx.cos.ap-guangzhou.myqcloud.com/output/padding/result.jpeg"
    }
  ]
}

사용 안내

AspectRatio, ImageWidth, ImageHeight 중 하나 이상을 지정합니다.

완료 응답에서 Status="FINISH"와 빈 ErrMsg를 함께 확인합니다.

출력 크기는 1024x1024 수준의 1K 범위를 권장합니다. 2K를 초과하는 해상도는 생성 품질 저하나 타임아웃을 유발할 수 있습니다.

URL 입력은 공개 접근이 가능해야 하고, COS 입력은 MPS 서비스에 해당 Bucket의 읽기 권한이 있어야 합니다.