Image ProcessingLast Updated 2026-09-30

Poster Suite

On this page

상품 메인 이미지를 업로드하고 플랫폼과 테마를 지정하면 광고 포스터 패널 여러 장을 한 번에 생성합니다. 이커머스 상품 이미지 일괄 제작, 광고 포스터 제작, 마케팅 소재 고속 생산, 플랫폼별 상품 이미지 커스터마이징에 사용합니다.

API 정보

항목	값
서비스	MPS
API Action	`ProcessImage`
엔드포인트	`mps.tencentcloudapi.com`
API 버전	`2019-06`-12
ScheduleId	생략 (`ImageTask.AiPosterSuiteConfig`로 기능 구분)
처리 방식	비동기 (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/poster_suite/`	출력 디렉터리. 기본값 `/output/poster_suite/`
ResourceId	String	선택	-	리소스 ID. 전용 리소스를 배정받은 경우에만 사용
ImageTask	Object	필수	아래 호출 예시 참조	이미지 태스크 설정
ImageTask.AiPosterSuiteConfig.Mode	String	필수	`auto`	실행 모드. `auto`(기본값) / `modify`
ImageTask.AiPosterSuiteConfig.Definition	Integer	필수	`50`	템플릿 팩 ID. `50~55`, 플랫폼 매핑 표 참조
ImageTask.AiPosterSuiteConfig.Recipe.N.Theme	String	필수	`hero`	패널 테마. 표준 테마 `6개` 중 하나
ImageTask.AiPosterSuiteConfig.Recipe.N.Num	Integer	필수	`2`	해당 테마의 패널 수. 테마당 `1~4`
ImageTask.AiPosterSuiteConfig.Language	String	필수	`zh-CN`	카피 언어. `zh-CN`(기본값) / `en-US`
ImageTask.AiPosterSuiteConfig.PanelRatio	String	필수	`1:1`	패널 가로세로 비율. `1:1`(기본값) / `3:2` / `2:3` / `3:4` / `4:3` / `9:16` / `16:9`
ImageTask.AiPosterSuiteConfig.PanelResolution	String	필수	`1K`	패널 해상도. `720` / `1K`(기본값) / `2K` / `4K`
ImageTask.AiPosterSuiteConfig.Model	String	필수	`WAND-suite-1.0-flash`	생성 모델. 현재 `WAND-suite-1.0-flash` 제공
ImageTask.AiPosterSuiteConfig.CustomVariables.N.Type	String	선택	`MaterialKeyword`	커스텀 변수명. PascalCase, 예약어 `UserPrompt`를 제외한 이름 사용, 요청 내 고유한 값 사용. auto 모드 전용
ImageTask.AiPosterSuiteConfig.CustomVariables.N.Description	String	선택	`material keyword`	커스텀 변수 설명. 개인화 템플릿과 함께 사용
AddOnParameter.ImageSet.N.Image	Object	선택	`{"Type":"URL","UrlInputInfo":{"Url":"https://example.com/view1.jpg"}}`	추가 상품 앵글 이미지. 최대 `3장`
AddOnParameter.ExtPrompt.N.Role	String	선택	`BrandName`	카피 변수 Role. 표준 변수 표 참조
AddOnParameter.ExtPrompt.N.Prompt	String	선택	`AURASKIN`	카피 변수 값. `Role`이 `UserPrompt`인 자유 텍스트는 요청당 최대 `1개`

표준 변수 Role 9개는 다음과 같습니다.

Role	의미	예시 값
`BrandName`	상품 패키지에 표기된 브랜드명을 원문 그대로 사용. 해당 항목이 공란이면 빈 값 유지	`AURASKIN`
`Headline`	메인 광고 슬로건. `4~8`단어	`Keep Revitalizing, Gentle on Skin`
`SellingPointsText`	셀링 포인트 목록. `3~4개`를 `/`로 연결, 특징 중심으로 서술	`Hydrating / Firming / Antioxidant`
`ProductCategory`	상품 카테고리. `MainCat-SubCat` 형식	`Beauty-Skincare`
`ProductVisualIdentity`	색상, 형태, 소재, 비율, 표면 처리 등 시각 특성	`matte glass dropper bottle, amber, frosted`
`TextureDescription`	상품 질감 또는 소재 설명	`silky cream`
`ColorPalette`	브랜드 컬러 팔레트. HEX `3개`를 `,`로 연결	`#F5C2C7,#A8DADC,#F1FAEE`
`TargetAudience`	타깃 고객 프로필	`Urban professional women 22-35`
`SceneContext`	권장 진열 장면과 사용 순간	`Morning vanity table / Post-workout`

응답 파라미터

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

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

파라미터	타입	필수	예시	설명
Status	String	항상	`FINISH`	태스크 상태. `FINISH`면 처리 완료
ErrMsg	String	항상	-	처리 결과 메시지. 성공 시 빈 값
CreateTime	String	항상	`2026-07-06T10:00:00Z`	태스크 생성 시각
FinishTime	String	완료 시	`2026-07-06T10:05:00Z`	태스크 완료 시각
ImageProcessTaskResultSet[0].Output.Content	String	성공 시	아래 응답 예시 참조	변수 에코. JSON 문자열이며 역직렬화하면 `AddOnParameter` 구조. modify 모드 요청에 그대로 재사용 가능
ImageProcessTaskResultSet[1..N].Output.Path	String	성공 시	`/output/poster_suite/hero_0.jpg`	생성된 패널 이미지의 COS 경로
ImageProcessTaskResultSet[1..N].Output.Content	String	성공 시	`hero_0`	`{Theme}_{Index}` 형식의 패널 라벨

호출 예시

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

# auto 모드: 상품 이미지 + Definition + Recipe
params = {
    "InputInfo": {
        "Type": "URL",
        "UrlInputInfo": {"Url": "https://example.com/product.jpg"}
    },
    "OutputStorage": {
        "Type": "COS",
        "CosOutputStorage": {"Bucket": "mybucket-125xxx", "Region": "ap-guangzhou"}
    },
    "OutputDir": "/output/poster_suite_auto/",
    "ImageTask": {
        "AiPosterSuiteConfig": {
            "Mode": "auto",
            "Definition": 50,
            "Recipe": [
                {"Theme": "hero", "Num": 2},
                {"Theme": "detail", "Num": 2}
            ],
            "Language": "zh-CN",
            "PanelRatio": "3:4",
            "PanelResolution": "2K",
            "Model": "WAND-suite-1.0-flash",
            "CustomVariables": [
                {"Type": "MaterialKeyword", "Description": "material keyword"}
            ]
        }
    },
    "AddOnParameter": {
        "ExtPrompt": [
            {"Role": "BrandName", "Prompt": "AURASKIN"},
            {"Role": "Headline", "Prompt": "Keep Revitalizing"},
            {"Role": "UserPrompt", "Prompt": "Bottle is 32cm, emphasize the pump and frosted texture"}
        ]
    }
}

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

LANGUAGE
# modify 모드: auto 결과의 변수 에코를 9개 전부 다시 전달하고 일부 값만 수정
params["OutputDir"] = "/output/poster_suite_modify/"
params["ImageTask"]["AiPosterSuiteConfig"]["Mode"] = "modify"
params["ImageTask"]["AiPosterSuiteConfig"].pop("CustomVariables")
params["AddOnParameter"] = {
    "ExtPrompt": [
        {"Role": "BrandName", "Prompt": "AURASKIN"},
        {"Role": "Headline", "Prompt": "Gentle yet powerful serum"},
        {"Role": "SellingPointsText", "Prompt": "Hydrating / Firming / Antioxidant"},
        {"Role": "ProductCategory", "Prompt": "Beauty-Skincare"},
        {"Role": "ProductVisualIdentity", "Prompt": "matte glass dropper bottle, amber"},
        {"Role": "TextureDescription", "Prompt": "silky cream"},
        {"Role": "ColorPalette", "Prompt": "#F5C2C7,#A8DADC,#F1FAEE"},
        {"Role": "TargetAudience", "Prompt": "Urban professional women 22-35"},
        {"Role": "SceneContext", "Prompt": "Morning vanity table"},
        {"Role": "UserPrompt", "Prompt": "Make the Headline font one size larger"}
    ]
}

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

DescribeImageTaskDetail 조회 결과(정리된 형태):

LANGUAGE
{
  "TaskId": "2600007696-WorkflowTask-xxxxxxxx",
  "Status": "FINISH",
  "CreateTime": "2026-07-06T10:00:00Z",
  "FinishTime": "2026-07-06T10:05:00Z",
  "VariableEcho": {
    "ExtPrompt": [
      {
        "Role": "BrandName",
        "Prompt": "AURASKIN"
      },
      {
        "Role": "Headline",
        "Prompt": "Keep Revitalizing"
      },
      {
        "Role": "SellingPointsText",
        "Prompt": "Hydrating / Firming / Antioxidant"
      }
    ]
  },
  "Panels": [
    {
      "theme_label": "hero_0",
      "bucket": "mps-bucket-125xxx",
      "region": "ap-guangzhou",
      "path": "/output/poster_suite/hero_0.jpg",
      "cos_uri": "cos://mps-bucket-125xxx/output/poster_suite/hero_0.jpg",
      "url": "https://mps-bucket-125xxx.cos.ap-guangzhou.myqcloud.com/output/poster_suite/hero_0.jpg"
    },
    {
      "theme_label": "hero_1",
      "bucket": "mps-bucket-125xxx",
      "region": "ap-guangzhou",
      "path": "/output/poster_suite/hero_1.jpg",
      "cos_uri": "cos://mps-bucket-125xxx/output/poster_suite/hero_1.jpg",
      "url": "https://mps-bucket-125xxx.cos.ap-guangzhou.myqcloud.com/output/poster_suite/hero_1.jpg"
    }
  ]
}

사용 안내

Recipe의 테마별 Num은 1~4, 전체 패널 수는 4~12로 지정합니다.

modify 모드는 auto 결과의 표준 변수 9개를 ExtPrompt에 전달합니다. CustomVariables는 auto 모드에서 사용합니다.

modify로 반복 생성할 때는 auto와 다른 OutputDir를 지정합니다. 같은 디렉터리를 사용하면 hero_0.png 같은 패널 파일명이 겹쳐 auto 결과를 덮어사용합니다.

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

UserPrompt는 요청당 1개를 사용합니다. ExtPrompt 항목 또는 별도 자유 텍스트 중 한 방식으로 전달합니다.

카피성 필드의 출력 언어는 Language를 따릅니다. BrandName과 ColorPalette는 원문 값을 유지합니다.

URL 입력은 공개 접근이 가능해야 하고, COS 입력은 MPS 서비스에 해당 Bucket의 읽기 권한이 있어야 합니다. 추가 앵글 이미지는 최대 3장입니다.