기능 · 의류

가상 착용(Virtual try-on) API 의류용

한 줄 요약

Photta의 가상 착용(virtual try-on) API는 바닥에 펼친 의류 이미지와 마네킹 ID, 포즈 ID를 받아 2K 또는 4K 모델 착용 컷을 반환합니다. 작업을 POST하고, 3~5초마다 폴링하여, status가 completed가 되면 다운로드하세요.

API 키 발급받기 문서 보기

일반적인 소요 시간: 1.5–4 min
크레딧: 2K에서 5 크레딧 · 4K에서 6 크레딧
처리 방식: 비동기, 폴링
제한 사항: 600 requests/min
인증: Bearer 키

이 페이지의 모든 수치는 다음 출처를 기반으로 합니다: Photta API 문서 · 확인 완료 2026-09-10

POST/api/v1/tryon/apparel

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

const res = await fetch("https://api.photta.app/api/v1/tryon/apparel", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "product_type": "top",
    "product_images": [
      "https://cdn.yourstore.com/products/shirt-front.jpg"
    ],
    "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
    "product_category": "t_shirt",
    "mannequin_id": "mnk_f3a9b1",
    "pose_id": "pose_c2d4e5",
    "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
    "lock_background": true,
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "body_size": "M",
    "expression": "neutral",
    "user_instruction": "Keep the collar pattern crisp and centered."
  }),
});
const { data } = await res.json(); // data.id, data.status

import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/tryon/apparel",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "product_type": "top",
      "product_images": [
        "https://cdn.yourstore.com/products/shirt-front.jpg"
      ],
      "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
      "product_category": "t_shirt",
      "mannequin_id": "mnk_f3a9b1",
      "pose_id": "pose_c2d4e5",
      "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
      "lock_background": True,
      "resolution": "2K",
      "aspect_ratio": "3:4",
      "body_size": "M",
      "expression": "neutral",
      "user_instruction": "Keep the collar pattern crisp and centered."
    },
)
data = res.json()["data"]  # data["id"], data["status"]

A garment rendered on an AI model by the apparel try-on API — 출력 예시

한눈에 보기

엔드포인트: POST /api/v1/tryon/apparel
인증: Bearer API 키
처리 방식: 비동기 — 상태 엔드포인트 폴링
일반적인 소요 시간: 1.5–4 min
크레딧: 2K에서 5 크레딧 · 4K에서 6 크레딧
화면비: 3:4 · 1:1 · 4:3 · 9:16 · 16:9
입력 제한: 이미지당 최대 10 MB; JPEG, PNG, WebP
멱등성: 아니요

요청 및 응답

요청

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

const res = await fetch("https://api.photta.app/api/v1/tryon/apparel", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "product_type": "top",
    "product_images": [
      "https://cdn.yourstore.com/products/shirt-front.jpg"
    ],
    "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
    "product_category": "t_shirt",
    "mannequin_id": "mnk_f3a9b1",
    "pose_id": "pose_c2d4e5",
    "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
    "lock_background": true,
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "body_size": "M",
    "expression": "neutral",
    "user_instruction": "Keep the collar pattern crisp and centered."
  }),
});
const { data } = await res.json(); // data.id, data.status

import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/tryon/apparel",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "product_type": "top",
      "product_images": [
        "https://cdn.yourstore.com/products/shirt-front.jpg"
      ],
      "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
      "product_category": "t_shirt",
      "mannequin_id": "mnk_f3a9b1",
      "pose_id": "pose_c2d4e5",
      "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
      "lock_background": True,
      "resolution": "2K",
      "aspect_ratio": "3:4",
      "body_size": "M",
      "expression": "neutral",
      "user_instruction": "Keep the collar pattern crisp and centered."
    },
)
data = res.json()["data"]  # data["id"], data["status"]

202 Accepted / 완료됨

{
  "data": {
    "id": "try_abc123",
    "status": "processing",
    "product_type": "top",
    "mannequin_id": "mnk_f3a9b1",
    "pose_id": "pose_c2d4e5",
    "lock_background": true,
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 5,
    "created_at": "2026-04-10T12:00:00Z"
  },
  "request_id": "req_xyz789"
}

{
  "data": {
    "id": "try_abc123",
    "status": "completed",
    "product_type": "top",
    "mannequin_id": "mnk_f3a9b1",
    "pose_id": "pose_c2d4e5",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "output_url": "https://cdn.photta.app/generated/try_abc123.jpg",
    "thumbnail_url": "https://cdn.photta.app/generated/try_abc123-thumb.jpg",
    "credits_used": 5,
    "created_at": "2026-04-10T12:00:00Z",
    "completed_at": "2026-04-10T12:01:15Z",
    "duration_ms": 75000
  },
  "request_id": "req_abc001"
}

요청 파라미터

필드설명

product_type

타입: string필수

Type of garment.

topbottomtop_and_bottomone_piece

product_images

타입: array[string]필수

Array of image URLs or base64 data URIs. The first entry is the FRONT image and is required. Not used when product_type is "top_and_bottom".

product_back_image

타입: string

Optional URL or base64 data URI for the BACK of the garment. When supplied, the pipeline auto-switches to the back image whenever the selected pose is back-facing (Back / BackCloseUp). Not used when product_type is "top_and_bottom".

top_image

타입: string

Front image of the top garment. Required when product_type is "top_and_bottom".

top_back_image

타입: string

Optional back image of the top garment. Auto-selected on back-facing poses when present.

bottom_image

타입: string

Front image of the bottom garment. Required when product_type is "top_and_bottom".

bottom_back_image

타입: string

Optional back image of the bottom garment. Auto-selected on back-facing poses when present.

mannequin_id

타입: string필수

ID of the mannequin to wear the garment. Use GET /api/v1/mannequins to list available options.

pose_id

타입: string필수

ID of the pose. Use GET /api/v1/poses to list available options. The pose dictates the framing of the output — what's in frame, whether the face/feet are visible, full body vs half body, etc.

background

타입: string

Optional URL or base64 data URI to a background photo. Anything that is not a URL or data: URI is rejected with HTTP 400. When omitted, an editorial neutral backdrop is used.

lock_background

타입: boolean

When true, the supplied background image is reproduced faithfully (locked) instead of being treated as loose inspiration. Requires the background field — returns 400 if set without a background. Echoed back in the response object.

= false

resolution

타입: string

Output resolution. 4K cannot be combined with aspect_ratio 1:1 — that combination returns 400.

= 2K

2K4K

aspect_ratio

타입: string

Output aspect ratio. 1:1 cannot be combined with resolution 4K — that combination returns 400.

= 3:4

3:41:14:39:1616:9

body_size

타입: string

Body size of the mannequin.

= M

XSSMLXLXXL

expression

타입: string

Facial expression.

= neutral

neutralhappyserioussmiling

footwear_url

타입: string

URL or base64 of a custom footwear image. The pipeline always stages the footwear when supplied; the prompt's pose-authority block decides whether to render it (poses that don't show feet drop it cleanly).

user_instruction

타입: string

Free-form refinement, e.g. "preserve the seam pattern across the shoulder", "keep the collar contrast strong". Capped at 500 characters server-side; longer strings are silently truncated. Useful for brand-specific details that need an extra nudge.

product_category

타입: string

Optional silhouette anchor for the garment (e.g. "t_shirt", "jeans", "blazer", "midi_dress"). Helps disambiguate the structure of the garment when the silhouette is ambiguous from the photo alone. Used for product_type "top", "bottom", and "one_piece".

top_category

타입: string

Silhouette anchor for the top half. Only valid when product_type is "top_and_bottom".

bottom_category

타입: string

Silhouette anchor for the bottom half. Only valid when product_type is "top_and_bottom".

length

타입: string

Garment length key for product_type "top", "bottom", or "one_piece". List available values with GET /api/v1/garment-attributes?type=length&garment_type={product_type}.

fit

타입: string

Garment fit key for product_type "top", "bottom", or "one_piece". List available values with GET /api/v1/garment-attributes?type=fit&garment_type={product_type}.

top_length

타입: string

Top length key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=length&garment_type=top.

top_fit

타입: string

Top fit key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=fit&garment_type=top.

bottom_length

타입: string

Bottom length key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=length&garment_type=bottom.

bottom_fit

타입: string

Bottom fit key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=fit&garment_type=bottom.

오류

상태타입의미

400invalid_request_error: The request is malformed or contains invalid parameters.
401authentication_error: The API key is missing, invalid, or expired.
402insufficient_credits_error: Your account does not have enough credits.
404not_found_error: The requested resource does not exist.
409conflict_error: The request conflicts with current state — e.g. your concurrent-batch cap is reached.
429rate_limit_error: Too many requests. Slow down and retry.Retry-After: 30
500api_error: An internal server error occurred. Retry later.

제한 사항

API 키당 분당 600회 요청 (고정 윈도우 방식이며, 제한은 모든 요금제에서 동일합니다)
429 응답에는 Retry-After: 30초 헤더가 포함됩니다
이미지당 최대 10 MB
지원 형식: JPEG, PNG, WebP
요금제별 동시 배치 수: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
폴링 전용 — API는 웹훅을 전송하지 않습니다.

5단계, 제품 사진 1장

마네킹을 고르고 작업을 제출한 뒤, 완료될 때까지 폴링하여 결과를 다운로드하세요.

단계 1
API 키 발급
ai.photta.app에서 가입 후 Developers 탭을 열고 API 키 생성을 클릭하세요. 프로덕션 라이브 키는 `photta_live_`로 시작합니다. 키는 `PHOTTA_API_KEY`에 저장하고 절대 커밋하지 마세요.
단계 2
마네킹 및 포즈 선택
GET `/api/v1/mannequins`로 사용 가능한 목록을 조회합니다. 구도 선택은 GET `/api/v1/poses`를 사용합니다. 두 ID 모두 try-on 요청에 포함됩니다.
단계 3
try-on 작업 POST 전송
`product_type`, `product_images`, `mannequin_id`, `pose_id`와 선택적 `resolution`, `aspect_ratio`를 포함해 `/api/v1/tryon/apparel`로 POST 요청을 보냅니다. API는 생성 ID와 함께 202 Accepted를 반환합니다.
단계 4
작업 완료 시까지 폴링
3초마다 GET `/api/v1/tryon/apparel/:id`를 호출합니다. `data.status`가 `completed`로 바뀌면 페이로드에 `output_url` 및 `thumbnail_url`이 포함됩니다. 요청이 중단되는 일이 없도록 폴링 상한을 설정하세요.
단계 5
다운로드 및 영구 저장
`output_url`에서 바이트 데이터를 fetch하여 자체 오브젝트 스토리지에 저장하세요. CDN URL은 안정적이지만 서비스 렌더링을 여기에 직접 의존해서는 안 됩니다.

Node.js, Python, cURL에서 동일한 엔드포인트 지원

의류 try-on 배포 전 엔지니어들이 자주 묻는 질문

Photta의 가상 try-on API는 무엇인가요?

바닥에 펼쳐놓은 제품 평면 컷과 마네킹 ID를 입력받아 실사 모델 착용 이미지를 반환하는 REST 엔드포인트입니다. Photta의 소비자용 앱과 동일한 파이프라인을 사용합니다. 상의, 하의, 상·하의 세트, 원피스 등 4가지 제품 유형을 지원합니다.

호출당 비용은 얼마인가요?

2K 결과물은 5 credits, 4K는 6 credits입니다. credits는 구독 시 기본 제공되며 추가 충전할 수 있습니다. 생성 실패 시에는 credits가 소모되지 않고 환불 처리됩니다.

생성에는 얼마나 걸리나요?

엔드투엔드 기준 통상 1.5분에서 4분 정도 소요됩니다. POST 요청은 1초 이내에 생성 ID를 반환하며, 폴링이 진행되는 동안 백그라운드에서 GPU 작업이 처리됩니다.

어떤 제품 유형이 지원되나요?

`top`, `bottom`, `top_and_bottom`, `one_piece`의 4가지 유형을 지원합니다. 유형마다 요구하는 `product_images` 형태가 다릅니다. 예를 들어 `top_and_bottom`은 `top_image`와 `bottom_image` URL이 모두 필요합니다.

자체 마네킹을 사용할 수 있나요?

네, 가능합니다. `POST /api/v1/mannequins`로 마네킹 사진을 업로드하거나 `POST /api/v1/mannequins/generate`로 새 AI 마네킹을 생성할 수 있습니다. 반환된 ID를 try-on 요청에 바로 사용할 수 있습니다.

결과값 폴링은 어떻게 구현하나요?

`data.status`가 `completed` 또는 `failed`가 될 때까지 3~5초마다 GET `/api/v1/tryon/apparel/:id`를 호출하세요. 시도 횟수 상한을 두는 것이 좋습니다. 3초 간격 120회면 문서상 안내된 처리 시간을 여유 있게 커버합니다.

5분 만에 API 체험하기

Photta API 키를 발급받고 위 cURL 스니펫을 붙여넣기만 하면, 커피가 다 내려지기도 전에 첫 번째 모델 착용 컷을 받아볼 수 있습니다.

계정 생성 후 API 키 발급받기 문서 보기

1.5–4 min
2K에서 5 크레딧 · 4K에서 6 크레딧
비동기, 폴링
600 requests/min
Bearer 키

가상 착용(Virtual try-on) API 의류용

한눈에 보기

요청 및 응답

요청 파라미터

오류

5단계, 제품 사진 1장

API 키 발급

마네킹 및 포즈 선택

try-on 작업 POST 전송

작업 완료 시까지 폴링

다운로드 및 영구 저장

Node.js, Python, cURL에서 동일한 엔드포인트 지원

의류 try-on 배포 전 엔지니어들이 자주 묻는 질문

관련 기능

5분 만에 API 체험하기