기능 · 고스트 마네킹
고스트 마네킹 API 투명 마네킹 제품 사진용
한 줄 요약
Photta의 고스트 마네킹 API는 마네킹 착용 의류 사진을 입력받아 의류 내부가 복원된 인비저블 마네킹 이미지를 반환합니다. 3d 또는 flat_lay 스타일을 선택하고, POST 요청을 보낸 뒤, 3초마다 폴링하여 completed 시 다운로드하세요.
- 일반적인 소요 시간: 1.5–4 min
- 크레딧: 2K에서 4 크레딧 · 4K에서 5 크레딧
- 처리 방식: 비동기, 폴링
- 제한 사항: 600 requests/min
- 인증: Bearer 키
이 페이지의 모든 수치는 다음 출처를 기반으로 합니다: Photta API 문서 · 확인 완료
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')const res = await fetch("https://api.photta.app/api/v1/ghost-mannequin", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/ghost-mannequin",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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"
},
)
data = res.json()["data"] # data["id"], data["status"]
한눈에 보기
한눈에 보기
- 엔드포인트
- 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')const res = await fetch("https://api.photta.app/api/v1/ghost-mannequin", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/ghost-mannequin",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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"
},
)
data = res.json()["data"] # data["id"], data["status"]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"
}{
"data": {
"id": "gm_d4e5f6",
"status": "completed",
"style": "3d",
"angle": "side",
"background_color": "white",
"resolution": "2K",
"aspect_ratio": "3:4",
"output_url": "https://cdn.photta.app/generated/gm_d4e5f6.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/gm_d4e5f6-thumb.jpg",
"credits_used": 4,
"created_at": "2026-04-10T16:00:00Z",
"completed_at": "2026-04-10T16:00:48Z",
"duration_ms": 48000
},
"request_id": "req_gm002"
}요청 파라미터
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
값:frontbackangle타입: 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
값:straightbacksidestyle타입: string
Output style: "3d" (ghost mannequin with 3D body shape) or "flat_lay" (garment laid flat, mannequin removed).
= 3d
값:3dflat_laybackground_color타입: string
Background color.
= white
값:whitegraybeigeblackresolution타입: 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
값:2K4Kaspect_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:9user_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.
오류
- 400
invalid_request_error - The request is malformed or contains invalid parameters.
- 401
authentication_error - The API key is missing, invalid, or expired.
- 402
insufficient_credits_error - Your account does not have enough credits.
- 404
not_found_error - The requested resource does not exist.
- 409
conflict_error - The request conflicts with current state — e.g. your concurrent-batch cap is reached.
- 429
rate_limit_error - Too many requests. Slow down and retry.Retry-After: 30
- 500
api_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
API 키 생성
고스트 마네킹은 다른 모든 Photta 기능과 동일한 자격 증명을 사용합니다 — 단 하나의 키, 단 하나의 크레딧 잔액.
단계 2
소스 사진 업로드
`product_image`에 공개 URL 또는 base64 데이터 URI를 전달합니다. 뒷면 뷰가 있는 경우 `back_image`를 추가하세요. 이미지당 최대 10 MB까지 JPEG, PNG 및 WebP를 지원합니다.
단계 3
고스트 마네킹 작업 POST 요청
`product_image`, `style`(`3d` 또는 `flat_lay`) 및 선택 사항인 `angle`, `background_color`, `resolution`과 함께 `/api/v1/ghost-mannequin`으로 POST 요청을 보냅니다. 완료 신호는 폴링으로만 확인 가능합니다 — API는 웹훅을 전송하지 않습니다.
단계 4
작업이 완료될 때까지 폴링
`data.status`가 `completed` 또는 `failed`가 될 때까지 3초마다 GET `/api/v1/ghost-mannequin/:id`를 호출합니다. 일반적인 완료 시간은 1.5분에서 4분입니다.
단계 5
다운로드 및 저장
결과물은 마네킹이 제거되고 의류 내부가 복원된 PNG 형식입니다. PDP 고스트 컷, 3D 느낌의 제품 갤러리 및 플랫레이 인서트에 적합합니다.
Node.js, Python 및 cURL에서 동일한 엔드포인트 사용
Node.js
Node.js 환경의 고스트 마네킹 API
네이티브 fetch를 사용하여 Node.js 백엔드에서 Photta의 고스트 마네킹 API 기능을 호출하세요. SDK는 필요 없습니다: 키를 저장하고 작업을 제출한 뒤 결과를 폴링하면 됩니다.
읽기Python
Python 환경의 고스트 마네킹 API
requests 라이브러리를 사용하여 Python에서 Photta의 고스트 마네킹 API를 호출하세요. 30줄짜리 래퍼이자 httpx를 통한 비동기 지원이 가능하며, Django, FastAPI, Celery에서 원활하게 동작합니다.
읽기cURL
cURL 기반 고스트 마네킹 API
cURL을 사용해 셸에서 Photta의 고스트 마네킹 API 기능을 직접 호출하세요. 제출, polling, 다운로드까지 — 모든 스니펫은 스크립트 파이프라인 구축을 위해 jq와 연동됩니다.
읽기
고스트 마네킹 적용 전 개발자들이 자주 묻는 질문
고스트 마네킹 사진이란 무엇인가요?
의류가 보이지 않는 몸에 떠 있는 것처럼 연출하여 형태와 내부 구조를 동시에 보여주는 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`를 호출하세요. 배치 작업은 종합 상태와 개별 항목 내역을 반환하는 상위 엔드포인트를 폴링합니다.
관련 기능
기능
가상 착용(Virtual try-on) API 의류용
의류를 AI 마네킹에 착용시키는 REST API입니다. 비동기식 처리, 1.5~4분의 생성 시간, 2K 기준 5 credits, 4K 기준 6 credits 소요. cURL, Node.js, Python 예제가 제공됩니다.
엔드포인트 보기기능
주얼리 try-on API 목걸이, 반지, 팔찌 및 귀걸이 지원
REST 방식으로 AI 모델에 목걸이, 반지, 팔찌, 귀걸이를 착용해 보세요. 2K 기준 5 credits, 내장 클로즈업 마네킹 제공, 반사광을 정밀하게 반영하는 Photta 공식 렌더링 파이프라인을 활용하세요.
엔드포인트 보기빌드
카탈로그용 고스트 마네킹 추출 자동화
야간 카탈로그 자동화 레시피: 어제의 상품 업데이트 추출, Photta 고스트 마네킹 API로 배치 제출, 상위 배치 폴링, 데이터베이스에 영구 저장.
엔드포인트 보기비교
Photta vs Pixazo — 자체 파이프라인인가 모델 애그리게이터인가
Photta와 Pixazo 비교: 퍼스트 파티 패션 파이프라인 vs 멀티 모델 애그리게이터. 엔드포인트, 지연 시간, 무료 티어 및 트레이드오프. 2026-04-19 기준 데이터.
엔드포인트 보기빠른 시작
5분 안에 첫 번째 Photta 이미지를 생성하세요.
회원가입, API 키 생성, 첫 cURL 호출 실행, 완료될 때까지 폴링, 결과 저장까지. 엔드투엔드로 문서화된 5단계 가이드입니다.
엔드포인트 보기레퍼런스
Photta API 오류
Photta API의 전체 오류 유형 목록과 상태 코드, 오류 본문 포맷, 그리고 재시도할 가치가 있는 오류에 대한 안내입니다.
엔드포인트 보기레퍼런스
Photta API rate limits
Photta API rate limit, 윈도우, Retry-After 헤더, polling 주기, 플랜별 동시성 상한선 등 API 문서에 명시된 모든 내용입니다.
엔드포인트 보기
이 페이지의 모든 수치는 다음 출처를 기반으로 합니다: Photta API 문서 · 확인 완료
5분 만에 API 체험하기
Photta API 키를 발급받고 위 cURL 스니펫을 붙여넣기만 하면, 커피가 다 내려지기도 전에 첫 번째 모델 착용 컷을 받아볼 수 있습니다.
- 1.5–4 min
- 2K에서 4 크레딧 · 4K에서 5 크레딧
- 비동기, 폴링
- 600 requests/min
- Bearer 키