> ## Documentation Index > Fetch the complete documentation index at: https://wand.tencentpoc.com/llms.txt > Use this file to discover all available pages before exploring further. # Poster Suite > 상품 메인 이미지 기반 플랫폼별 포스터 패널 일괄 생성 API Reference 상품 메인 이미지를 업로드하고 플랫폼과 테마를 지정하면 광고 포스터 패널 여러 장을 한 번에 생성합니다. 이커머스 상품 이미지 일괄 제작, 광고 포스터 제작, 마케팅 소재 고속 생산, 플랫폼별 상품 이미지 커스터마이징에 사용합니다. ## 요청 방법 | 항목 | 값 | | ---------- | -------------------------------------------- | | API Action | `ProcessImage` | | 엔드포인트 | `mps.tencentcloudapi.com` | | API 버전 | `2019-06-12` | | 인증 | TC3-HMAC-SHA256 (SecretId/SecretKey 서명) | | 요청 방식 | HTTP POST, JSON | | ScheduleId | 미사용 (`ImageTask.AiPosterSuiteConfig`로 기능 구분) | 비동기 태스크입니다. 호출이 접수되면 `TaskId`가 즉시 발급되고, 처리 결과는 `DescribeImageTaskDetail`로 조회합니다. `Status`가 `FINISH`이고 `ErrMsg`가 비어 있어야 성공입니다. 실행 모드는 두 가지입니다. | Mode | 상품 정보 자동 추출 | ExtPrompt 역할 | | ------------ | ----------------------------------------- | ------------------------------------------ | | `auto` (기본값) | 수행. 상품 이미지에서 브랜드, 셀링 포인트, 컬러 팔레트 등을 자동 추출 | 개별 필드 덮어쓰기, 자유 텍스트 추가 | | `modify` | 미수행 | auto에서 얻은 표준 변수 9개를 전부 다시 전달해야 함(부분 전달 불가) | `Definition`은 플랫폼을 결정합니다. | Definition | 플랫폼 | | ---------- | ------------ | | `50` | Taobao/Tmall | | `51` | Amazon | | `52` | JD.com | | `53` | Pinduoduo | | `54` | Temu | | `55` | TikTok | `Recipe`의 `Theme`은 플랫폼과 무관하게 다음 6개 표준 값만 허용합니다. | Theme | 용도 | | ------------ | ------------------------------ | | `hero` | 메인 이미지. 상품 중심의 커버 패널 | | `selling` | 셀링 포인트 이미지. 아이콘과 주석으로 핵심 장점 전달 | | `scene` | 장면 이미지. 실제 사용 장면에 상품 배치 | | `detail` | 디테일 이미지. 소재와 질감 클로즈업 | | `angles` | 멀티 앵글 이미지. 다양한 시점의 상품 컷 | | `atmosphere` | 분위기 이미지. 브랜드 톤과 라이프스타일 강조 | ## 요청 파라미터 | 파라미터 | 타입 | 필수 여부 | 예시 | 설명 | | ----------------------------------------------------------- | ------- | ----- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | 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}` 형식의 패널 라벨 | ## 호출 예시 ```python theme={null} 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("", "") 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()) ``` ```python theme={null} # 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"} ] } ``` ```python theme={null} # 태스크 결과 조회 query = models.DescribeImageTaskDetailRequest() query.from_json_string(json.dumps({"TaskId": ""})) detail = client.DescribeImageTaskDetail(query) print(detail.to_json_string()) ``` ## 응답 예시 ProcessImage 응답: ```json theme={null} { "Response": { "TaskId": "2600007696-WorkflowTask-xxxxxxxx", "RequestId": "3c140219-cfe9-470e-b241-907877d6fb03" } } ``` DescribeImageTaskDetail 조회 결과(정리된 형태): ```json theme={null} { "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이고, 전체 패널 수(`Num`의 합)는 4~~12여야 합니다. 범위를 벗어나면 태스크를 제출할 수 없습니다. modify 모드는 auto에서 얻은 표준 변수 9개를 전부 `ExtPrompt`에 다시 전달해야 합니다. 일부만 전달하면 에러가 발생합니다. `CustomVariables`는 auto 모드에서만 사용할 수 있습니다. modify로 반복 생성할 때는 auto와 다른 `OutputDir`를 지정합니다. 같은 디렉터리를 쓰면 `hero_0.png` 같은 패널 파일명이 겹쳐 auto 결과를 덮어씁니다. `Status`가 `FINISH`여도 성공을 의미하지 않습니다. `ErrMsg`가 비어 있는지 반드시 함께 확인합니다. `UserPrompt`는 요청당 최대 1개입니다. `ExtPrompt`의 `UserPrompt` 항목과 별도 자유 텍스트를 동시에 전달할 수 없습니다. 카피성 필드(`Headline`, `SellingPointsText`, `ProductCategory`, `TargetAudience`, `SceneContext`, `TextureDescription`, `ProductVisualIdentity`)의 출력 언어는 `Language`를 따르고, `BrandName`과 `ColorPalette`는 언어의 영향을 받지 않습니다. URL 입력은 공개 접근이 가능해야 하고, COS 입력은 MPS 서비스에 해당 Bucket의 읽기 권한이 있어야 합니다. 추가 앵글 이미지는 최대 3장입니다.