기능 · 고스트 마네킹

고스트 마네킹 API 투명 마네킹 제품 사진용

한 줄 요약

Photta의 고스트 마네킹 API는 마네킹 착용 의류 사진을 입력받아 의류 내부가 복원된 인비저블 마네킹 이미지를 반환합니다. 3d 또는 flat_lay 스타일을 선택하고, POST 요청을 보낸 뒤, 3초마다 폴링하여 completed 시 다운로드하세요.

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

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

POST/api/v1/ghost-mannequin
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
  "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
  "image_side": "front",
  "angle": "side",
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, cream interior lining",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')
A garment shown without its mannequin by the ghost mannequin API
출력 예시

한눈에 보기

한눈에 보기

엔드포인트
POST /api/v1/ghost-mannequin
인증
Bearer API 키
처리 방식
비동기 — 상태 엔드포인트 폴링
일반적인 소요 시간
1.5–4 min
크레딧
2K에서 4 크레딧 · 4K에서 5 크레딧
화면비
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/ghost-mannequin \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
  "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
  "image_side": "front",
  "angle": "side",
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, cream interior lining",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / 완료됨

{
  "data": {
    "id": "gm_d4e5f6",
    "status": "processing",
    "style": "3d",
    "angle": "side",
    "background_color": "white",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 4,
    "created_at": "2026-04-10T16:00:00Z"
  },
  "request_id": "req_gm001"
}

요청 파라미터

product_image

타입: string필수

URL or base64 data URI of the garment photo (front or back, on a mannequin or flat).

back_image

타입: string

URL or base64 data URI of the opposite side — helps the AI reconstruct the interior of the garment for a more realistic 3D effect.

image_side

타입: string

Which side product_image represents.

= front

값: frontback
angle

타입: string

Camera angle for the output. "side" is worth calling out: the side view is reconstructed from the front photo (plus the back photo when provided), giving you a third catalog view without a third photoshoot — and it works well even on textured garments (crochet, lace, embroidery).

= straight

값: straightbackside
style

타입: string

Output style: "3d" (ghost mannequin with 3D body shape) or "flat_lay" (garment laid flat, mannequin removed).

= 3d

값: 3dflat_lay
background_color

타입: string

Background color.

= white

값: whitegraybeigeblack
resolution

타입: string

Output resolution. "2K" costs 4 credits per image; "4K" costs 5 credits per image. 4K is produced natively in a single generation — pick it upfront; the resolution cannot be changed after creation. Note: 4K cannot be combined with aspect_ratio 1:1 — that combination returns 400.

= 2K

값: 2K4K
aspect_ratio

타입: string

Output aspect ratio. Note: 1:1 is not available at 4K resolution — 1:1 combined with 4K returns 400.

= 3:4

값: 3:41:14:39:1616:9
user_instruction

타입: string

Optional free-form note, max 400 characters (anything longer is silently truncated). A guarded steer for ambiguous rendering choices — e.g. "closed front", "cream interior lining", "buttoned up" — it never overrides the source garment, brand label, or structural reconstruction, and it is explicitly NOT a determinism/seed control.

brand_label_id

타입: string

Brand label UUID returned by the Brand Labels API. Applied to the generated garment when present. API v1 request fields use snake_case; use brand_label_id.

오류

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는 웹훅을 전송하지 않습니다.

사진 1장 입력으로 투명 마네킹 사진 1장 출력

소스 업로드, 스타일 선택, 요청 전송, 폴링, 다운로드.

  1. 단계 1

    API 키 생성

    고스트 마네킹은 다른 모든 Photta 기능과 동일한 자격 증명을 사용합니다 — 단 하나의 키, 단 하나의 크레딧 잔액.

  2. 단계 2

    소스 사진 업로드

    `product_image`에 공개 URL 또는 base64 데이터 URI를 전달합니다. 뒷면 뷰가 있는 경우 `back_image`를 추가하세요. 이미지당 최대 10 MB까지 JPEG, PNG 및 WebP를 지원합니다.

  3. 단계 3

    고스트 마네킹 작업 POST 요청

    `product_image`, `style`(`3d` 또는 `flat_lay`) 및 선택 사항인 `angle`, `background_color`, `resolution`과 함께 `/api/v1/ghost-mannequin`으로 POST 요청을 보냅니다. 완료 신호는 폴링으로만 확인 가능합니다 — API는 웹훅을 전송하지 않습니다.

  4. 단계 4

    작업이 완료될 때까지 폴링

    `data.status`가 `completed` 또는 `failed`가 될 때까지 3초마다 GET `/api/v1/ghost-mannequin/:id`를 호출합니다. 일반적인 완료 시간은 1.5분에서 4분입니다.

  5. 단계 5

    다운로드 및 저장

    결과물은 마네킹이 제거되고 의류 내부가 복원된 PNG 형식입니다. PDP 고스트 컷, 3D 느낌의 제품 갤러리 및 플랫레이 인서트에 적합합니다.

고스트 마네킹 적용 전 개발자들이 자주 묻는 질문

고스트 마네킹 사진이란 무엇인가요?

의류가 보이지 않는 몸에 떠 있는 것처럼 연출하여 형태와 내부 구조를 동시에 보여주는 PDP 연출 방식입니다. 전통적으로는 여러 장의 스튜디오 촬영본을 합성하지만, Photta의 API는 마네킹 착용 사진 1장으로 단 한 번의 호출을 통해 이를 생성합니다.

고스트 마네킹의 비용은 얼마인가요?

2K에서 4 credits, 4K에서 5 credits입니다 — try-on보다 각 티어별로 1 크레딧 저렴합니다. 실패한 작업은 자동으로 환불됩니다.

3D 스타일과 플랫레이 스타일의 차이점은 무엇인가요?

`3d` 스타일은 마네킹의 3차원 입체 형태를 유지합니다 — 의류의 볼륨이 유지되고 어깨와 소매가 자연스럽게 표현되며 내부가 복원됩니다. `flat_lay`는 의류를 깔끔한 2D 레이아웃으로 평평하게 펼쳐 놓아, 일관된 정면 형태를 요구하는 캡슐 컬렉션이나 마켓플레이스 등록에 적합합니다.

여러 장의 사진을 배치 처리할 수 있나요?

네, 가능합니다. 소스 이미지 배열과 함께 `/api/v1/ghost-mannequin/batch`로 POST 요청을 보내세요. 응답으로 배치 ID와 개별 항목별 생성 ID가 반환됩니다. 전체 상태를 확인하려면 `/api/v1/ghost-mannequin/batch/:id`를 폴링하고, 개별 항목을 각각 폴링할 수도 있습니다.

내부 솔기와 라벨도 보존되나요?

네 — 모델이 임의의 표면을 만들어내는 대신 의류 내부(넥라인 안쪽, 소매 안쪽, 허리 밴드 안감)를 정밀하게 재구성합니다. 원본 사진에 보이는 태그와 프린트 라벨도 가능한 한 그대로 유지됩니다.

결과는 어떻게 폴링하나요?

3초마다 GET `/api/v1/ghost-mannequin/:id`를 호출하세요. 배치 작업은 종합 상태와 개별 항목 내역을 반환하는 상위 엔드포인트를 폴링합니다.

관련 기능

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

5분 만에 API 체험하기

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

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