요청 방법
| 항목 | 값 |
|---|---|
| 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 경로 |
호출 예시
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))
# 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())
# 태스크 결과 조회
query = models.DescribeImageTaskDetailRequest()
query.from_json_string(json.dumps({"TaskId": "<TaskId>"}))
detail = client.DescribeImageTaskDetail(query)
print(detail.to_json_string())
응답 예시
ProcessImage 응답:{
"Response": {
"TaskId": "2600007696-WorkflowTask-b8dac8f326214464acef88afef9002d4",
"RequestId": "3c140219-cfe9-470e-b241-907877d6fb03"
}
}
{
"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를 혼합해서 지정할 수 있습니다.