> ## 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. # Try-On > 모델 이미지 기반 AI 의류 착용(가상 피팅) API Reference 모델 이미지와 의류 이미지를 입력받아 모델이 해당 의류를 착용한 이미지를 생성합니다. 이커머스 의류 피팅, 상품 상세 이미지 생성, 광고 소재 제작, 착용 효과 미리보기에 사용합니다. ## 요청 방법 | 항목 | 값 | | ---------- | --------------------------------------- | | API Action | `ProcessImage` | | 엔드포인트 | `mps.tencentcloudapi.com` | | API 버전 | `2019-06-12` | | 인증 | TC3-HMAC-SHA256 (SecretId/SecretKey 서명) | | 요청 방식 | HTTP POST, JSON | | ScheduleId | 미사용 (`ImageTask.AiTryOnConfig`로 기능 구분) | 비동기 태스크입니다. 호출이 접수되면 `TaskId`가 즉시 발급되고, 처리 결과는 `DescribeImageTaskDetail`로 조회합니다. `Status`가 `FINISH`이고 `ErrMsg`가 비어 있어야 성공입니다. ## 요청 파라미터 | 파라미터 | 타입 | 필수 여부 | 예시 | 설명 | | ---------------------------------- | ------ | ----- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | InputInfo | Object | 필수 | `{"Type":"URL","UrlInputInfo":{"Url":"https://example.com/model.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/tryon/` | 출력 디렉터리. 기본값 `/output/tryon/` | | OutputPath | String | 선택 | `/output/tryon/result.jpeg` | 커스텀 출력 경로. 파일 확장자를 포함해야 함 | | ResourceId | String | 선택 | - | 리소스 ID. 전용 리소스를 배정받은 경우에만 사용 | | ImageTask | Object | 필수 | 아래 호출 예시 참조 | 이미지 태스크 설정 | | ImageTask.AiTryOnConfig.Model | String | 필수 | `WAND-tryon-1.0-flash` | 피팅 모델. `WAND-tryon-1.0-lite`(경량) / `WAND-tryon-1.0-flash`(고속, 기본값) / `WAND-tryon-1.0-pro`(전문가) | | ImageTask.AiTryOnConfig.Resolution | String | 필수 | `1K` | 출력 해상도. `1K`(기본값) / `2K` / `4K` | | ImageTask.AiTryOnConfig.Prompt | String | 선택 | `Change the shirt to red` | 피팅 지시문. 생략 시 내장 기본값 사용 | | AddOnParameter.ImageSet.N.Image | Object | 필수 | `{"Type":"URL","UrlInputInfo":{"Url":"https://example.com/cloth.jpg"}}` | 의류 이미지. 1장 이상 4장 이하, InputInfo와 동일한 구조 | ## 응답 파라미터 | 파라미터 | 타입 | 필수 여부 | 예시 | 설명 | | --------- | ------ | ----- | ---------------------------------------------------------- | -------------------------------------------- | | 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/tryon/result.jpeg` | 결과 이미지의 COS 경로 | ## 호출 예시 ```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)) # AI 피팅 태스크 제출 (모델 1장 + 의류 1장) params = { "InputInfo": { "Type": "URL", "UrlInputInfo": {"Url": "https://example.com/model.jpg"} }, "OutputStorage": { "Type": "COS", "CosOutputStorage": {"Bucket": "mybucket-125xxx", "Region": "ap-guangzhou"} }, "OutputDir": "/output/tryon/", "ImageTask": { "AiTryOnConfig": { "Model": "WAND-tryon-1.0-flash", "Resolution": "1K" } }, "AddOnParameter": { "ImageSet": [ { "Image": { "Type": "URL", "UrlInputInfo": {"Url": "https://example.com/cloth.jpg"} } } ] } } req = models.ProcessImageRequest() req.from_json_string(json.dumps(params)) resp = client.ProcessImage(req) print(resp.to_json_string()) ``` ```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-b8dac8f326214464acef88afef9002d4", "RequestId": "3c140219-cfe9-470e-b241-907877d6fb03" } } ``` DescribeImageTaskDetail 조회 결과: ```json theme={null} { "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/tryon/result.jpeg", "cos_uri": "cos://mps-bucket-125xxx/output/tryon/result.jpeg", "url": "https://mps-bucket-125xxx.cos.ap-guangzhou.myqcloud.com/output/tryon/result.jpeg" } ] } ``` ## 주의사항 의류 이미지는 1장 이상 4장 이하입니다. 4장을 초과하면 태스크를 제출할 수 없습니다. 속옷, 란제리 등 특수 카테고리는 `Prompt`로 장면을 명시하고(예: `lingerie try-on`) 의류 이미지를 1장만 전달합니다. 장면 구분용 전용 파라미터는 없으며 `Prompt`로만 표현합니다. `Status`가 `FINISH`여도 성공을 의미하지 않습니다. `ErrMsg`가 비어 있는지 반드시 함께 확인합니다. 이 기능은 `ScheduleId`로 시나리오를 구분하지 않습니다. `ImageTask.AiTryOnConfig`를 사용하는 신규 API 구조입니다. URL 입력은 공개 접근이 가능해야 하고, COS 입력은 MPS 서비스에 해당 Bucket의 읽기 권한이 있어야 합니다. 모델 이미지와 의류 이미지는 URL과 COS를 혼합해서 지정할 수 있습니다.