Image ProcessingLast Updated 2026-09-30

Background Fusion

On this page

피사체(전경/상품) 이미지와 배경 이미지를 입력받아 자연스럽게 합성하거나, 배경 이미지 없이 프롬프트만으로 새 배경을 생성합니다. 이커머스 상품 이미지 배경 교체, 광고 소재 배경 생성, 진열 장면 커스터마이징에 사용합니다.

API 정보

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

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

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

요청 파라미터

파라미터	타입	필수	예시	설명
InputInfo	Object	필수	`{"Type":"URL","UrlInputInfo":{"Url":"https://example.com/product.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/bgfusion/`	출력 디렉터리. 기본값 `/output/bgfusion/`
OutputPath	String	선택	`/output/bgfusion/result.jpeg`	커스텀 출력 경로. 파일 확장자를 포함해야 함
ResourceId	String	선택	-	리소스 ID. 전용 리소스를 배정받은 경우에만 사용
ScheduleId	Integer	필수	`30060`	배경 합성/생성 시나리오 ID
AddOnParameter	Object	필수	아래 호출 예시 참조	배경 합성/생성 설정
AddOnParameter.OutputConfig.Format	String	필수	`JPEG`	출력 포맷. `JPEG`(기본값) / `PNG`
AddOnParameter.OutputConfig.ImageSize	String	필수	`2K`	출력 크기. `1K` / `2K`(기본값) / `4K`
AddOnParameter.OutputConfig.Quality	Integer	필수	`85`	출력 품질. `1~100`, 기본값 `85`
AddOnParameter.ExtPrompt.N.Prompt	String	조건부 필수	`Minimalist white marble tabletop, soft natural light`	배경 설명 또는 합성 요구 사항. 여러 개 지정 가능. 배경 생성 모드에서는 필수
AddOnParameter.ImageSet.N.Image	Object	선택	`{"Type":"URL","UrlInputInfo":{"Url":"https://example.com/bg.jpg"}}`	배경 이미지. `1장`만 지정 가능. 생략하면 배경 생성 모드
StdExtInfo	String(JSON)	선택	`{"ModelConfig":{"RandomSeed":42}}`	모델 설정. `RandomSeed`를 고정하면 동일 스타일의 결과를 재현할 수 있음

응답 파라미터

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

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

파라미터	타입	필수	예시	설명
Status	String	항상	`FINISH`	태스크 상태. `FINISH`면 처리 완료
ErrMsg	String	항상	-	처리 결과 메시지. 성공 시 빈 값
CreateTime	String	항상	`2025-05-21T01:02:51Z`	태스크 생성 시각
FinishTime	String	완료 시	`2025-05-21T01:02:52Z`	태스크 완료 시각
Outputs.N.Path	String	성공 시	`/output/bgfusion/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))

# 배경 생성 모드: 피사체 이미지 + Prompt (배경 이미지 없음)
params = {
    "InputInfo": {
        "Type": "URL",
        "UrlInputInfo": {"Url": "https://example.com/product.jpg"}
    },
    "OutputStorage": {
        "Type": "COS",
        "CosOutputStorage": {"Bucket": "mybucket-125xxx", "Region": "ap-guangzhou"}
    },
    "OutputDir": "/output/bgfusion/",
    "ScheduleId": 30060,
    "AddOnParameter": {
        "OutputConfig": {"Format": "JPEG", "ImageSize": "2K", "Quality": 85},
        "ExtPrompt": [{"Prompt": "Minimalist white marble tabletop, soft natural light"}]
    },
    "StdExtInfo": json.dumps({"ModelConfig": {"RandomSeed": 42}})
}

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

LANGUAGE
# 배경 합성 모드: ImageSet에 배경 이미지를 추가
params["AddOnParameter"]["ImageSet"] = [
    {
        "Image": {
            "Type": "URL",
            "UrlInputInfo": {"Url": "https://example.com/background.jpg"}
        }
    }
]
params["AddOnParameter"]["ExtPrompt"] = [
    {"Prompt": "Replace the leaves in the background with yellow"}
]

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-b8dac8f326214464acef88afef9002d4",
    "RequestId": "3c140219-cfe9-470e-b241-907877d6fb03"
  }
}

DescribeImageTaskDetail 조회 결과:

LANGUAGE
{
  "TaskId": "2600007696-WorkflowTask-b8dac8f326214464acef88afef9002d4",
  "Status": "FINISH",
  "CreateTime": "2025-05-21T01:02:51Z",
  "FinishTime": "2025-05-21T01:02:52Z",
  "Outputs": [
    {
      "bucket": "mps-bucket-125xxx",
      "region": "ap-guangzhou",
      "path": "/output/bgfusion/result.jpeg",
      "cos_uri": "cos://mps-bucket-125xxx/output/bgfusion/result.jpeg",
      "url": "https://mps-bucket-125xxx.cos.ap-guangzhou.myqcloud.com/output/bgfusion/result.jpeg"
    }
  ]
}

사용 안내

프롬프트 기반 배경 생성은 ExtPrompt에 배경 설명을 입력합니다.

배경 이미지는 1장을 입력합니다.

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

URL 입력은 공개 접근이 가능해야 하고, COS 입력은 MPS 서비스에 해당 Bucket의 읽기 권한이 있어야 합니다. 피사체 이미지와 배경 이미지는 서로 다른 Bucket에 두어도 됩니다.