기능 · 마네킹 생성
AI 마네킹 생성 API 자체 모델용
한 줄 요약
Photta의 마네킹 생성 API는 선택한 속성을 기반으로 실사 수준의 AI 모델을 생성하고 재사용 가능한 마네킹 id를 반환하며 4 credits가 차감됩니다. 두 가지 빌더(의류용 빌더, 주얼리 클로즈업 특화 빌더)를 제공합니다.
- 일반적인 소요 시간: 30-60s
- 크레딧: 4 크레딧
- 처리 방식: 비동기, 폴링
- 제한 사항: 600 requests/min
- 인증: Bearer 키
이 페이지의 모든 수치는 다음 출처를 기반으로 합니다: Photta API 문서 · 확인 완료
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/mannequins/generate \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"category": "Female",
"ethnicity": "east_asian_korean",
"age": "late_20s",
"skin_tone": "light_medium",
"expression": "neutral",
"hair_style": "long_straight",
"hair_color": "black",
"body_type": "slim",
"height": "average"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/mannequins/generate", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"category": "Female",
"ethnicity": "east_asian_korean",
"age": "late_20s",
"skin_tone": "light_medium",
"expression": "neutral",
"hair_style": "long_straight",
"hair_color": "black",
"body_type": "slim",
"height": "average"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/mannequins/generate",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"category": "Female",
"ethnicity": "east_asian_korean",
"age": "late_20s",
"skin_tone": "light_medium",
"expression": "neutral",
"hair_style": "long_straight",
"hair_color": "black",
"body_type": "slim",
"height": "average"
},
)
data = res.json()["data"] # data["id"], data["status"]한눈에 보기
한눈에 보기
- 엔드포인트
- POST /api/v1/mannequins/generate
- 인증
- Bearer API 키
- 처리 방식
- 비동기 — 상태 엔드포인트 폴링
- 일반적인 소요 시간
- 30-60s
- 크레딧
- 4 크레딧
- 입력 제한
- 이미지당 최대 10 MB; JPEG, PNG, WebP
- 멱등성
- 아니요
요청 및 응답
요청
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/mannequins/generate \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"category": "Female",
"ethnicity": "east_asian_korean",
"age": "late_20s",
"skin_tone": "light_medium",
"expression": "neutral",
"hair_style": "long_straight",
"hair_color": "black",
"body_type": "slim",
"height": "average"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/mannequins/generate", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"category": "Female",
"ethnicity": "east_asian_korean",
"age": "late_20s",
"skin_tone": "light_medium",
"expression": "neutral",
"hair_style": "long_straight",
"hair_color": "black",
"body_type": "slim",
"height": "average"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/mannequins/generate",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"category": "Female",
"ethnicity": "east_asian_korean",
"age": "late_20s",
"skin_tone": "light_medium",
"expression": "neutral",
"hair_style": "long_straight",
"hair_color": "black",
"body_type": "slim",
"height": "average"
},
)
data = res.json()["data"] # data["id"], data["status"]202 Accepted / 완료됨
{
"data": {
"id": "mmk_r4s5t6",
"status": "processing",
"category": "Female",
"credits_used": 4,
"created_at": "2026-04-10T14:00:00Z"
},
"request_id": "req_mnk002"
}{
"data": {
"id": "mmk_r4s5t6",
"status": "completed",
"mannequin": {
"id": "mnk_v7w8x9",
"name": "Generated Mannequin",
"gender": "female",
"thumbnail_url": "https://cdn.photta.app/mannequins/mnk_v7w8x9-thumb.jpg"
},
"credits_used": 4,
"created_at": "2026-04-10T14:00:00Z",
"completed_at": "2026-04-10T14:00:42Z",
"duration_ms": 42000
},
"request_id": "req_mnk003"
}요청 파라미터
category타입: string필수
Mannequin category.
값:FemaleMaleGirlChildBoyChildethnicity타입: string
Ethnic appearance.
값:east_asian_koreaneast_asian_chinesesoutheast_asiansouth_asiannordicwestern_europeaneastern_europeanmediterraneanafricanafrican_americanmiddle_easternlatin_americanbrazilianmixed_asian_europeanpolynesianage타입: string
Age range.
값:early_20slate_20searly_30slate_30s40s50sbaby_1toddler_2_4young_5_7child_8_10preteen_11_13skin_tone타입: string
Skin tone.
값:lightlight_mediummediummedium_darkdarkface_shape타입: string
Face shape.
값:ovalsquareroundheartoblongdiamondeye_color타입: string
Eye color.
값:browndark_brownblackbluegreenhazelgrayambereye_shape타입: string
Eye shape.
값:almondroundmonolidhoodedupturneddownturnedexpression타입: string
Facial expression.
값:neutralsoft_smilewarm_smileseriousconfidentfriendlyfacial_hair타입: string
Facial hair style (Male only).
값:nonelight_stubblemedium_stubbleshort_beardfull_beardgoateemustachemakeup타입: string
Makeup style (Female only).
값:naturalminimalsoft_glamprofessionaleditorialhair_style타입: string
Hair style. Available options depend on category — use /options endpoint.
hair_color타입: string
Hair color.
값:blackdark_brownmedium_brownlight_brownauburnredblondeplatinum_blondegraywhitehair_texture타입: string
Hair texture.
값:straightwavycurlycoilybody_type타입: string
Body type. Options depend on category — use /options endpoint.
height타입: string
Height.
값:shortaveragetallglasses타입: string
Glasses.
값:noneeyeglassessunglassesfreckles타입: string
Freckles.
값:nonelightprominentpiercings타입: string
Piercings.
값:noneearnosemultiple
오류
- 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는 웹훅을 전송하지 않습니다.
속성을 입력하면 재사용 가능한 모델이 출력됩니다
옵션을 확인하고, 속성을 선택해 전송한 뒤, 폴링을 거쳐 id를 재사용하세요.
단계 1
API 키 생성
마네킹 생성은 다른 모든 Photta 기능과 동일한 인증 정보 및 credit 잔액을 사용합니다.
단계 2
옵션 카탈로그 조회
GET `/api/v1/mannequins/generate/options`는 카테고리별로 달라지는 `hair_style` 및 `body_type` 목록을 포함하여 허용되는 모든 값을 반환합니다. enum 값을 하드코딩하지 말고 이 데이터를 기반으로 폼을 구성하세요.
단계 3
마네킹 생성 요청(POST)
`category`(`Female`, `Male`, `GirlChild`, `BoyChild`)와 함께 17가지 선택 속성(인종, 나이, 피부 톤, 얼굴형 및 눈 모양, 표정, 수염, 메이크업, 헤어, 체형, 키, 안경, 주근깨, 피어싱)을 포함하여 POST `/api/v1/mannequins/generate`를 호출하세요.
단계 4
작업이 완료될 때까지 폴링
`data.status`가 `completed` 또는 `failed`가 될 때까지 3초마다 GET `/api/v1/mannequins/generate/:id`를 호출하세요. 일반적인 완료 시간은 30초에서 60초입니다.
단계 5
마네킹 재사용
완료된 응답 본문에는 고유 id를 가진 `mannequin` 객체가 포함됩니다. 이후 try-on 또는 아이웨어 작업 시 이 id를 `mannequin_id`로 전달하면 모든 컷에서 동일한 얼굴이 유지됩니다.
Node.js, Python, cURL로 확인하는 동일한 endpoint
Node.js
Node.js 환경의 AI 마네킹 생성 API
네이티브 fetch를 사용하여 Node.js 백엔드에서 Photta의 aI 마네킹 생성 API 기능을 호출하세요. SDK는 필요 없습니다: 키를 저장하고 작업을 제출한 뒤 결과를 폴링하면 됩니다.
읽기Python
Python 환경의 AI 마네킹 생성 API
requests 라이브러리를 사용하여 Python에서 Photta의 aI 마네킹 생성 API를 호출하세요. 30줄짜리 래퍼이자 httpx를 통한 비동기 지원이 가능하며, Django, FastAPI, Celery에서 원활하게 동작합니다.
읽기cURL
cURL 기반 AI 마네킹 생성 API
cURL을 사용해 셸에서 Photta의 aI 마네킹 생성 API 기능을 직접 호출하세요. 제출, polling, 다운로드까지 — 모든 스니펫은 스크립트 파이프라인 구축을 위해 jq와 연동됩니다.
읽기
개발자가 모델 생성 전에 자주 묻는 질문
AI 마네킹이란 무엇인가요?
캐스팅 대신 외형 속성을 직접 지정하여 생성한 모델입니다. id 형태로 반환되므로 동일한 얼굴, 헤어, 체형으로 카탈로그 내 모든 의류를 착용할 수 있습니다.
마네킹 생성 비용은 얼마인가요?
의류 빌더와 주얼리 빌더 모두 4 credits입니다. 생성된 기존 마네킹을 이후 촬영에 재사용할 때는 추가 비용이 들지 않으며, 모델이 아닌 try-on 비용만 지불하면 됩니다.
어떤 속성을 설정할 수 있나요?
`category`는 필수 항목입니다. 그 외 속성(인종, 나이, 피부 톤, 얼굴형, 눈 색상 및 모양, 표정, 수염, 메이크업, 헤어스타일, 색상 및 질감, 체형, 키, 안경, 주근깨, 피어싱)은 모두 선택 사항입니다. 허용되는 값은 옵션 endpoint에 나열되어 있습니다.
주얼리 빌더는 어떤 용도인가요?
POST `/api/v1/mannequins/jewelry/generate`는 주얼리 클로즈업 작업에 특화된 모델을 생성합니다. 전신 속성 대신 `jewelry_type`, `shot_type`, `camera_angle`, `background`, `lighting`을 전달받아 목선, 귀, 손 등이 근접 촬영에서도 자연스럽게 표현됩니다.
여러 촬영에서 동일한 모델을 재사용할 수 있나요?
네 — 바로 그것이 이 endpoint의 핵심 목적입니다. 생성된 마네킹 id는 의류 try-on, 주얼리 try-on, 아이웨어 스튜디오에서 `mannequin_id`로 전달하여 사용할 수 있습니다.
결과는 어떻게 폴링하나요?
`data.status`가 `completed` 또는 `failed`가 될 때까지 3초마다 GET `/api/v1/mannequins/generate/: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 공식 렌더링 파이프라인을 활용하세요.
엔드포인트 보기빌드
앱에 가상 try-on 기능 구축하기
Photta API를 사용해 가상 try-on 기능을 배포하기 위한 엔드투엔드 레시피: 업로드, 제출, 워커에서의 polling, 결과 렌더링. TypeScript + 서버 전용 패턴.
엔드포인트 보기비교
Photta vs Fitroom — 패션 API에 적합한 솔루션 선택하기
endpoint, 호출당 credit 비용, 가격 모델 및 연동 범위를 기준으로 Photta와 Fitroom을 비교했습니다. 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 스니펫을 붙여넣기만 하면, 커피가 다 내려지기도 전에 첫 번째 모델 착용 컷을 받아볼 수 있습니다.
- 30-60s
- 4 크레딧
- 비동기, 폴링
- 600 requests/min
- Bearer 키